Create a customer

POST

customers

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"]
    }
  }'

{
  "customer": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "sequential_id": 1,
    "slug": "LAG-1234-001",
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "applicable_timezone": "America/Los_Angeles",
    "city": "Woodland Hills",
    "country": "US",
    "currency": "USD",
    "email": "dinesh@piedpiper.test",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Gavin Belson",
    "firstname": "Gavin",
    "lastname": "Belson",
    "account_type": "customer",
    "customer_type": "company",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "tax_identification_number": "EU123456789",
    "timezone": "America/Los_Angeles",
    "url": "http://hooli.com",
    "zipcode": "91364",
    "net_payment_term": 30,
    "created_at": "2022-04-29T08:59:51Z",
    "updated_at": "2022-04-29T08:59:51Z",
    "finalize_zero_amount_invoice": "inherit",
    "skip_invoice_custom_sections": false,
    "billing_configuration": {
      "invoice_grace_period": 3,
      "payment_provider": "stripe",
      "payment_provider_code": "stripe-eu-1",
      "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",
        "boleto",
        "crypto"
      ]
    },
    "shipping_address": {
      "address_line1": "5230 Penfield Ave",
      "address_line2": null,
      "city": "Woodland Hills",
      "country": "US",
      "state": "CA",
      "zipcode": "91364"
    },
    "metadata": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "Purchase Order",
        "value": "123456789",
        "display_in_invoice": true,
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "integration_customers": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "type": "netsuite",
        "integration_code": "netsuite-eu-1",
        "external_customer_id": "cus_12345",
        "sync_with_provider": true,
        "subsidiary_id": "2"
      }
    ],
    "taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "TVA",
        "code": "french_standard_vat",
        "description": "French standard VAT",
        "rate": 20,
        "applied_to_organization": true,
        "created_at": "2023-07-06T14:35:58Z"
      }
    ],
    "applicable_invoice_custom_sections": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "EU Bank Details",
        "code": "eu_bank_details",
        "description": "This section contains the bank details for EU customers.",
        "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
        "display_name": "Bank Details:",
        "applied_to_organization": true,
        "organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "created_at": "2023-07-06T14:35:58Z"
      }
    ]
  }
}

This endpoint performs an upsert operation.

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"]
    }
  }'

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Customer payload

customer

object

required

customer.external_id

string

required

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

customer.address_line1

string | null

The first line of the billing address

customer.address_line2

string | null

The second line of the billing address

customer.city

string | null

The city of the customer's billing address

customer.country

enum<string>

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

Available options:

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

customer.currency

enum<string>

Currency of the customer. Format must be ISO 4217

Available options:

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

customer.email

string | null

The email of the customer

customer.legal_name

string | null

The legal company name of the customer

customer.legal_number

string | null

The legal company number of the customer

customer.logo_url

string | null

The logo URL of the customer

customer.name

string | null

The full name of the customer

customer.firstname

string | null

First name of the customer

customer.lastname

string | null

Last name of the customer

customer.account_type

enum<string> | null

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.

Available options:

customer,

partner

customer.customer_type

enum<string> | null

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.

Available options:

company,

individual

customer.phone

string | null

The phone number of the customer

customer.state

string | null

The state of the customer's billing address

customer.tax_codes

string[]

List of unique code used to identify the taxes.

customer.tax_identification_number

string | null

The tax identification number of the customer

customer.timezone

enum<string>

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

Available options:

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

customer.url

string | null

The custom website URL of the customer

customer.zipcode

string | null

The zipcode of the customer's billing address

customer.net_payment_term

integer | null

The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.

customer.finalize_zero_amount_invoice

enum<string>

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.

Available options:

inherit,

skip,

finalize

customer.billing_configuration

object

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.

customer.billing_configuration.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

customer.billing_configuration.payment_provider

enum<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.

Available options:

stripe,

adyen,

gocardless

customer.billing_configuration.payment_provider_code

string

Unique code used to identify a payment provider connection.

customer.billing_configuration.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

customer.billing_configuration.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

customer.billing_configuration.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

customer.billing_configuration.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

customer.billing_configuration.provider_payment_methods

string[] | null

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 and crypto. Note that when link is selected, card should also be provided in the array.

customer.shipping_address

object

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.

customer.integration_customers

object[]

customer.metadata

object[]

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

customer.skip_invoice_custom_sections

boolean

Set to true to exclude all invoice custom sections from PDF generation for this customer only. False by default

customer.invoice_custom_section_codes

string[]

List of unique codes identifying the invoice custom sections.

Response

200

application/json

Customer created or updated

customer

object

required

customer.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

customer.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

customer.slug

string

required

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

