OpenAPI Specification
openapi: 3.1.0
info:
title: Lago API documentation Add_ons Customers 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: Customers
description: Everything about Customer collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/customers/customer-object
paths:
/customers:
post:
tags:
- Customers
summary: Lago Create a customer
description: This endpoint creates a new customer.
operationId: createCustomer
requestBody:
description: Customer payload
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerCreateInput'
required: true
responses:
'200':
description: Customer created or updated
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Customers
summary: Lago List all customers
description: This endpoint retrieves all existing customers.
operationId: findAllCustomers
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: List of customers
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
/customers/{external_id}:
parameters:
- name: external_id
in: path
description: External ID of the existing customer
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
get:
tags:
- Customers
summary: Lago Retrieve a customer
description: This endpoint retrieves an existing customer.
operationId: findCustomer
responses:
'200':
description: Customer
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Customers
summary: Lago Delete a customer
description: This endpoint deletes an existing customer.
operationId: destroyCustomer
responses:
'200':
description: Customer deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{external_customer_id}/applied_coupons/{applied_coupon_id}:
delete:
tags:
- Customers
summary: Lago Delete an applied coupon
description: This endpoint is used to delete a specific coupon that has been applied to a customer.
parameters:
- name: external_customer_id
in: path
description: The customer external unique identifier (provided by your own application)
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
- name: applied_coupon_id
in: path
description: Unique identifier of the applied coupon, created by Lago.
required: true
explode: true
schema:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
operationId: deleteAppliedCoupon
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/AppliedCoupon'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{external_customer_id}/portal_url:
get:
tags:
- Customers
summary: Lago Get a customer portal URL
description: 'Retrieves an embeddable link for displaying a customer portal.
This endpoint allows you to fetch the URL that can be embedded to provide customers access to a dedicated portal'
parameters:
- name: external_customer_id
in: path
description: External ID of the existing customer
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
operationId: getCustomerPortalUrl
responses:
'200':
description: Portal URL
content:
application/json:
schema:
type: object
required:
- customer
properties:
customer:
type: object
required:
- portal_url
properties:
portal_url:
type: string
example: https://app.lago.com/customer-portal/1234567890
description: An embeddable link for displaying a customer portal
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{external_customer_id}/current_usage:
get:
tags:
- Customers
summary: Lago Retrieve customer current usage
description: This endpoint enables the retrieval of the usage-based billing data for a customer within the current period.
parameters:
- name: external_customer_id
in: path
description: The customer external unique identifier (provided by your own application).
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
- name: external_subscription_id
in: query
description: The unique identifier of the subscription within your application.
required: true
explode: true
schema:
type: string
example: sub_1234567890
operationId: findCustomerCurrentUsage
responses:
'200':
description: Customer usage
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerUsage'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/customers/{external_customer_id}/past_usage:
get:
tags:
- Customers
summary: Lago Retrieve customer past usage
description: This endpoint enables the retrieval of the usage-based billing data for a customer within past periods.
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- name: external_customer_id
in: path
description: The customer external unique identifier (provided by your own application).
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
- name: external_subscription_id
in: query
description: The unique identifier of the subscription within your application.
required: true
explode: true
schema:
type: string
example: sub_1234567890
- name: billable_metric_code
in: query
description: Billable metric code filter to apply to the charge usage
required: false
explode: true
schema:
type: string
example: cpu
- name: periods_count
in: query
description: Number of past billing period to returns in the result
required: false
explode: true
schema:
type: integer
example: 5
operationId: findAllCustomerPastUsage
responses:
'200':
description: Customer past usage
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerPastUsage'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/customers/{external_customer_id}/checkout_url:
post:
tags:
- Customers
summary: Lago Generate a Customer Payment Provider Checkout URL
description: This endpoint regenerates the Payment Provider Checkout URL of a Customer.
parameters:
- name: external_customer_id
in: path
description: The customer external unique identifier (provided by your own application).
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
operationId: generateCustomerCheckoutURL
responses:
'200':
description: Customer Checkout URL
content:
application/json:
schema:
type: object
description: .
properties:
customer:
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
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.
checkout_url:
type: string
example: https://foo.bar
description: The new generated Payment Provider Checkout URL for the Customer.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
CustomerObjectExtended:
allOf:
- $ref: '#/components/schemas/CustomerObject'
- type: object
properties:
metadata:
type: array
items:
$ref: '#/components/schemas/CustomerMetadata'
taxes:
description: List of customer taxes
type: array
items:
$ref: '#/components/schemas/TaxObject'
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
CustomerChargeUsageObject:
type: object
required:
- units
- events_count
- amount_cents
- amount_currency
- charge
- billable_metric
- groups
properties:
units:
type: string
pattern: ^[0-9]+.?[0-9]*$
example: '1.0'
description: The number of units consumed by the customer for a specific charge item.
events_count:
type: integer
example: 10
description: The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts.
amount_cents:
type: integer
example: 123
description: The amount in cents, tax excluded, consumed by the customer for a specific charge item.
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The currency of a usage item consumed by the customer.
example: EUR
charge:
type: object
description: Object listing all the properties for a specific charge item.
required:
- lago_id
- charge_model
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the charge within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the charge's record within the Lago system.
charge_model:
type: string
description: The pricing model applied to this charge. Possible values are standard, `graduated`, `percentage`, `package` or `volume`.
enum:
- standard
- graduated
- package
- percentage
- volume
example: graduated
invoice_display_name:
type: string
description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
example: Setup
billable_metric:
type: object
description: The related billable metric object.
required:
- lago_id
- name
- code
- aggregation_type
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the billable metric within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the billable metric's record within the Lago system.
name:
type: string
example: Storage
description: The name of the billable metric used for this charge.
code:
type: string
example: storage
description: The code of the billable metric used for this charge.
aggregation_type:
type: string
description: The aggregation type of the billable metric used for this charge. Possible values are `count_agg`, `sum_agg`, `max_agg` or `unique_count_agg`.
enum:
- count_agg
- sum_agg
- max_agg
- unique_count_agg
- weighted_sum_agg
- latest_agg
example: sum_agg
filters:
$ref: '#/components/schemas/CustomerChargeFiltersUsageObject'
grouped_usage:
$ref: '#/components/schemas/CustomerChargeGroupedUsageObject'
AppliedCouponObject:
type: object
required:
- lago_id
- lago_coupon_id
- coupon_code
- coupon_name
- external_customer_id
- lago_customer_id
- status
- frequency
- created_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the applied coupon, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
lago_coupon_id:
type: string
format: uuid
description: Unique identifier of the coupon, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
coupon_code:
type: string
description: Unique code used to identify the coupon.
example: startup_deal
coupon_name:
type: string
description: The name of the coupon.
example: Startup Deal
lago_customer_id:
type: string
format: uuid
description: Unique identifier of the customer, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
external_customer_id:
type: string
description: The customer external unique identifier (provided by your own application)
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
status:
type: string
enum:
- active
- terminated
description: The status of the coupon. Can be either `active` or `terminated`.
example: active
amount_cents:
type: integer
nullable: true
description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
example: 2000
amount_cents_remaining:
type: integer
nullable: true
description: The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`. This field indicates the remaining balance or value that can still be utilized from the coupon.
example: 50
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- nullable: true
description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
example: EUR
percentage_rate:
type: string
pattern: ^[0-9]+.?[0-9]*$
nullable: true
description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
example: null
frequency:
type: string
enum:
- once
- recurring
- forever
description: 'The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.
- If set to `once`, the coupon is applicable only for a single use.
- If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
- If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.'
example: recurring
frequency_duration:
type: integer
nullable: true
description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
example: 3
frequency_duration_remaining:
type: integer
nullable: true
description: The remaining number of billing periods to which the coupon is applicable. This field determines the remaining usage or availability of the coupon based on the remaining billing periods.
example: 1
expiration_at:
type: string
format: date-time
nullable: true
description: The date and time after which the coupon will stop applying to customer's invoices. Once the expiration date is reached, the coupon will no longer be applicable, and any further invoices generated for the customer will not include the coupon discount.
example: '2022-04-29T08:59:51Z'
created_at:
type: string
format: date-time
description: The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2022-04-29T08:59:51Z'
terminated_at:
type: string
format: date-time
nullable: true
description: This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2022-04-29T08:59:51Z'
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
Customer:
type: object
required:
- customer
properties:
customer:
$ref: '#/components/schemas/CustomerObjectExtended'
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
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
CustomerUsageObject:
type: object
required:
- from_datetime
- to_datetime
- issuing_date
- amount_cents
- taxes_amount_cents
- total_amount_cents
- charges_usage
properties:
from_datetime:
type: string
format: date-time
description: The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
example: '2022-07-01T00:00:00Z'
to_datetime:
type: string
format: date-time
description: The upper bound of the
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-customers-api-openapi.yml