The invoice object

{
  "invoice": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "issuing_date": "2022-04-30",
    "payment_due_date": "2022-05-30",
    "net_payment_term": 30,
    "invoice_type": "subscription",
    "status": "finalized",
    "payment_status": "succeeded",
    "currency": "EUR",
    "fees_amount_cents": 100,
    "coupons_amount_cents": 0,
    "sub_total_taxes_excluding_amount_cents": 100,
    "taxes_amount_cents": 20,
    "sub_total_taxes_including_amount_cents": 120,
    "credit_notes_amount_cents": 0,
    "prepaid_credit_amount_cents": 0,
    "total_amount_cents": 120,
    "file_url": "https://getlago.com/invoice/file",
    "version_number": 3,
    "customer": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "sequential_id": 1,
      "slug": "LAG-1234-001",
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "name": "Gavin Belson",
      "email": "dinesh@piedpiper.test",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "currency": "USD",
      "timezone": "America/Los_Angeles",
      "applicable_timezone": "America/Los_Angeles",
      "address_line1": "5230 Penfield Ave",
      "address_line2": "string",
      "zipcode": "91364",
      "city": "Woodland Hills",
      "state": "CA",
      "country": "US",
      "tax_identification_number": "EU123456789",
      "logo_url": "http://hooli.com/logo.png",
      "created_at": "2022-04-29T08:59:51Z",
      "billing_configuration": {
        "document_locale": "fr"
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
      }
    },
    "metadata": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "digital_ref_id",
        "value": "INV-0123456-98765",
        "display_in_invoice": false,
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "metadata": [
      {
        "lago_id": "7cbfd968-1707-4e8b-ac0b-92efb305a6a0",
        "key": "invoice_test",
        "value": "12345",
        "created_at": "2023-07-13T14:28:19Z"
      }
    ],
    "credits": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "amount_cents": 1200,
        "amount_currency": "EUR",
        "before_vat": "boolean",
        "item": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "type": "coupon",
          "code": "startup_deal",
          "name": "Startup Deal"
        },
        "invoice": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "payment_status": "succeeded"
        }
      }
    ],
    "fees": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_group_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_parent_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "external_id",
        "external_subscription_id": "external_id",
        "amount_cents": 100,
        "amount_currency": "EUR",
        "taxes_amount_cents": 20,
        "taxes_rate": "20.0",
        "units": "0.32",
        "total_amount_cents": 120,
        "total_amount_currency": "EUR",
        "events_count": 23,
        "pay_in_advance": true,
        "invoiceable": true,
        "prorated": false,
        "from_date": "2022-04-29T08:59:51Z",
        "to_date": "2022-05-29T08:59:51Z",
        "payment_status": "pending",
        "created_at": "2022-08-24T14:58:59Z",
        "succeeded_at": "2022-08-24T14:58:59Z",
        "failed_at": "2022-08-24T14:58:59Z",
        "refunded_at": "2022-08-24T14:58:59Z",
        "event_transaction_id": "transaction_1234567890",
        "item": {
          "type": "subscription",
          "code": "startup",
          "name": "Startup",
          "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "item_type": "Subscription"
        }
      }
    ],
    "subscriptions": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "billing_time": "anniversary",
        "name": "Repository A",
        "plan_code": "premium",
        "status": "active",
        "created_at": "2022-08-08T00:00:00Z",
        "canceled_at": "2022-09-14T16:35:31Z",
        "started_at": "2022-08-08T00:00:00Z",
        "subscription_at": "2022-08-08T00:00:00Z",
        "terminated_at": "2022-09-14T16:35:31Z",
        "previous_plan_code": "string",
        "next_plan_code": "string",
        "downgrade_plan_date": "string"
      }
    ],
    "applied_taxes": [
      {
        "lago_id": "e0f02502-aa4c-444c-a390-746e4467d918",
        "lago_invoice_id": "b5067d7c-6f6f-4eaa-8e9c-821e7c5617a7",
        "lago_tax_id": "2d3316be-9b53-4143-b432-2488155e0260",
        "tax_name": "vat",
        "tax_code": "vat",
        "tax_rate": 20.0,
        "tax_description": "",
        "amount_cents": 20000,
        "amount_currency": "USD",
        "created_at": "2023-07-13T14:27:48Z"
      }
    ]
  }
}

