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 billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC). example: '2022-07-31T23:59:59Z' issuing_date: type: string format: date description: The date of creation of the invoice. example: '2022-08-01' lago_invoice_id: type: string format: uuid nullable: true example: 1a901a90-1a90-1a90-1a90-1a901a901a90 description: A unique identifier associated with the invoice related to this particular usage record. currency: allOf: - $ref: '#/components/schemas/Currency' - description: The currency of the customer's current usage. example: EUR amount_cents: type: integer description: The amount in cents, tax excluded. example: 123 taxes_amount_cents: type: integer description: The tax amount in cents. example: 200 total_amount_cents: type: integer description: The total amount in cents, tax included. example: 123 charges_usage: type: array description: Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage. items: $ref: '#/components/schemas/CustomerChargeUsageObject' CustomerCreateInput: type: object required: - customer properties: customer: type: object required: - external_id properties: external_id: type: string example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba description: The customer external unique identifier (provided by your own application) address_line1: type: string example: 5230 Penfield Ave description: The first line of the billing address nullable: true address_line2: type: string example: '' 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 currency: allOf: - $ref: '#/components/schemas/Currency' - description: Currency of the customer. Format must be ISO 4217 nullable: true email: type: string format: email example: dinesh@piedpiper.test description: The email of the customer nullable: true legal_name: type: string example: Coleman-Blair description: The legal company name of the customer nullable: true legal_number: type: string example: 49-008-2965 description: The legal company number of the customer nullable: true logo_url: type: string example: http://hooli.com/logo.png description: The logo URL of the customer nullable: true name: type: string example: Gavin Belson description: The full name of the customer nullable: true firstname: type: string example: Gavin description: First name of the customer nullable: true lastname: type: string example: Belson description: Last name of the customer nullable: true customer_type: type: string enum: - company - individual nullable: true 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 example: 1-171-883-3711 x245 description: The phone number of the customer nullable: true state: type: string example: CA description: The state of the customer's billing address nullable: true tax_codes: type: array items: type: string description: List of unique code used to identify the taxes. example: - french_standard_vat tax_identification_number: type: string example: EU123456789 description: The tax identification number of the customer nullable: true timezone: allOf: - $ref: '#/components/schemas/Timezone' - description: The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone nullable: true url: type: string example: http://hooli.com description: The custom website URL of the customer nullable: true zipcode: type: string example: '91364' description: The zipcode of the customer's billing address nullable: true 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. nullable: true 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. 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 CustomerPastUsage: type: object required: - usage_periods - meta properties: usage_periods: type: array items: $ref: '#/components/schemas/CustomerUsage' meta: $ref: '#/components/schemas/PaginationMeta' 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 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 nullable: true 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` and `link`. Note that when `link` is selected, `card` should also be provided in the array. example: - card - sepa_debit ApiErrorUnauthorized: type: object required: - status - error properties: status: type: integer format: int32 example: 401 error: type: string example: Unauthorized ApiErrorBadRequest: type: object required: - status - error properties: status: type: integer format: int32 example: 400 error: type: string example: Bad request 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 CustomerUsage: type: object required: - customer_usage properties: customer_usage: $ref: '#/components/schemas/CustomerUsageObject' CustomerChargeGroupedUsageObject: type: array description: Array of aggregated fees, grouped by the event properties defined in a `standard` charge model. required: - amount_cents - events_count - units - grouped_by - groups items: type: object properties: amount_cents: type: integer example: 1000 description: The amount in cents, tax excluded, consumed for a specific group related to a 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. units: type: string pattern: ^[0-9]+.?[0-9]*$ example: '0.9' description: The number of units consumed for a specific group related to a charge item. grouped_by: type: object description: Key value list of event properties aggregated by the charge model additionalProperties: type: string filters: $ref: '#/components/schemas/CustomerChargeFiltersUsageObject' CustomerObject: allOf: - 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 example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba description: The customer external unique identifier (provided by your own application) 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 applicable_timezone: allOf: - $ref: '#/components/schemas/Timezone' - description: The customer's applicable timezone, used for billing purposes in their local time. 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 currency: allOf: - $ref: '#/components/schemas/Currency' - example: USD description: Currency of the customer. Format must be ISO 4217 nullable: true email: type: string format: email example: dinesh@piedpiper.test description: The email of the customer nullable: true legal_name: type: string example: Coleman-Blair description: The legal company name of the customer nullable: true legal_number: type: string example: 49-008-2965 description: The legal company number of the customer nullable: true logo_url: type: string example: http://hooli.com/logo.png description: The logo URL of the customer nullable: true name: type: string example: Gavin Belson description: The full name of the customer nullable: true firstname: type: string example: Gavin description: First name of the customer nullable: true lastname: type: string example: Belson description: Last name of the customer nullable: true customer_type: type: string enum: - company - individual nullable: true 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 example: 1-171-883-3711 x245 description: The phone number of the customer nullable: true state: type: string example: CA description: The state of the customer's billing address nullable: true tax_identification_number: type: string example: EU123456789 description: The tax identification number of the customer nullable: true timezone: allOf: - $ref: '#/components/schemas/Timezone' - description: The customer's timezone, used for billing purposes in their local time. Overrides the organization's timezone nullable: true url: type: string example: http://hooli.com description: The custom website URL of the customer nullable: true zipcode: type: string example: '91364' description: The zipcode of the customer's billing address nullable: true 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. nullable: true 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.' billing_configuration: $ref: '#/components/schemas/CustomerBillingConfiguration' shipping_address: $ref: '#/components/schemas/Address' metadata: type: array items: $ref: '#/components/schemas/CustomerMetadata' - type: object properties: integration_customers: type: array items: $ref: '#/components/schemas/IntegrationCustomer' AppliedCoupon: type: object required: - applied_coupon properties: applied_coupon: $ref: '#/components/schemas/AppliedCouponObject' CustomerChargeFiltersUsageObject: type: array description: Array of filter object, representing multiple dimensions for a charge item. required: - values - units - events_count - amount_cents items: type: object properties: units: type: string pattern: ^[0-9]+.?[0-9]*$ example: '0.9' description: The number of units consumed for a specific charge filter related to a charge item. amount_cents: type: integer example: 1000 description: The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item. events_count: type: integer example: 10 description: The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts. invoice_display_name: type: string description: Specifies the name that will be displayed on an invoice. example: AWS eu-east-1 values: type: object description: List of filter values applied to the usage. additionalProperties: type: string example: region: us-east-1 CustomersPaginated: type: object required: - customers - meta properties: customers: type: array items: $ref: '#/components/schemas/CustomerObjectExtended' meta: $ref: '#/components/schemas/PaginationMeta' 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' responses: BadRequest: description: Bad Request error content: application/json: schema: $ref: '#/components/schemas/ApiErrorBadRequest' NotFound: description: Not Found error content: application/json: schema: $ref: '#/components/schemas/ApiErrorNotFound' 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' parameters: page: name: page in: query description: Page number. required: false explode: true schema: type: integer example: 1 per_page: name: per_page in: query description: Number of records per page. required: false explode: true schema: type: integer example: 20 securitySchemes: bearerAuth: type: http scheme: bearer externalDocs: description: Lago Github url: https://github.com/getlago