Overview

When a new invoice is generated, Lago also sends an invoice.created webhook (learn more).

When an invoice is linked to an add-on, another type of webhook is sent, called invoice.one_off_created.

​

Invoice object

Invoices include (but are not limited to):

• Invoice number;
• Billing period;
• Customer information;
• Fees; and
• Taxes.

You can download invoices or use the invoice object to create your own invoice template.

​

Invoice numbering

With Lago, invoice numbering is generated every time an invoice is finalized. You have the flexibility to customize how invoice numbers are incremented to align with your organizational structure and customer management approach.

• Invoice numbering per customer: This setting is designed to increment invoice numbers individually for each customer. It ensures that each customer has their own unique sequence of invoice numbers, separate from other customers. This approach is ideal for maintaining distinct and isolated numbering patterns for each customer, aiding in clear tracking and accounting processes.
• Invoice numbering across the organization: Opting for this method applies a global sequence for incrementing invoice numbers across your entire organization. Instead of having individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers, simplifying the invoice management process. In that case, invoices are incremented per month (dynamic value used is YYYYMM).

​

Invoice prefix customization

Lago also allows you to customize the prefix for documents, including invoices and credit notes. By default, Lago auto-generates this prefix by combining the first three letters of your organization’s name with the last four digits of your organization ID. However, you have the flexibility to fully customize this field to better align with your organization’s branding or numbering conventions. This feature ensures clarity and consistency across your documents while allowing you to maintain a professional and personalized appearance in your invoicing system.

​

Custom invoice grouping

Grouping invoice line items in a way that provides clearer insight for your customers can be more beneficial than sticking to the default charge setup in Lago.

For instance, as an AI service provider, you might prefer to regroup all fees associated to one charge by a specific model used by a customer, without the need to individually list each model in Lago.

When setting up a charge with a standard charge model, you can use model_name as an event property in the grouped_by attribute. If every event reported to Lago includes a model_name, Lago is capable of adjusting your invoice so that charges are organized under the respective model name for that particular charge. Consequently, Lago will also automatically allocate the usage costs for each model.

You can specify multiple grouped_by keys for your charge; the order you set them in dictates how they will be displayed on the invoice, affecting the presentation of charges.

​

Finalize empty invoices

By default, Lago finalizes all invoices, including those with a final amount of zero. However, some customers may prefer to skip empty invoices to avoid unnecessary accounting documents. In such cases, you can configure Lago to skip the issuance of invoices when they are empty.

​

Empty invoices definition

Lago considers an invoice empty only if it has no line items before applying coupons or discounts. If an applicable discount reduces an invoice’s total to zero, Lago will not consider this invoice as part of the empty invoices scope and will still finalize it.

​

Organization level

The finalize_zero_amount_invoice setting is set to true by default. At the organization level, you can change this value to false at any time. When set to false, empty invoices won’t be finalized for any customers unless specifically overridden at the customer level.

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/organizations" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "organization": {
      "country": "US",
      "finalize_zero_amount_invoice": true
    }
  }'

​

Customer level

By default, new customers inherit the finalize_zero_amount_invoice setting from the organization. You can override this setting for individual customers to meet specific needs.

The available options are:

• inherit: Follows the organization’s setting;
• skip: Skips finalizing empty invoices; or
• finalize: Always finalizes invoices, even if empty.

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "hooli_12345",
      "address_line1": "100 Fintech Devcon Street",
      "city": "Austin",
      "country": "US",
      "email": "hooli@fintech.com",
      "legal_number": "54321",
      "name": "Hooli 12345",
      "state": "Texas",
      "tax_identification_number": "1234",
      "zipcode": "9399",
      "finalize_zero_amount_invoice": "skip"
    }
  }'