Attributes

invoice

object

lago_idrequired

string

Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice’s record within the Lago system.

sequential_idrequired

integer

This ID helps in uniquely identifying and organizing the invoices associated with a specific customer. It provides a sequential numbering system specific to the customer, allowing for easy tracking and management of invoices within the customer’s context.

numberrequired

string

The unique number assigned to the invoice. This number serves as a distinct identifier for the invoice and helps in differentiating it from other invoices in the system.

issuing_daterequired

string

The date when the invoice was issued. It is provided in the ISO 8601 date format.

payment_due_daterequired

string

The payment due date for the invoice, specified in the ISO 8601 date format.

net_payment_termrequired

integer

The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.

invoice_typerequired

string

The type of invoice issued. Possible values are subscription, one-off or credit.

statusrequired

string

The status of the invoice. It indicates the current state of the invoice and can have two possible values:

draft: the invoice is in the draft state, waiting for the end of the grace period to be finalized. During this period, events can still be ingested and added to the invoice.
finalized: the invoice has been issued and finalized. In this state, events cannot be ingested or added to the invoice anymore.

payment_statusrequired

string

The status of the payment associated with the invoice. It can have one of the following values:

pending: the payment is pending, waiting for payment processing in Stripe or when the invoice is emitted but users have not updated the payment status through the endpoint.
succeeded: the payment of the invoice has been successfully processed.
failed: the payment of the invoice has failed or encountered an error during processing.

currencyrequired

string

The currency of the invoice issued.

fees_amount_centsrequired

integer

The total sum of fees amount in cents. It calculates the cumulative amount of all the fees associated with the invoice, providing a consolidated value.

taxes_amount_centsrequired

integer

The sum of tax amount associated with the invoice, expressed in cents.

coupons_amount_centsrequired

integer

The total sum of all coupons discounted on the invoice. It calculates the cumulative discount amount applied by coupons, expressed in cents.

credit_notes_amount_centsrequired

integer

The total sum of all credit notes discounted on the invoice. It calculates the cumulative discount amount applied by credit notes, expressed in cents.

prepaid_credit_amount_centsrequired

integer

The total sum of all prepaid credits discounted on the invoice. It calculates the cumulative discount amount applied by prepaid credits, expressed in cents.

sub_total_taxes_excluding_amount_centsrequired

integer

Subtotal amount, excluding taxes, expressed in cents. This field depends on the version number. Here are the definitions based on the version:

Version 1: is equal to the sum of fees_amount_cents, minus coupons_amount_cents, and minus prepaid_credit_amount_cents.
Version 2: is equal to the fees_amount_cents.
Version 3: is equal to the fees_amount_cents, minus coupons_amount_cents.

sub_total_taxes_including_amount_centsrequired

integer

Subtotal amount, including taxes, expressed in cents. This field depends on the version number. Here are the definitions based on the version:

Version 1: is equal to the total_amount_cents.
Version 2: is equal to the sum of fees_amount_cents and vat_amount_cents.
Version 3: is equal to the sum sub_total_excluding_taxes_amount_cents and taxes_amount_cents

total_amount_centsrequired

integer

The sum of the amount and taxes amount on the invoice, expressed in cents. It calculates the total financial value of the invoice, including both the original amount and any applicable taxes.

file_url

string

Contains the URL that provides direct access to the invoice PDF file. You can use this URL to download or view the PDF document of the invoice

file_url

string

Contains the URL that provides direct access to the invoice PDF file. You can use this URL to download or view the PDF document of the invoice

