Skip to main content

Invoice object

Lago automatically generates invoices for each of your customers at the end of a billing period (monthly or yearly depending on the plan assigned to the customers).

They list and summarize the fees generated by Lago for your customers, based on the subscription and metrics notifications setuped in your Lago workspace.

Invoice object

{
"invoice": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"number": "LAG-1234-001-002",
"issuing_date": "2022-04-30",
"invoice_type": "subscription",
"status": "finalized",
"payment_status": "succeeded",
"currency": "EUR",
"fees_amount_cents": 100,
"vat_amount_cents": 20,
"coupons_amount_cents": 10,
"credit_notes_amount_cents": 10,
"sub_total_vat_excluded_amount_cents": 100,
"sub_total_vat_included_amount_cents": 120,
"total_amount_cents": 100,
"file_url": "https://getlago.com/invoice/file",
"legacy": false,
"customer": {
"lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"address_line1": "5230 Penfield Ave",
"address_line2": null,
"city": "Woodland Hills",
"country": "US",
"created_at": "2022-04-29T08:59:51Z",
"email": "dinesh@piedpiper.test",
"legal_name": "Coleman-Blair",
"legal_number": "49-008-2965",
"logo_url": "http://hooli.com/logo.png",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
"state": "CA",
"url": "http://hooli.com",
"vat_rate": 20.0,
"zipcode": "91364"
},
"subscriptions": [
{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"external_id": "susbcription_external_id",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"canceled_at": "2022-04-29T08:59:51Z",
"created_at": "2022-04-29T08:59:51Z",
"plan_code": "new_code",
"started_at": "2022-04-29T08:59:51Z",
"status": "active",
"terminated_at": null
}
],
"fees": [
{
"lago_id": "6be23c42-47d2-45a3-9770-5b3572f225c3",
"lago_group_id": null,
"lago_true_up_fee_id": null,
"lago_true_up_parent_fee_id": null,
"item": {
"type": "subscription",
"code": "plan_code",
"name": "Plan"
},
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"units": "0.32",
"events_count": 23
}
]
},
"credits": [
{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"item": {
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"type": "coupon",
"code": "coupon_code",
"name": "Coupon",
},
"amount_cents": 100,
"amount_currency": "EUR",
"before_vat": false
}
],
"metadata": [
{
"lago_id": "27f12d13-4ae0-437b-b822-8771bcd62e3a",
"key": "digital_ref_id",
"value": "INV-0123456-98765",
"created_at": "2022-04-29T08:59:51Z"
}
]
}
AttributesDescription
lago_id     String     Not nullUnique identifer of the invoice in Lago application
sequential_id     Integer     Not nullInvoice sequential id scoped on the customer
number     String     Not nullInvoice unique number
issuing_date     String    Not null
ISO 8601 date
Date of creation of the invoice
invoice_type     String     Not null
Type of invoice.
Possible values
- subscription: Invoice related to a subscription.
- one_off: Invoice related to one-off invoices.
- credit: Invoice related to a credit purchase.
status     String     Not null
Status of the invoice.
Possible values
- draft: Waiting for end of grace period to be finalized, events can still be ingested during this period.
- finalized: Invoice has been created, events cannot be ingested anymore.
payment_status     String     Not null
Status of the payment.
Possible values
- pending: Waiting for payment in Stripe or when invoice is emitted but users have not updated the payment status through the endpoint
- succeeded
- failed
currency     String    Not nullCurrency of all amount fields
fees_amount_cents     Integer     Not nullSum of fees amount in cents
vat_amount_cents     Integer     Not nullVat amount in cents
coupons_amount_cents     Integer     Not nullSum of applied coupons amount in cents
credit_notes_amount_cents     Integer     Not nullSum of applied credit notes amount in cents
prepaid_credit_amount_cents     Integer     Not nullSum of applied prepaid credit amount in cents
sub_total_vat_excluded_amount_cents     Integer     Not nullSubtotal amount in cents without VAT.
Value depends on version number
- 1: should be equal to fees_amount_cents - coupons_amount_cents - prepaid_credit_amount_cents.
- 2: should be equal to fees_amount_cents.
sub_total_vat_included_amount_cents     Integer     Not nullSubtotal amount in cents with VAT.
Value depends on version number
- 1: should be equal to total_amount_cents.
- 2: should be equal to fees_amount_cents + vat_amount_cents.
total_amount_cents     Integer     Not nullShould be the sum of the amount and the VAT amount
file_url     String  File url of the invoice PDF
customer     JSON    Not nullCustomer object. Billed customer
subscriptions     JSON    Not nullArray of Subscription objects (billed subscriptions)
fees     JSON    Not nullArray of fee objects
credits     JSON    Not nullArray of credit objects

Deprecated arguments

AttributesDescription
amount_cents     Integer     Not nullAmount in cents, VAT (tax) excluded. Replaced by the fees_amount_cents field
credit_amount_cents     Integer     Not nullTotal of credit amount applied to the invoice in cents. Replaced by coupons_amount_cents, credit_notes_amount_cents and prepaid_credit_amount_cents
legacy     Boolean    Not nulltrue if version_number = 1, false otherwise
amount_currency     String    Not nullCurrency of the amount. Replaced by the currency field
vat_amount_currency     String    Not nullCurrency of the VAT amount. Replaced by the currency field
credit_amount_currency     String    Not nullCurrency of the credit amount. Replaced by the currency field
total_amount_currency     String    Not nullCurrency of the total amount. Replaced by the currency field

Credit object

{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"item": {
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"type": "coupon",
"code": "coupon_code",
"name": "Coupon",
},
"amount_cents": 100,
"amount_currency": "EUR"
}
AttributesDescription
lago_id     String     Not nullUnique identifer of the credit in Lago application
item     JSON     Not nullItem attached to the credit.
Always have 4 attributes:
- lago_id: Id of the coupon or of the credit note
- type: coupon or credit_note
- code: Code of the coupon attached to the credit or number of the credit note
- name: Name of the coupon attached to the credit or number of the initial credit note invoice
amount_cents     Integer     Not nullAmount in cents of the credit
amount_currency     String     Not nullCurrency of the amount
before_vat     Boolean     Not nullFlag to indicate if the credit is applied on the amount before taxes (coupons) or after taxes (credit notes)

Metadata attributes

AttributesDescription
lago_id     String     Not nullUnique identifier of the invoice metadata object in Lago application.
created_at     String     Not null    
ISO 8601 datetime in UTC
Date of metadata object creation.
key     String     Not nullKey part in metadata pair
value     String     Not nullValue part in metadata pair