The customer object

This object represents a customer of your business. It lets you create or update a customer, but also track usage and create invoices for the same customer.

The customer object

{
  "customer": {
    "lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
    "sequential_id": "001",
    "slug": "LAG-1234-001",
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "city": "Woodland Hills",
    "country": "US",
    "created_at": "2022-04-29T08:59:51Z",
    "email": "[e-mail]",
    "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",
    "url": "http://hooli.com",
    "zipcode": "91364",
    "currency": "USD",
    "timezone": "Europe/Paris",
    "applicable_timezone": "Europe/Paris",
    "billing_configuration": {
      "invoice_grace_period": 3,
      "payment_provider": "stripe",
      "payment_provider_code": "stripe_eu",
      "provider_customer_id": "cus_12345",
      "sync_with_provider": true,
      "document_locale": "fr",
      "provider_payment_methods": ["card","sepa_debit", "us_bank_account", "bacs_debit"]
    },
    "metadata": [
      {
        "lago_id": "27f12d13-4ae0-437b-b822-8771bcd62e3a",
        "key": "Purchase Order",
        "value": "123456789",
        "display_in_invoice": true,
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "taxes": [
      {
        "lago_id": "173c9da8-effc-4db6-a341-1a2d2aa500e6",
        "name": "VAT",
        "code": "vat_fr",
        "rate": 20.0,
        "description": null,
        "applied_to_organization": false,
        "add_ons_count": 0,
        "customers_count": 1,
        "plans_count": 0,
        "charges_count": 1,
        "created_at": "2022-06-29T12:04:36Z"
      }
    ]
  }
}

Attributes

customer · object

Hide object

lago_id · string · required

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 · integer · required

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 · string · required

A concise and unique identifier for the customer, formed by combining the Organization’s name, id, and customer’s sequential_id.

external_id · string

The customer external unique identifier (provided by your own application).

address_line1 · string

The first line of the billing address.

address_line2 · string

The second line of the billing address.

applicable_timezone · string · required

The customer’s applicable timezone, used for billing purposes in their local time.

city · string

The city of the customer’s billing address.

country · string

Country code of the customer’s billing address. Format must be ISO 3166 (alpha-2).

currency · string

Currency of the customer. Format must be ISO 4217.

email · string

The email of the customer.

legal_name · string

The legal company name of the customer.

legal_number · string

The legal company number of the customer.

logo_url · string

The logo URL of the customer.

name · string

The full name of the customer.

state · string

The state of the customer’s billing address.

tax_identification_number · string

The tax identification number of the customer.

timezone · string

The customer’s timezone, used for billing purposes in their local time. Overrides the organization’s timezone.

url · string

The custom website URL of the customer.

zipcode · string

The zipcode of the customer’s billing address.

created_at · string · required

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.

billing_configuration · object

Show object

invoice_grace_period · integer

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 · string

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.

payment_provider_code · string

Unique code used to identify a payment provider connection.

provider_customer_id · string

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 · boolean

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 · boolean

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 · string

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 · array

Specifies the available payment method(s) 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 set by the user, card is selected by default. Possible values include card, sepa_debit, us_bank_account and bacs_debit.

metadata · array

Show array

lago_id · string · required

A unique identifier for the customer metadata object in the Lago application. Can be used to update a key-value pair.

key · string · required

The metadata object key.

value · string · required

The metadata object value.

display_in_invoice · boolean · required

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 · string · required

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.

taxes · array

Show array

lago_id · string · required

Unique identifier of tax object in the Lago application.

name · string · required

Name of the tax.

code · string · required

Unique code used to identify the tax object in the Lago application.

rate · float · required

The percentage rate of the tax.

description · string | null

Internal description of the tax.

applied_to_organization · boolean · required

Set to true if the tax is used as one of the organization’s default.

add_ons_count · integer · required

Number of add-ons this tax is applied to.

customers_count · integer · required

Number of customers this tax is applied to.

plans_count · integer · required

Number of plans this tax is applied to (directly or via the organization’s default).

charges_count · integer · required

Number of charges this tax is applied to.

created_at · string · required

Creation date of the tax object.