customersrequired

object

subscriptionsrequired

object

lago_idrequired

string

Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription’s record within the Lago system

external_idrequired

string

The unique external identifier for the subscription in your application. This identifier serves as an idempotency key, ensuring that each subscription is unique.

lago_customer_idrequired

string

Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer’s record within the Lago system

external_customer_idrequired

string

The customer external unique identifier (provided by your own application).

canceled_at

string

The cancellation date of the subscription. This field is not null when the subscription is canceled. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

created_atrequired

string

The creation date of the subscription, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). This date provides a timestamp indicating when the subscription was initially created.

plan_coderequired

string

The unique code representing the plan to be attached to the customer. This code must correspond to the code property of one of the active plans.

started_atrequired

string

The effective start date of the subscription. This field can be null if the subscription is pending or canceled. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

namerequired

string

The display name of the subscription on an invoice. This field allows for customization of the subscription’s name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan.

statusrequired

string

The status of the subscription, which can have the following values:

pending: a previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period.
active: the subscription is currently active and applied to the customer.
terminated: the subscription is no longer active.
canceled: the subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer or when a subscription with a pending status is terminated.

terminated_atrequired

string

The termination date of the subscription. This field is not null when the subscription is terminated. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC)

feesrequired

object

lago_idrequired

string

Unique identifier assigned to the fee within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the fee’s record within the Lago system.

lago_group_id

string

Unique identifier assigned to the group that the fee belongs to.

lago_true_up_fee_id

string

Unique identifier assigned to the true-up fee when a minimum has been set to the charge. This identifier helps to distinguish and manage the true-up fee associated with the charge, which may be applicable when a minimum threshold or limit is set for the charge amount.

lago_true_up_parent_fee_id

string

Unique identifier assigned to the parent fee on which the true-up fee is assigned. This identifier establishes the relationship between the parent fee and the associated true-up fee.

amount_centsrequired

integer

The cost of this specific fee, excluding any applicable taxes.

amount_currencyrequired

string

The currency of this specific fee. It indicates the monetary unit in which the fee’s cost is expressed.

vat_amount_centsrequired

integer

The cost of the tax associated with this specific fee.

vat_amount_currencyrequired

string

The currency of the tax associated with this specific fee.

total_amount_centsrequired

integer

The cost of this specific fee, including any applicable taxes.

total_amount_currencyrequired

string

The currency of this specific fee, including any applicable taxes.

unitsrequired

string

The number of units used to charge the customer. This field indicates the quantity or count of units consumed or utilized in the context of the charge. It helps in determining the basis for calculating the fee or cost associated with the usage of the service or product provided to the customer.

events_count

integer

The number of events that have been sent and used to charge the customer. This field indicates the count or quantity of events that have been processed and considered in the charging process.

pay_in_advancerequired

boolean

Flag that indicates whether the fee was paid in advance. It serves as a boolean value, where true represents that the fee was paid in advance (straightaway), and false indicates that the fee was not paid in arrears (at the end of the period).

invoiceablerequired

boolean

Flag that indicates whether the fee was included on the invoice. It serves as a boolean value, where true represents that the fee was included on the invoice, and false indicates that the fee was not included on the invoice.

proratedrequired

boolean

Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully. If not defined, this argument is set to false by default.

If set to true, the charge is prorated based on the remaining days in the current billing period.
If set to false, the charge is billed in full.

Note that only a charge_model sets to standard and volume can be prorated.

itemrequired

JSON

creditsrequired

object

metadata

object