customer.external_id

string

required

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

customer.applicable_timezone

enum<string>

required

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

Available options:

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

customer.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

customer.address_line1

string | null

The first line of the billing address

customer.address_line2

string | null

The second line of the billing address

customer.city

string | null

The city of the customer's billing address

customer.country

enum<string>

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

Available options:

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

customer.currency

enum<string>

Currency of the customer. Format must be ISO 4217

Available options:

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

customer.email

string | null

The email of the customer

customer.legal_name

string | null

The legal company name of the customer

customer.legal_number

string | null

The legal company number of the customer

customer.logo_url

string | null

The logo URL of the customer

customer.name

string | null

The full name of the customer

customer.firstname

string | null

First name of the customer

customer.lastname

string | null

Last name of the customer

customer.account_type

enum<string>

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.

Available options:

customer,

partner

customer.customer_type

enum<string> | null

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.

Available options:

company,

individual

customer.phone

string | null

The phone number of the customer

customer.state

string | null

The state of the customer's billing address

customer.tax_identification_number

string | null

The tax identification number of the customer

customer.timezone

enum<string>

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

Available options:

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

customer.url

string | null

The custom website URL of the customer

customer.zipcode

string | null

The zipcode of the customer's billing address

customer.net_payment_term

integer | null

The net payment term, expressed in days, specifies the duration within which a customer is expected to remit payment after the invoice is finalized.

customer.updated_at

string

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

customer.finalize_zero_amount_invoice

enum<string>

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.

Available options:

inherit,

skip,

finalize

customer.skip_invoice_custom_sections

boolean

Set to true to exclude all invoice custom sections from PDF generation for this customer only.

customer.billing_configuration

object

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.

customer.billing_configuration.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

customer.billing_configuration.payment_provider

enum<string>

Available options:

stripe,

adyen,

gocardless

customer.billing_configuration.payment_provider_code

string

Unique code used to identify a payment provider connection.

customer.billing_configuration.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

customer.billing_configuration.sync

boolean

customer.billing_configuration.sync_with_provider

boolean

customer.billing_configuration.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

customer.billing_configuration.provider_payment_methods

string[] | null

customer.shipping_address

object

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.

customer.metadata

object[]

customer.integration_customers

object[]

customer.taxes

object[]

List of customer taxes

customer.applicable_invoice_custom_sections

object[]

The customer’s invoice custom section used for generating invoices.

Was this page helpful?

Suggest edits Raise issue

The customer object Update a customer

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"]
    }
  }'

{
  "customer": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "sequential_id": 1,
    "slug": "LAG-1234-001",
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "applicable_timezone": "America/Los_Angeles",
    "city": "Woodland Hills",
    "country": "US",
    "currency": "USD",
    "email": "dinesh@piedpiper.test",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Gavin Belson",
    "firstname": "Gavin",
    "lastname": "Belson",
    "account_type": "customer",
    "customer_type": "company",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "tax_identification_number": "EU123456789",
    "timezone": "America/Los_Angeles",
    "url": "http://hooli.com",
    "zipcode": "91364",
    "net_payment_term": 30,
    "created_at": "2022-04-29T08:59:51Z",
    "updated_at": "2022-04-29T08:59:51Z",
    "finalize_zero_amount_invoice": "inherit",
    "skip_invoice_custom_sections": false,
    "billing_configuration": {
      "invoice_grace_period": 3,
      "payment_provider": "stripe",
      "payment_provider_code": "stripe-eu-1",
      "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",
        "boleto",
        "crypto"
      ]
    },
    "shipping_address": {
      "address_line1": "5230 Penfield Ave",
      "address_line2": null,
      "city": "Woodland Hills",
      "country": "US",
      "state": "CA",
      "zipcode": "91364"
    },
    "metadata": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "Purchase Order",
        "value": "123456789",
        "display_in_invoice": true,
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "integration_customers": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "type": "netsuite",
        "integration_code": "netsuite-eu-1",
        "external_customer_id": "cus_12345",
        "sync_with_provider": true,
        "subsidiary_id": "2"
      }
    ],
    "taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "TVA",
        "code": "french_standard_vat",
        "description": "French standard VAT",
        "rate": 20,
        "applied_to_organization": true,
        "created_at": "2023-07-06T14:35:58Z"
      }
    ],
    "applicable_invoice_custom_sections": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "EU Bank Details",
        "code": "eu_bank_details",
        "description": "This section contains the bank details for EU customers.",
        "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
        "display_name": "Bank Details:",
        "applied_to_organization": true,
        "organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "created_at": "2023-07-06T14:35:58Z"
      }
    ]
  }
}

API Reference

Authorizations

Body

Response