OpenAPI Specification
openapi: 3.1.0
info:
title: Lago API documentation Add_ons Organizations 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: Organizations
description: Everything about Organization collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/organizations/organization-object
paths:
/organizations:
put:
tags:
- Organizations
summary: Lago Update your organization
description: This endpoint is used to update your own organization's settings.
operationId: updateOrganization
requestBody:
description: Update an existing organization
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationUpdateInput'
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
schemas:
OrganizationObject:
type: object
required:
- lago_id
- name
- created_at
- document_numbering
- document_number_prefix
- email_settings
- billing_configuration
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the organization within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the organization's record within the Lago system
name:
type: string
example: Name1
description: The name of your organization.
created_at:
type: string
format: date-time
example: '2022-05-02T13:04:09Z'
description: The date of creation of your organization, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
nullable: true
webhook_url:
type: string
example: https://webhook.brex.com
description: The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Lago system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner.
nullable: true
webhook_urls:
type: array
items:
type: string
example:
- https://webhook.brex.com
- https://webhook2.brex.com
description: The array containing your webhooks URLs.
nullable: true
country:
allOf:
- $ref: '#/components/schemas/Country'
- nullable: true
description: The country of your organization.
example: US
default_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The default currency of an organization.
example: USD
address_line1:
type: string
example: 100 Brex Street
description: The first line of your organization's billing address.
nullable: true
address_line2:
type: string
example: null
description: The second line of your organization's billing address.
nullable: true
state:
type: string
example: NYC
description: The state of your organization's billing address.
nullable: true
zipcode:
type: string
example: '10000'
description: The zipcode of your organization's billing address.
nullable: true
email:
type: string
format: email
example: brex@brex.com
description: The email address of your organization used to bill your customers.
nullable: true
city:
type: string
example: New York
description: The city of your organization's billing address.
nullable: true
legal_name:
type: string
example: null
description: The legal name of your organization.
nullable: true
legal_number:
type: string
example: null
description: The legal number of your organization.
nullable: true
document_numbering:
type: string
enum:
- per_customer
- per_organization
example: per_customer
description: 'This parameter configures the method of incrementing invoice numbers for your customers.
- `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer''s invoice numbers follow a distinct and isolated numbering pattern.
- `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month.
The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer.'
document_number_prefix:
type: string
example: ORG-1234
description: Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Lago.
net_payment_term:
type: integer
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.
tax_identification_number:
type: string
example: US123456789
description: The tax identification number of your organization.
nullable: true
timezone:
allOf:
- $ref: '#/components/schemas/Timezone'
- description: Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone.
example: America/New_York
billing_configuration:
$ref: '#/components/schemas/OrganizationBillingConfiguration'
taxes:
type: array
description: List of default organization taxes
items:
$ref: '#/components/schemas/TaxObject'
finalize_zero_amount_invoice:
type: boolean
example: false
description: Indicates whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized.
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
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
OrganizationBillingConfiguration:
type: object
description: The custom billing settings for your organization.
properties:
invoice_footer:
type: string
example: This is my customer footer
description: The customer invoice message that appears at the bottom of each billing documents.
nullable: true
invoice_grace_period:
type: integer
example: 3
description: The grace period, expressed in days, for finalizing the invoice. This period refers to the additional time granted to your customers beyond the invoice due date to adjust usage and line items. Can be overwritten by the customer's grace period.
document_locale:
type: string
example: en
description: The locale of the billing documents, expressed in the ISO 639-1 format. This field indicates the language or regional variant used for the documents content issued or the embeddable customer portal.
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
Organization:
type: object
required:
- organization
properties:
organization:
$ref: '#/components/schemas/OrganizationObject'
ApiErrorUnauthorized:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 401
error:
type: string
example: Unauthorized
OrganizationUpdateInput:
type: object
required:
- organization
properties:
organization:
type: object
properties:
webhook_url:
type: string
example: https://webhook.brex.com
description: The URL of your newest updated webhook endpoint. This URL allows your organization to receive important messages, notifications, or data from the Lago system. By configuring your webhook endpoint to this URL, you can ensure that your organization stays informed and receives relevant information in a timely manner.
nullable: true
country:
allOf:
- $ref: '#/components/schemas/Country'
- nullable: true
description: The country of your organization.
example: US
default_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The default currency of an organization.
example: USD
address_line1:
type: string
example: 100 Brex Street
description: The first line of your organization's billing address.
nullable: true
address_line2:
type: string
example: null
description: The second line of your organization's billing address.
nullable: true
state:
type: string
example: NYC
description: The state of your organization's billing address.
nullable: true
zipcode:
type: string
example: '10000'
description: The zipcode of your organization's billing address.
nullable: true
email:
type: string
format: email
example: brex@brex.com
description: The email address of your organization used to bill your customers.
nullable: true
city:
type: string
example: New York
description: The city of your organization's billing address.
nullable: true
legal_name:
type: string
example: null
description: The legal name of your organization.
nullable: true
legal_number:
type: string
example: null
description: The legal number of your organization.
nullable: true
document_numbering:
type: string
enum:
- per_customer
- per_organization
example: per_customer
description: 'This parameter configures the method of incrementing invoice numbers for your customers.
- `per_customer`: Invoice numbers are incremented individually for each customer. This means every customer will have their own unique sequence of invoice numbers, separate from other customers. It ensures that each customer''s invoice numbers follow a distinct and isolated numbering pattern.
- `per_organization`: Invoice number incrementation is made across your entire organization. Rather than individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers. Invoices are incremented per month (dynamic value used is YYYYMM), and invoice numbers are reset at the end of each month.
The default value for `document_numbering` is set to `per_customer`, meaning that, unless changed, invoice numbers will increment uniquely for each customer.'
document_number_prefix:
type: string
example: ORG-1234
description: Sets the prefix for invoices and credit notes. Default is the first three letters of your organization name plus the last four digits of your organization ID. Customizable within 1-10 characters, and automatically capitalized by Lago.
net_payment_term:
type: integer
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.
tax_identification_number:
type: string
example: US123456789
description: The tax identification number of your organization.
nullable: true
timezone:
allOf:
- $ref: '#/components/schemas/Timezone'
- description: Your organization's timezone, used for billing purposes in your own local time. Can be overwritten by the customer's timezone.
example: America/New_York
email_settings:
type: array
description: Represents the email settings of the organization. It allows you to define which documents are sent by email. The field value determines the types of documents that trigger email notifications. Possible values for are `invoice.finalized` and `credit_note.created`. By configuring this field, you can specify whether invoices, credit notes, or both should be sent to recipients via email.
example:
- invoice.finalized
- credit_note.created
items:
type: string
enum:
- invoice.finalized
- credit_note.created
billing_configuration:
$ref: '#/components/schemas/OrganizationBillingConfiguration'
finalize_zero_amount_invoice:
type: boolean
example: false
description: Determines whether invoices with a zero total amount should be finalized. If set to true, zero amount invoices will be finalized. If set to false, zero amount invoices will not be finalized.
ApiErrorBadRequest:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 400
error:
type: string
example: Bad request
TaxObject:
type: object
required:
- lago_id
- name
- code
- rate
- applied_to_organization
- customers_count
- 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
description: Internal description of the taxe
example: French standard VAT
rate:
type: number
description: The percentage rate of the tax
example: 20
applied_to_organization:
type: boolean
description: Set to `true` if the tax is used as one of the organization's default
example: true
add_ons_count:
type: integer
description: Number of add-ons this tax is applied to.
example: 0
charges_count:
type: integer
description: Number of charges this tax is applied to.
example: 0
customers_count:
type: integer
description: Number of customers this tax is applied to (directly or via the organization's default).
example: 0
plans_count:
type: integer
description: Number of plans this tax is applied to.
example: 0
created_at:
type: string
format: date-time
description: Creation date of the tax.
example: '2023-07-06T14:35:58Z'
Currency:
type: string
example: USD
enum:
- 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
responses:
BadRequest:
description: Bad Request error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBadRequest'
UnprocessableEntity:
description: Unprocessable entity error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorUnprocessableEntity'
Unauthorized:
description: Unauthorized error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorUnauthorized'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
externalDocs:
description: Lago Github
url: https://github.com/getlago