{
  "invoice": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "issuing_date": "2022-04-30",
    "payment_due_date": "2022-05-30",
    "net_payment_term": 30,
    "invoice_type": "subscription",
    "status": "finalized",
    "payment_status": "succeeded",
    "currency": "EUR",
    "fees_amount_cents": 100,
    "coupons_amount_cents": 0,
    "sub_total_taxes_excluding_amount_cents": 100,
    "taxes_amount_cents": 20,
    "sub_total_taxes_including_amount_cents": 120,
    "credit_notes_amount_cents": 0,
    "prepaid_credit_amount_cents": 0,
    "total_amount_cents": 120,
    "file_url": "https://getlago.com/invoice/file",
    "version_number": 3,
    "customer": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "sequential_id": 1,
      "slug": "LAG-1234-001",
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "name": "Gavin Belson",
      "email": "dinesh@piedpiper.test",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "currency": "USD",
      "timezone": "America/Los_Angeles",
      "applicable_timezone": "America/Los_Angeles",
      "address_line1": "5230 Penfield Ave",
      "address_line2": "string",
      "zipcode": "91364",
      "city": "Woodland Hills",
      "state": "CA",
      "country": "US",
      "tax_identification_number": "EU123456789",
      "logo_url": "http://hooli.com/logo.png",
      "created_at": "2022-04-29T08:59:51Z",
      "billing_configuration": {
        "document_locale": "fr"
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
      }
    },
    "metadata": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "digital_ref_id",
        "value": "INV-0123456-98765",
        "display_in_invoice": false,
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "metadata": [
      {
        "lago_id": "7cbfd968-1707-4e8b-ac0b-92efb305a6a0",
        "key": "invoice_test",
        "value": "12345",
        "created_at": "2023-07-13T14:28:19Z"
      }
    ],
    "credits": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "amount_cents": 1200,
        "amount_currency": "EUR",
        "before_vat": "boolean",
        "item": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "type": "coupon",
          "code": "startup_deal",
          "name": "Startup Deal"
        },
        "invoice": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "payment_status": "succeeded"
        }
      }
    ],
    "fees": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_group_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_parent_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "external_id",
        "external_subscription_id": "external_id",
        "amount_cents": 100,
        "amount_currency": "EUR",
        "taxes_amount_cents": 20,
        "taxes_rate": "20.0",
        "units": "0.32",
        "total_amount_cents": 120,
        "total_amount_currency": "EUR",
        "events_count": 23,
        "pay_in_advance": true,
        "invoiceable": true,
        "prorated": false,
        "from_date": "2022-04-29T08:59:51Z",
        "to_date": "2022-05-29T08:59:51Z",
        "payment_status": "pending",
        "created_at": "2022-08-24T14:58:59Z",
        "succeeded_at": "2022-08-24T14:58:59Z",
        "failed_at": "2022-08-24T14:58:59Z",
        "refunded_at": "2022-08-24T14:58:59Z",
        "event_transaction_id": "transaction_1234567890",
        "item": {
          "type": "subscription",
          "code": "startup",
          "name": "Startup",
          "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "item_type": "Subscription"
        }
      }
    ],
    "subscriptions": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "billing_time": "anniversary",
        "name": "Repository A",
        "plan_code": "premium",
        "status": "active",
        "created_at": "2022-08-08T00:00:00Z",
        "canceled_at": "2022-09-14T16:35:31Z",
        "started_at": "2022-08-08T00:00:00Z",
        "subscription_at": "2022-08-08T00:00:00Z",
        "terminated_at": "2022-09-14T16:35:31Z",
        "previous_plan_code": "string",
        "next_plan_code": "string",
        "downgrade_plan_date": "string"
      }
    ],
    "applied_taxes": [
      {
        "lago_id": "e0f02502-aa4c-444c-a390-746e4467d918",
        "lago_invoice_id": "b5067d7c-6f6f-4eaa-8e9c-821e7c5617a7",
        "lago_tax_id": "2d3316be-9b53-4143-b432-2488155e0260",
        "tax_name": "vat",
        "tax_code": "vat",
        "tax_rate": 20.0,
        "tax_description": "",
        "amount_cents": 20000,
        "amount_currency": "USD",
        "created_at": "2023-07-13T14:27:48Z"
      }
    ]
  }
}

API Reference

​Attributes

Attributes