> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a customer
> This endpoint creates a new customer.
This endpoint performs an upsert operation.
```bash cURL theme={"dark"}
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": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"address_line1": "5230 Penfield Ave",
"address_line2": "",
"city": "Woodland Hills",
"country": "US",
"currency": "USD",
"email": "dinesh@piedpiper.test",
"legal_name": "Coleman-Blair",
"legal_number": "49-008-2965",
"tax_identification_number": "EU123456789",
"logo_url": "http://hooli.com/logo.png",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
"state": "CA",
"timezone": "Europe/Paris",
"url": "http://hooli.com",
"zipcode": "91364",
"billing_configuration": {
"invoice_grace_period": 3,
"payment_provider": "stripe",
"provider_customer_id": "cus_12345",
"sync": true,
"sync_with_provider": true,
"document_locale": "fr",
"provider_payment_methods": ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
},
"metadata": [
{
"key": "Purchase Order",
"value": "123456789",
"display_in_invoice": true
}
],
"tax_codes": ["french_standard_vat"]
}
}'
```
```python Python theme={"dark"}
from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import Customer, CustomerBillingConfiguration
client = Client(api_key='__YOUR_API_KEY__')
metadata_object = Metadata(
display_in_invoice=True,
key='Purchase Order',
value='123456789'
)
customer = Customer(
external_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
address_line1="5230 Penfield Ave",
address_line2=None,
city="Woodland Hills",
currency="USD",
country="US",
email="test@example.com",
legal_name="Coleman-Blair",
legal_number="49-008-2965",
tax_identification_number="EU123456789",
logo_url="http://hooli.com/logo.png",
name="Test Name",
phone="1-171-883-3711 x245",
state="CA",
timezone="Europe/Paris",
url="http://hooli.com",
zipcode="91364",
billing_configuration=CustomerBillingConfiguration(
invoice_grace_period=3,
payment_provider="stripe",
provider_customer_id="cus_12345",
sync=true,
sync_with_provider=true,
document_locale="fr"
),
metadata=MetadataList(__root__=[metadata_object])
)
try:
client.customers.create(customer)
except LagoApiError as e:
repair_broken_state(e) # do something on error or raise your own exception
```
```ruby Ruby theme={"dark"}
require 'lago-ruby-client'
client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
client.customers.create(
external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
address_line1: "5230 Penfield Ave",
address_line2: nil,
city: "Woodland Hills",
country: "US",
currency: "USD",
email: "dinesh@piedpiper.test",
legal_name: "Coleman-Blair",
legal_number: "49-008-2965",
tax_identification_number: "EU123456789",
logo_url: "http://hooli.com/logo.png",
name: "Gavin Belson",
phone: "1-171-883-3711 x245",
state: "CA",
timezone: "Europe/Paris",
url: "http://hooli.com",
zipcode: "91364",
billing_configuration: {
invoice_grace_period: 3,
payment_provider: "stripe",
provider_customer_id: "cus_12345",
sync: true,
sync_with_provider: true,
document_locale: "fr",
provider_payment_methods: ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
},
metadata: [
{
key: 'Purchase Order',
value: '123456789',
display_in_invoice: true
}
],
tax_codes: ["french_standard_vat"]
)
```
```js Javascript theme={"dark"}
import { BillingConfigurationCustomer } from "lago-javascript-client";
const customerObject = {
external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
address_line1: "5230 Penfield Ave",
city: "Woodland Hills",
currency: "EUR",
country: "US",
email: "dinesh@piedpiper.test",
legal_name: "Coleman-Blair",
legal_number: "49-008-2965",
tax_identification_number: "EU123456789",
logo_url: "http://hooli.com/logo.png",
name: "Gavin Belson",
phone: "1-171-883-3711 x245",
state: "CA",
timezone: "Europe/Paris",
url: "http://hooli.com",
zipcode: "91364",
billing_configuration: {
invoice_grace_period: 3,
paymentProvider:
"stripe" as BillingConfigurationCustomer["paymentProvider"],
provider_customer_id: "cus_12345",
sync: true,
sync_with_provider: true,
document_locale: "fr"
},
metadata: [
{
key: "Purchase Order",
value: "123456789",
display_in_invoice: true,
},
],
};
await client.customers.createCustomer({ customer: customerObject });
```
```go Go theme={"dark"}
import "fmt"
import "github.com/getlago/lago-go-client"
func main() {
lagoClient := lago.New().
SetApiKey("__YOUR_API_KEY__")
customerInput := &lago.CustomerInput{
ExternalID: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
Name: "Gavin Belson",
Email: "dinesh@piedpiper.test",
AddressLine1: "5230 Penfield Ave",
AddressLine2: "",
City: "Woodland Hills",
Country: "US",
Currency: "USD",
State: "CA",
Zipcode: "75001",
LegalName: "Coleman-Blair",
LegalNumber: "49-008-2965",
TaxIdentificationNumber: "EU123456789",
Phone: "+330100000000",
Timezone: "Europe/Paris",
URL: "http://hooli.com",
BillingConfiguration: &CustomerBillingConfigurationInput{
InvoiceGracePeriod: 3,
PaymentProvider: lago.PaymentProviderStripe,
ProviderCustomerID: "cus_123456789",
SyncWithProvider: true,
DocumentLocale: "fr"
},
Metadata: [
&CustomerMetadataInput{
Key: "Purchase Order",
Value: "123456789",
DisplayInInvoice: true
}
]
}
customer, err := lagoClient.Customer().Create(customerInput)
if err != nil {
// Error is *lago.Error
panic(err)
}
// You can use the same input to update the customer
customer, err := lagoClient.Customer().Update(customerInput)
if err != nil {
// Error is *lago.Error
panic(err)
}
// customer is *lago.Customer
fmt.Println(customer)
}
```
## OpenAPI
````yaml POST /customers
openapi: 3.1.0
info:
title: Lago API documentation
description: >-
Lago API allows your application to push customer information and metrics
(events) from your application to the billing application.
version: 1.46.0
license:
name: AGPLv3
url: https://github.com/getlago/lago-openapi/blob/main/LICENSE
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 Lago cluster
security:
- bearerAuth: []
tags:
- name: activity_logs
description: Everything about Activity logs
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/audit-logs/activity-logs-object
- name: analytics
description: Everything about Analytics
- name: api_logs
description: Everything about API logs
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/audit-logs/api-logs-object
- name: billable_metrics
description: Everything about Billable metric collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/billable-metrics/object
- name: features
description: Everything about Feature collection
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/entitlements/features/feature-object
- name: entitlements
description: Everything about Entitlement collection
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object
- name: billing_entities
description: Everything about Billing Entities
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/billing-entities/object
- name: customers
description: Everything about Customer collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/customers/object
- name: plans
description: Everything about Plan collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/plans/object
- name: subscriptions
description: Everything about Subscription collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/subscriptions/subscription-object
- name: events
description: Everything about Event collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/events/event-object
- name: organizations
description: Everything about Organization collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/organizations/organization-object
- name: taxes
description: Everything about Tax collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/taxes/tax-object
- name: coupons
description: Everything about Coupon collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/coupons/coupon-object
- name: add_ons
description: Everything about Add-on collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/add-ons/add-on-object
- name: fees
description: Everything about Fees
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/invoices/invoice-object#fee-object
- name: invoices
description: Everything about Invoice collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/invoices/invoice-object
- name: wallets
description: Everything about Wallet collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/wallets/wallet-object
- name: credit_notes
description: Everything about Credit notes collection
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/credit-notes/credit-note-object
- name: webhooks
description: Everything about Webhooks
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/webhooks/format---signature#1-retrieve-the-public-key
- name: webhook_endpoints
description: Everything about Webhook Endpoints
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object
- name: payment_receipts
description: Everything about Payment receipts
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object
- name: payment_requests
description: Everything about PaymentRequests
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/payment-requests/payment-request-object
- name: payments
description: Everything about Payments
externalDocs:
description: Find out more
url: https://getlago.com/docs/api-reference/payments/payment-object
- name: payment_methods
description: Everything about Payment Methods
externalDocs:
description: Find out more
url: >-
https://getlago.com/docs/api-reference/payment-methods/payment-method-object
externalDocs:
description: Lago Github
url: https://github.com/getlago
paths:
/customers:
post:
tags:
- customers
summary: 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'
components:
schemas:
CustomerCreateInput:
type: object
required:
- customer
properties:
customer:
type: object
required:
- external_id
properties:
external_id:
type: string
description: >-
The customer external unique identifier (provided by your own
application)
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
billing_entity_code:
type:
- string
- 'null'
example: acme_corp
description: >-
The unique code of the billing entity to associate with the
customer. If not provided, the default billing entity will be
used.
address_line1:
type:
- string
- 'null'
example: 5230 Penfield Ave
description: The first line of the billing address
address_line2:
type:
- string
- 'null'
example: ''
description: The second line of the billing address
city:
type:
- string
- 'null'
example: Woodland Hills
description: The city of the customer's billing address
country:
$ref: '#/components/schemas/CountryOrNull'
description: >-
Country code of the customer's billing address. Format must be
ISO 3166 (alpha-2)
example: US
currency:
$ref: '#/components/schemas/CurrencyOrNull'
description: Currency of the customer. Format must be ISO 4217
email:
type:
- string
- 'null'
format: email
example: dinesh@piedpiper.test
description: The email of the customer
legal_name:
type:
- string
- 'null'
example: Coleman-Blair
description: The legal company name of the customer
legal_number:
type:
- string
- 'null'
example: 49-008-2965
description: The legal company number of the customer
logo_url:
type:
- string
- 'null'
example: http://hooli.com/logo.png
description: The logo URL of the customer
name:
type:
- string
- 'null'
example: Gavin Belson
description: The full name of the customer
firstname:
type:
- string
- 'null'
example: Gavin
description: First name of the customer
lastname:
type:
- string
- 'null'
example: Belson
description: Last name of the customer
account_type:
type:
- string
- 'null'
enum:
- customer
- partner
- null
example: customer
description: >-
The type of the account. It can have one of the following
values:
- `customer`: the account is a customer, default value.
- `partner`: the account is a partner.
customer_type:
type:
- string
- 'null'
enum:
- company
- individual
- null
description: >-
The type of the customer. It can have one of the following
values:
- `company`: the customer is a company.
- `individual`: the customer is an individual.
phone:
type:
- string
- 'null'
example: 1-171-883-3711 x245
description: The phone number of the customer
state:
type:
- string
- 'null'
example: CA
description: The state of the customer's billing address
tax_codes:
$ref: '#/components/schemas/TaxCodes'
tax_identification_number:
type:
- string
- 'null'
example: EU123456789
description: The tax identification number of the customer
timezone:
$ref: '#/components/schemas/TimezoneOrNull'
description: >-
The customer's timezone, used for billing purposes in their
local time. Overrides the organization's timezone
url:
type:
- string
- 'null'
example: http://hooli.com
description: The custom website URL of the customer
zipcode:
type:
- string
- 'null'
example: '91364'
description: The zipcode of the customer's billing address
net_payment_term:
type:
- integer
- 'null'
example: 30
description: >-
The net payment term, expressed in days, specifies the duration
within which a customer is expected to remit payment after the
invoice is finalized.
finalize_zero_amount_invoice:
type: string
enum:
- inherit
- skip
- finalize
example: inherit
description: >-
Specifies how invoices with a zero total amount should be
handled:
- `inherit`: (Default) Follows the organization-level
configuration.
- `finalize`: Invoices are issued and finalized even if the
total amount is zero.
- `skip`: Invoices with a total amount of zero are not
finalized.
billing_configuration:
$ref: '#/components/schemas/CustomerBillingConfiguration'
shipping_address:
$ref: '#/components/schemas/Address'
integration_customers:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: >-
A unique identifier for the integration customer object in
the Lago application.
integration_type:
type: string
example: netsuite
description: |-
The integration type used for accounting and tax syncs.
Accepted values: `netsuite, anrok, xero`.
enum:
- netsuite
- anrok
- xero
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.
metadata:
type: array
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
items:
type: object
required:
- key
- value
- display_in_invoice
properties:
id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: >-
Identifier for the metadata object, only required when
updating 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.
skip_invoice_custom_sections:
type: boolean
example: false
description: >-
Set to `true` to exclude all invoice custom sections from PDF
generation for this customer only. False by default
invoice_custom_section_codes:
type: array
items:
type: string
description: List of unique codes identifying the invoice custom sections.
example:
- eu_bank_details
Customer:
type: object
required:
- customer
properties:
customer:
$ref: '#/components/schemas/CustomerObjectExtended'
CountryOrNull:
type:
- string
- 'null'
example: US
enum:
- null
- 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
CurrencyOrNull:
type:
- string
- 'null'
example: USD
enum:
- null
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BWP
- BYN
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNY
- COP
- CRC
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- ISK
- JMD
- JPY
- KES
- KGS
- KHR
- KMF
- KRW
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SEK
- SGD
- SHP
- SLL
- SOS
- SRD
- STD
- SZL
- THB
- TJS
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VND
- VUV
- WST
- XAF
- XCD
- XOF
- XPF
- YER
- ZAR
- ZMW
TaxCodes:
type: array
items:
type: string
description: List of unique code used to identify the taxes.
example:
- french_standard_vat
TimezoneOrNull:
type:
- string
- 'null'
example: America/Los_Angeles
enum:
- null
- 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
CustomerBillingConfiguration:
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:
invoice_grace_period:
type: integer
example: 3
description: >-
The grace period, expressed in days, for the invoice. This period
refers to the additional time granted to the customer beyond the
invoice due date to adjust usage and line items
subscription_invoice_issuing_date_anchor:
type:
- string
- 'null'
example: next_period_start
description: >-
Defines whether the issuing date follows the current billing
period's end date or the next period starting date.
enum:
- current_period_end
- next_period_start
- null
default: null
subscription_invoice_issuing_date_adjustment:
type:
- string
- 'null'
example: keep_anchor
description: >-
The logic applied on top of the
subscription_invoice_issuing_date_anchor rule. You can opt to use
the invoice finalization date, that includes any configured grace
period.
enum:
- align_with_finalization_date
- keep_anchor
- null
default: null
payment_provider:
type: string
example: stripe
description: >-
The payment provider utilized to initiate payments for invoices
issued by Lago.
Accepted values: `stripe`, `adyen`, `gocardless` or null. This field
is required if you intend to assign a `provider_customer_id`.
enum:
- stripe
- adyen
- gocardless
payment_provider_code:
type: string
example: stripe-eu-1
description: Unique code used to identify a payment provider connection.
provider_customer_id:
type: string
example: cus_12345
description: >-
The customer ID within the payment provider's system. If this field
is not provided, Lago has the option to create a new customer record
within the payment provider's system on behalf of the customer
sync:
type: boolean
example: true
description: >-
Set this field to `true` if you want to create the customer in the
payment provider synchronously with the customer creation process in
Lago. This option is applicable only when the `provider_customer_id`
is `null` and the customer is automatically created in the payment
provider through Lago. By default, the value is set to `false`
sync_with_provider:
type: boolean
example: true
description: >-
Set this field to `true` if you want to create a customer record in
the payment provider's system. This option is applicable only when
the `provider_customer_id` is null and the `sync_with_provider`
field is set to `true`. By default, the value is set to `false`
document_locale:
type: string
example: fr
description: >-
The document locale, specified in the ISO 639-1 format. This field
represents the language or locale used for the documents issued by
Lago
provider_payment_methods:
type:
- array
- 'null'
items:
type: string
description: >-
Specifies the available payment methods that can be used for this
customer when `payment_provider` is set to `stripe`. The
`provider_payment_methods` field is an array that allows multiple
payment options to be defined. If this field is not explicitly set,
the payment methods will be set to `card`. For now, possible values
are `card`, `sepa_debit`, `us_bank_account`, `bacs_debit`, `boleto`,
`link`, `crypto` and `customer_balance`. Note that when `link` is
selected, `card` should also be provided in the array. When
`customer_balance` is selected, no other payment can be selected.
example:
- card
- sepa_debit
- us_bank_account
- bacs_debit
- link
- boleto
- crypto
- customer_balance
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
- 'null'
example: 5230 Penfield Ave
description: The first line of the billing address
address_line2:
type:
- string
- 'null'
example: null
description: The second line of the billing address
city:
type:
- string
- 'null'
example: Woodland Hills
description: The city of the customer's billing address
country:
$ref: '#/components/schemas/CountryOrNull'
description: >-
Country code of the customer's billing address. Format must be ISO
3166 (alpha-2)
example: US
state:
type:
- string
- 'null'
example: CA
description: The state of the customer's billing address
zipcode:
type:
- string
- 'null'
example: '91364'
description: The zipcode of the customer's billing address
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'
applicable_invoice_custom_sections:
description: >-
The customer’s invoice custom section used for generating
invoices.
type: array
items:
$ref: '#/components/schemas/InvoiceCustomSectionObject'
error_details:
description: >-
List of errors with details that might have been raised while
processing backgroud actions for the customers
type: array
items:
$ref: '#/components/schemas/ErrorDetailObject'
ApiErrorBadRequest:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 400
error:
type: string
example: Bad request
ApiErrorUnauthorized:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 401
error:
type: string
example: Unauthorized
ApiErrorUnprocessableEntity:
type: object
required:
- status
- error
- code
- error_details
properties:
status:
type: integer
format: int32
example: 422
error:
type: string
example: Unprocessable entity
code:
type: string
example: validation_errors
error_details:
type: object
CustomerObject:
allOf:
- $ref: '#/components/schemas/CustomerBaseObject'
- type: object
properties:
integration_customers:
type: array
items:
$ref: '#/components/schemas/IntegrationCustomer'
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
TaxObject:
type: object
required:
- lago_id
- name
- code
- rate
- applied_to_organization
- created_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the tax, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
name:
type: string
description: Name of the tax.
example: TVA
code:
type: string
description: >-
Unique code used to identify the tax associated with the API
request.
example: french_standard_vat
description:
type:
- string
- 'null'
description: Internal description of the tax
example: French standard VAT
rate:
type: number
description: The percentage rate of the tax
example: 20
applied_to_organization:
type: boolean
deprecated: true
description: >-
This field is deprecated and will be removed in a future version.
When set to true, it applies the tax to the organization's default
billing entity. To apply or remove a tax from any billing entity
(including the default one), please use the `PUT
/billing_entities/:code` endpoint instead.
example: true
created_at:
type: string
format: date-time
description: Creation date of the tax.
example: '2023-07-06T14:35:58Z'
InvoiceCustomSectionObject:
type: object
required:
- lago_id
- name
- code
properties:
lago_id:
type: string
format: uuid
description: >-
Unique identifier for the invoice custom section in the Lago
application, generated by Lago to ensure record uniqueness within
the system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
name:
type: string
description: Name of the invoice custom section.
example: EU Bank Details
code:
type: string
description: >-
Unique code identifying the invoice custom section for the API
request.
example: eu_bank_details
description:
type: string
description: Internal description of the invoice custom section.
example: This section contains the bank details for EU customers.
details:
type: string
description: The value shown on the invoice PDF.
example: 'Bank Name: Lago Bank, IBAN: FR7630004000031234567890143'
display_name:
type: string
description: The name of the invoice custom section displayed on the invoice.
example: 'Bank Details:'
applied_to_organization:
type: boolean
deprecated: true
description: >-
This field is deprecated and will be removed in a future version.
When set to true, it applies the invoice custom section to the
organization's default billing entity. To apply or remove an invoice
custom section from any billing entity (including the default one),
please use the `PUT /billing_entities/:code` endpoint instead.
example: true
organization_id:
type: string
format: uuid
description: >-
Unique identifier for the organization associated with the invoice
custom section.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
created_at:
type: string
format: date-time
description: Creation date of the tax.
example: '2023-07-06T14:35:58Z'
ErrorDetailObject:
type: object
required:
- lago_id
- error_code
- details
properties:
lago_id:
type:
- string
- 'null'
format: uuid
description: >-
Unique identifier assigned to the error_detail within the Lago
application. This ID is exclusively created by Lago and serves as a
unique identifier for the error's record within the Lago system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
error_code:
type: string
description: >-
Code that specifies part of the application / connection, where the
error originally happened
example: tax_error
details:
type: object
description: >-
Key value list of more elaborated error detail, where by the key of
error_code an external service error details are stored
example:
tax_error: taxDateTooFarInFuture
additionalProperties:
type: string
CustomerBaseObject:
type: object
required:
- lago_id
- sequential_id
- slug
- external_id
- applicable_timezone
- created_at
properties:
lago_id:
type: string
format: uuid
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
sequential_id:
type: integer
example: 1
description: >-
The unique identifier assigned to the customer within the
organization's scope. This identifier is used to track and reference
the customer's order of creation within the organization's system.
It ensures that each customer has a distinct `sequential_id``
associated with them, allowing for easy identification and sorting
based on the order of creation
slug:
type: string
example: LAG-1234-001
description: >-
A concise and unique identifier for the customer, formed by
combining the Organization's `name`, `id`, and customer's
`sequential_id`
external_id:
type: string
description: >-
The customer external unique identifier (provided by your own
application)
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
billing_entity_code:
type: string
example: acme_corp
description: The unique code of the billing entity associated with the customer.
address_line1:
type:
- string
- 'null'
example: 5230 Penfield Ave
description: The first line of the billing address
address_line2:
type:
- string
- 'null'
example: null
description: The second line of the billing address
applicable_timezone:
$ref: '#/components/schemas/Timezone'
description: >-
The customer's applicable timezone, used for billing purposes in
their local time.
city:
type:
- string
- 'null'
example: Woodland Hills
description: The city of the customer's billing address
country:
$ref: '#/components/schemas/CountryOrNull'
description: >-
Country code of the customer's billing address. Format must be ISO
3166 (alpha-2)
example: US
currency:
$ref: '#/components/schemas/CurrencyOrNull'
example: USD
description: Currency of the customer. Format must be ISO 4217
email:
type:
- string
- 'null'
format: email
example: dinesh@piedpiper.test
description: The email of the customer
legal_name:
type:
- string
- 'null'
example: Coleman-Blair
description: The legal company name of the customer
legal_number:
type:
- string
- 'null'
example: 49-008-2965
description: The legal company number of the customer
logo_url:
type:
- string
- 'null'
example: http://hooli.com/logo.png
description: The logo URL of the customer
name:
type:
- string
- 'null'
example: Gavin Belson
description: The full name of the customer
firstname:
type:
- string
- 'null'
example: Gavin
description: First name of the customer
lastname:
type:
- string
- 'null'
example: Belson
description: Last name of the customer
account_type:
type: string
enum:
- customer
- partner
example: customer
description: |-
The type of the account. It can have one of the following values:
- `customer`: the account is a customer.
- `partner`: the account is a partner.
customer_type:
type:
- string
- 'null'
enum:
- company
- individual
- null
description: |-
The type of the customer. It can have one of the following values:
- `company`: the customer is a company.
- `individual`: the customer is an individual.
phone:
type:
- string
- 'null'
example: 1-171-883-3711 x245
description: The phone number of the customer
state:
type:
- string
- 'null'
example: CA
description: The state of the customer's billing address
tax_identification_number:
type:
- string
- 'null'
example: EU123456789
description: The tax identification number of the customer
timezone:
$ref: '#/components/schemas/TimezoneOrNull'
description: >-
The customer's timezone, used for billing purposes in their local
time. Overrides the organization's timezone
url:
type:
- string
- 'null'
example: http://hooli.com
description: The custom website URL of the customer
zipcode:
type:
- string
- 'null'
example: '91364'
description: The zipcode of the customer's billing address
net_payment_term:
type:
- integer
- 'null'
example: 30
description: >-
The net payment term, expressed in days, specifies the duration
within which a customer is expected to remit payment after the
invoice is finalized.
created_at:
type: string
format: date-time
example: '2022-04-29T08:59:51Z'
description: >-
The date of the customer 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 customer object was created
updated_at:
type: string
format: date-time
example: '2022-04-29T08:59:51Z'
description: >-
The date of the customer update, represented in ISO 8601 datetime
format and expressed in Coordinated Universal Time (UTC). The
update_date provides a standardized and internationally recognized
timestamp for when the customer object was updated
finalize_zero_amount_invoice:
type: string
enum:
- inherit
- skip
- finalize
example: inherit
description: >-
Specifies how invoices with a zero total amount should be handled:
- `inherit`: (Default) Follows the organization-level configuration.
- `finalize`: Invoices are issued and finalized even if the total
amount is zero.
- `skip`: Invoices with a total amount of zero are not finalized.
skip_invoice_custom_sections:
type: boolean
example: false
description: >-
Set to true to exclude all invoice custom sections from PDF
generation for this customer only.
billing_configuration:
$ref: '#/components/schemas/CustomerBillingConfiguration'
shipping_address:
$ref: '#/components/schemas/Address'
metadata:
type: array
items:
$ref: '#/components/schemas/CustomerMetadata'
IntegrationCustomer:
type: object
required:
- lago_id
- type
- external_customer_id
- integration_code
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
- xero
- hubspot
- salesforce
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
- 'null'
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.
targeted_object:
type:
- string
- 'null'
example: contacts
description: >-
This optional field is present only when working with `hubspot`
connection.
email:
type:
- string
- 'null'
example: dinesh@piedpiper.test
description: >-
This optional field is present only when working with `hubspot`
connection.
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/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/Nuuk
- 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/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/Yangon
- 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/Kyiv
- 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
responses:
BadRequest:
description: Bad Request error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBadRequest'
Unauthorized:
description: Unauthorized error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorUnauthorized'
UnprocessableEntity:
description: Unprocessable entity error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorUnprocessableEntity'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````