Skip to main content

E-Receipts

An e-receipt is the digital version of a ticket or sales receipt. It is a payment voucher that you can give to your customer without requesting their tax information. This voucher includes all the sales information so that it can be invoiced if the customer requests it or alternatively can be included in a global invoice at the end of the month.

By creating a digital receipt in Facturapi, your customers will have access to a website where they can fill in their tax information and download their invoice (self-invoice portal).

You can also create a global invoice at the end of the month that includes all those receipts that were not invoiced (known as global invoice).

Create a receipt​

To see the descriptions of all the parameters, consult the complete reference of the method Create Receipt.

Optionally, you can associate a customer to the receipt by sending the customer field (either the ID of an existing customer or the customer object to create it).

const facturapi = new Facturapi('sk_test_API_KEY');
const receipt = await facturapi.receipts.create({
  folio_number: 1234,
  payment_form: Facturapi.PaymentForm.DINERO_ELECTRONICO,
  items: [{
    quantity: 1,
    product: {
      description: 'Ukelele',
      product_key: '60131324',
      price: 345.60,
      sku: 'ABC1234'
    }
  }]
});

Receipt customer​

A receipt can exist without an assigned customer. This state means the invoicing destination is not decided yet.

You can associate a customer when calling Create Receipt, by sending the customer field, or later with Assign or reassign customer to receipt. In both cases, you can send the ID of an existing customer or a customer object to create one.

curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
        "customer": "58e93bd8e86eb318b0197456"
      }'

Self-invoice portal​

When you create an e-receipt, you have the option to send it via email to your customer. This email will contain a link to a self-invoice portal where your customer can fill in their tax information and download their invoice.

For more information, see the article on Self-Invoice.

Ways to invoice receipts​

Open receipts can be invoiced to a specific customer or included in a global invoice to PUBLICO EN GENERAL.

  • Convert e-receipt to invoice creates an invoice for a single receipt. If you send customer, that customer is used as the invoice recipient and overrides the customer previously assigned to the receipt. If you omit customer, the receipt must already have an assigned customer.
  • Create invoice from multiple receipts creates an invoice for several receipts selected by key. If you send customer, that customer is used for every included receipt. If you omit customer, all receipts must already have the same assigned customer; if they have different customers or any receipt has no customer, the operation fails.
  • PDF preview for multiple receipts invoice and dry_run validate the same customer rules as real invoice creation, but do not persist changes.
  • Global invoice also groups multiple receipts, but always invoices them to the generic PUBLICO EN GENERAL customer. Included receipts are associated with that customer and their status changes to "invoiced_globally".

Global invoices with more than 5,000 receipts​

The global invoice limit is based on the number of included open receipts, not on the resulting items after they are grouped.

If a period contains more than 5,000 receipts, send limit_to_max_receipts: true. The request creates an invoice with up to 5,000 receipts and leaves the rest with status = "open". Repeat the same request, keeping the original date range and periodicity, until the API responds with null. This lets you split one period across multiple global invoices without changing its periodicity information.

If you omit this option, the API returns global_invoice_too_many_items and does not create a partial invoice.

Automate global invoices​

Organizations with the global invoice feature can enable automation through Edit receipt settings:

{
  "periodicity": "month",
  "activate_global_invoice": true
}

The automation processes each period after it ends, using the organization's time zone. You can change periodicity to reschedule future periods or send activate_global_invoice: false to pause it. Periods elapsed while automation is disabled are not automatically invoiced when it is enabled again.

Automatic and scheduled tasks can be monitored from Automatic global invoice in the Dashboard.

Group items when invoicing selected receipts​

The grouped_items_invoice setting groups equivalent items when invoicing multiple selected receipts, both through the API and the self-invoice portal. It is not used for global invoices.

Convert an e-receipt into an invoice​

With Convert e-receipt to invoice you can convert an e-receipt into an invoice for a specific customer. If the receipt already has an assigned customer, you can omit customer; if you send customer, that customer becomes the invoice recipient.

const invoice = await facturapi.receipts.invoice(receipt.id, {
  customer: {
    legal_name: 'Roger Watters',
    tax_id: 'ROWA121212A11',
    email: 'roger@pinkfloyd.com'
  },
  folio_number: 914,
  series: 'F'
});

Convert multiple receipts into one invoice​

Create invoice from multiple receipts creates a single invoice from open receipts selected by key.

You can also send dry_run: true to validate the operation and get a summary without creating the invoice, or use the PDF preview.