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