OpenAPI Specification
openapi: 3.1.0
info:
title: Lago API documentation Add_ons Invoices API
description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
version: 1.15.0
license:
name: AGPLv3
identifier: AGPLv3
contact:
email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
description: EU Lagos cluster
security:
- bearerAuth: []
tags:
- name: Invoices
description: Everything about Invoice collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/invoices/invoice-object
paths:
/invoices:
post:
tags:
- Invoices
summary: Lago Create a one-off invoice
description: This endpoint is used for issuing a one-off invoice.
operationId: createInvoice
requestBody:
description: Invoice payload
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceOneOffCreateInput'
required: true
responses:
'200':
description: Invoice created
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Invoices
summary: Lago List all invoices
description: This endpoint is used for retrieving all invoices.
operationId: findAllInvoices
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- $ref: '#/components/parameters/external_customer_id'
- name: issuing_date_from
in: query
description: Filter invoices starting from a specific date.
required: false
explode: true
schema:
type: string
format: date
example: '2022-07-08'
- name: issuing_date_to
in: query
description: Filter invoices up to a specific date.
required: false
explode: true
schema:
type: string
format: date
example: '2022-08-09'
- name: status
in: query
description: Filter invoices by status. Possible values are `draft` or `finalized`.
required: false
explode: true
schema:
type: string
enum:
- draft
- finalized
- name: payment_status
in: query
description: Filter invoices by payment status. Possible values are `pending`, `failed` or `succeeded`.
required: false
explode: true
schema:
type: string
enum:
- pending
- failed
- succeeded
- name: payment_overdue
in: query
description: Filter invoices by payment_overdue. Possible values are `true` or `false`.
required: false
explode: true
schema:
type: boolean
example: true
- name: search_term
in: query
description: Search invoices by id, number, customer name, customer external_id or customer email.
required: false
explode: true
schema:
type: string
example: Jane
- name: currency
in: query
description: Filter invoices by currency in. Possible values ISO 4217 currency codes.
required: false
explode: true
schema:
type: string
example: EUR
- name: payment_dispute_lost
in: query
description: Filter invoices with a payment dispute lost. Possible values are `true` or `false`.
required: false
explode: true
schema:
type: boolean
example: true
- name: invoice_type
in: query
description: Filter invoices by invoice type. Possible values are `subscription`, `add_on`, `credit`, `one_off` or `advance_charges`
required: false
explode: true
schema:
type: string
enum:
- subscription
- add_on
- credit
- one_off
- advance_charges
responses:
'200':
description: Invoices
content:
application/json:
schema:
$ref: '#/components/schemas/InvoicesPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
/invoices/{lago_id}:
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
put:
tags:
- Invoices
summary: Lago Update an invoice
description: This endpoint is used for updating an existing invoice.
operationId: updateInvoice
requestBody:
description: Update an existing invoice
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceUpdateInput'
required: true
responses:
'200':
description: Invoice updated
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Invoices
summary: Lago Retrieve an invoice
description: This endpoint is used for retrieving a specific invoice that has been issued.
operationId: findInvoice
responses:
'200':
description: Invoice
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/invoices/{lago_id}/download:
post:
tags:
- Invoices
summary: Lago Download an invoice PDF
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
description: This endpoint is used for downloading a specific invoice PDF document.
operationId: downloadInvoice
responses:
'200':
description: Invoice PDF
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/invoices/{lago_id}/finalize:
put:
tags:
- Invoices
summary: Lago Finalize a draft invoice
description: This endpoint is used for finalizing a draft invoice.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: finalizeInvoice
responses:
'200':
description: Invoice finalized
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/invoices/{lago_id}/lose_dispute:
post:
tags:
- Invoices
summary: Lago Mark an invoice payment dispute as lost
description: This endpoint is used for setting invoice's payment dispute as lost.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: loseDisputeInvoice
responses:
'200':
description: Invoice payment dispute lost
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/NotAllowed'
/invoices/{lago_id}/refresh:
put:
tags:
- Invoices
summary: Lago Refresh a draft invoice
description: This endpoint is used for refreshing a draft invoice.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: refreshInvoice
responses:
'200':
description: Invoice refreshed
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/invoices/{lago_id}/retry:
post:
tags:
- Invoices
summary: Lago Retry generation of a failed invoice
description: This endpoint is used for retrying to generate a failed invoice.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: retryInvoice
responses:
'200':
description: Invoice generation has been retried
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/invoices/{lago_id}/payment_url:
post:
tags:
- Invoices
summary: Lago Generate a payment URL
description: This endpoint generates a checkout link for a specific invoice.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: invoicePaymentUrl
responses:
'200':
description: Payment URL has been generated
content:
application/json:
schema:
type: object
description: .
properties:
invoice_payment_details:
type: object
properties:
lago_customer_id:
type: string
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: 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
lago_invoice_id:
type: string
example: 1e501a90-1a90-1a90-1a90-1a901a901a80
description: 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
external_customer_id:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
description: The customer external unique identifier (provided by your own application)
payment_provider:
type: string
example: stripe
description: The Payment Provider name linked to the Customer.
payment_url:
type: string
example: https://foo.bar
description: The generated Payment URL for the Invoice.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/invoices/{lago_id}/retry_payment:
post:
tags:
- Invoices
summary: Lago Retry an invoice payment
description: This endpoint resends an invoice for collection and retry a payment.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: retryPayment
responses:
'200':
description: Invoice payment retried
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/NotAllowed'
/invoices/{lago_id}/void:
post:
tags:
- Invoices
summary: Lago Void an invoice
description: This endpoint is used for voiding an invoice. You can void an invoice only when it's in a `finalized` status, and the payment status is not `succeeded`.
parameters:
- $ref: '#/components/parameters/lago_invoice_id'
operationId: voidInvoice
responses:
'200':
description: Invoice voided
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
PaginationMeta:
type: object
required:
- current_page
- total_pages
- total_count
properties:
current_page:
type: integer
description: Current page.
example: 2
next_page:
type: integer
description: Next page.
example: 3
nullable: true
prev_page:
type: integer
description: Previous page.
example: 1
nullable: true
total_pages:
type: integer
description: Total number of pages.
example: 4
total_count:
type: integer
description: Total number of records.
example: 70
CreditObject:
type: object
required:
- lago_id
- item
- amount_cents
- amount_currency
- invoice
- before_taxes
properties:
lago_id:
type: string
format: uuid
description: Unique identifier assigned to the credit within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the credit's item record within the Lago system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
amount_cents:
type: integer
description: The amount of credit associated with the invoice, expressed in cents.
example: 1200
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The currency of the credit.
example: EUR
before_taxes:
type: boolean
description: Indicates whether the credit is applied on the amount before taxes (coupons) or after taxes (credit notes). This flag helps determine the order in which credits are applied to the invoice calculation
example: false
item:
type: object
description: The item attached to the credit.
required:
- lago_item_id
- type
- code
- name
properties:
lago_item_id:
type: string
format: uuid
description: Unique identifier assigned to the credit item within the Lago application.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
type:
type: string
enum:
- coupon
- credit_note
- invoice
description: The type of credit applied. Possible values are `coupon`, `credit_note` or `invoice` (for `progressive_billing` invoice).
example: coupon
code:
type: string
description: The code of the credit applied. It can be the code of the coupon attached to the credit, the credit note's number or the `progressive_billing` invoice number.
example: startup_deal
name:
type: string
description: The name of the credit applied. It can be the name of the coupon attached to the credit, the initial invoice's number linked to the credit note or the `progressive_billing` invoice number.
example: Startup Deal
invoice:
type: object
required:
- lago_id
- payment_status
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
payment_status:
type: string
enum:
- pending
- succeeded
- failed
example: succeeded
UsageThresholdObject:
type: object
required:
- lago_id
- amount_cents
- recurring
- created_at
- updated_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the usage threshold created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
threshold_display_name:
type: string
nullable: true
description: The display name of the usage threshold.
example: Threshold 1
amount_cents:
type: integer
description: The amount to reach to trigger a `progressive_billing` invoice.
example: 10000
recurring:
type: boolean
description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount.
example: true
created_at:
type: string
format: date-time
description: The date and time when the usage threshold was created. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2023-06-27T19:43:42Z'
updated_at:
type: string
format: date-time
description: The date and time when the usage threshold was last updated. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2023-06-27T19:43:42Z'
InvoiceUpdateInput:
type: object
required:
- invoice
properties:
invoice:
type: object
properties:
payment_status:
type: string
enum:
- pending
- succeeded
- failed
description: The payment status of the invoice. Possible values are `pending`, `failed` or `succeeded`.
example: succeeded
metadata:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: The metadata object identifier. Only required when updating existing metadata.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
key:
type: string
description: The key in the key-value pair of the metadata.
example: digital_ref_id
value:
type: string
description: The value in the key-value pair of the metadata.
example: INV-0123456-98765
Address:
type: object
description: Configuration specific to the payment provider, utilized for billing the customer. This object contains settings and parameters necessary for processing payments and invoicing the customer.
properties:
address_line1:
type: string
example: 5230 Penfield Ave
description: The first line of the billing address
nullable: true
address_line2:
type: string
example: null
description: The second line of the billing address
nullable: true
city:
type: string
example: Woodland Hills
description: The city of the customer's billing address
nullable: true
country:
allOf:
- $ref: '#/components/schemas/Country'
- nullable: true
description: Country code of the customer's billing address. Format must be ISO 3166 (alpha-2)
example: US
state:
type: string
example: CA
description: The state of the customer's billing address
nullable: true
zipcode:
type: string
example: '91364'
description: The zipcode of the customer's billing address
nullable: true
IntegrationCustomer:
type: object
description: Configuration specific to the accounting and tax integrations. This object contains settings and parameters necessary for syncing documents and payments.
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: A unique identifier for the integration customer object in the Lago application.
type:
type: string
example: netsuite
description: 'The integration type used for accounting and tax syncs.
Accepted values: `netsuite, anrok`.'
enum:
- netsuite
- anrok
integration_code:
type: string
example: netsuite-eu-1
description: Unique code used to identify an integration connection.
external_customer_id:
type: string
example: cus_12345
description: The customer ID within the integration's system. If this field is not provided, Lago has the option to create a new customer record within the integration's system on behalf of the customer.
sync_with_provider:
type: boolean
example: true
description: Set this field to `true` if you want to create a customer record in the integration's system. This option is applicable only when the `external_customer_id` is null and the `sync_with_provider` field is set to `true`. By default, the value is set to `false`
subsidiary_id:
type: string
example: '2'
description: This optional field is needed only when working with `netsuite` connection.
CustomerMetadata:
type: object
description: Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format
required:
- lago_id
- key
- value
- display_in_invoice
- created_at
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: A unique identifier for the customer metadata object in the Lago application. Can be used to update a key-value pair
key:
type: string
example: Purchase Order
description: The metadata object key
value:
type: string
example: '123456789'
description: The metadata object value
display_in_invoice:
type: boolean
example: true
description: Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice.
created_at:
type: string
format: date-time
example: '2022-04-29T08:59:51Z'
description: The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created
Timezone:
type: string
example: America/Los_Angeles
enum:
- UTC
- Africa/Algiers
- Africa/Cairo
- Africa/Casablanca
- Africa/Harare
- Africa/Johannesburg
- Africa/Monrovia
- Africa/Nairobi
- America/Argentina/Buenos_Aires
- America/Bogota
- America/Caracas
- America/Chicago
- America/Chihuahua
- America/Denver
- America/Godthab
- America/Guatemala
- America/Guyana
- America/Halifax
- America/Indiana/Indianapolis
- America/Juneau
- America/La_Paz
- America/Lima
- America/Los_Angeles
- America/Mazatlan
- America/Mexico_City
- America/Monterrey
- America/Montevideo
- America/New_York
- America/Phoenix
- America/Puerto_Rico
- America/Regina
- America/Santiago
- America/Sao_Paulo
- America/St_Johns
- America/Tijuana
- Asia/Almaty
- Asia/Baghdad
- Asia/Baku
- Asia/Bangkok
- Asia/Chongqing
- Asia/Colombo
- Asia/Dhaka
- Asia/Hong_Kong
- Asia/Irkutsk
- Asia/Jakarta
- Asia/Jerusalem
- Asia/Kabul
- Asia/Kamchatka
- Asia/Karachi
- Asia/Kathmandu
- Asia/Kolkata
- Asia/Krasnoyarsk
- Asia/Kuala_Lumpur
- Asia/Kuwait
- Asia/Magadan
- Asia/Muscat
- Asia/Novosibirsk
- Asia/Rangoon
- Asia/Riyadh
- Asia/Seoul
- Asia/Shanghai
- Asia/Singapore
- Asia/Srednekolymsk
- Asia/Taipei
- Asia/Tashkent
- Asia/Tbilisi
- Asia/Tehran
- Asia/Tokyo
- Asia/Ulaanbaatar
- Asia/Urumqi
- Asia/Vladivostok
- Asia/Yakutsk
- Asia/Yekaterinburg
- Asia/Yerevan
- Atlantic/Azores
- Atlantic/Cape_Verde
- Atlantic/South_Georgia
- Australia/Adelaide
- Australia/Brisbane
- Australia/Darwin
- Australia/Hobart
- Australia/Melbourne
- Australia/Perth
- Australia/Sydney
- Europe/Amsterdam
- Europe/Athens
- Europe/Belgrade
- Europe/Berlin
- Europe/Bratislava
- Europe/Brussels
- Europe/Bucharest
- Europe/Budapest
- Europe/Copenhagen
- Europe/Dublin
- Europe/Helsinki
- Europe/Istanbul
- Europe/Kaliningrad
- Europe/Kiev
- Europe/Lisbon
- Europe/Ljubljana
- Europe/London
- Europe/Madrid
- Europe/Minsk
- Europe/Moscow
- Europe/Paris
- Europe/Prague
- Europe/Riga
- Europe/Rome
- Europe/Samara
- Europe/Sarajevo
- Europe/Skopje
- Europe/Sofia
- Europe/Stockholm
- Europe/Tallinn
- Europe/Vienna
- Europe/Vilnius
- Europe/Volgograd
- Europe/Warsaw
- Europe/Zagreb
- Europe/Zurich
- GMT+12
- Pacific/Apia
- Pacific/Auckland
- Pacific/Chatham
- Pacific/Fakaofo
- Pacific/Fiji
- Pacific/Guadalcanal
- Pacific/Guam
- Pacific/Honolulu
- Pacific/Majuro
- Pacific/Midway
- Pacific/Noumea
- Pacific/Pago_Pago
- Pacific/Port_Moresby
- Pacific/Tongatapu
ApiErrorNotAllowed:
type: object
required:
- status
- error
- code
properties:
status:
type: integer
format: int32
example: 405
error:
type: string
example: Method Not Allowed
code:
type: string
example: not_allowed
Country:
type: string
example: US
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
ApiErrorNotFound:
type: object
required:
- status
- error
- code
properties:
status:
type: integer
format: int32
example: 404
error:
type: string
example: Not Found
code:
type: string
example: object_not_found
BaseAppliedTax:
type: object
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the applied tax, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
lago_tax_id:
type: string
format: uuid
description: Unique identifier of the tax, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
tax_name:
type: string
description: Name of the tax.
example: TVA
tax_code:
type: string
description: Unique code used to identify the tax associated with the API request.
example: french_standard_vat
tax_rate:
type: number
description: The percentage rate of the tax
example: 20
tax_description:
type: string
description: Internal description of the taxe
example: French standard VAT
amount_cents:
type: integer
description: Amount of the tax
example: 2000
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: Currency of the tax
example: USD
created_at:
type: string
format: date-time
description: The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created.
example: '2022-09-14T16:35:31Z'
SubscriptionObject:
type: object
required:
- lago_id
- lago_customer_id
- billing_time
- external_customer_id
- created_at
- subscription_at
- plan_code
- external_id
- status
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
descript
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-invoices-api-openapi.yml