POST
/
billing_entities
Create a billing entity
curl --request POST \
  --url https://api.getlago.com/api/v1/billing_entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "billing_entity": {
    "code": "acme_corp",
    "name": "Acme Corp",
    "default_currency": "USD",
    "document_numbering": "per_customer",
    "document_number_prefix": "ABC-123",
    "finalize_zero_amount_invoice": true,
    "billing_configuration": {
      "invoice_footer": "Thank you for your business",
      "document_locale": "en",
      "invoice_grace_period": 0
    },
    "net_payment_term": 0,
    "address_line1": "5230 Penfield Ave",
    "address_line2": "Suite 100",
    "city": "Woodland Hills",
    "state": "CA",
    "country": "US",
    "zipcode": "91364",
    "email": "billing@acme.com",
    "legal_name": "Acme Corporation",
    "legal_number": "US123456789",
    "tax_identification_number": "EU123456789",
    "timezone": "UTC",
    "email_settings": [
      "invoice.finalized"
    ],
    "eu_tax_management": false,
    "logo": "data:image/png;base64,..."
  }
}'
{
  "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
  "code": "acme_corp",
  "name": "Acme Corp",
  "default_currency": "USD",
  "document_locale": "en",
  "document_numbering": "per_customer",
  "document_number_prefix": "ABC-123",
  "finalize_zero_amount_invoice": true,
  "invoice_footer": "Thank you for your business",
  "invoice_grace_period": 0,
  "is_default": false,
  "net_payment_term": 0,
  "address_line1": "5230 Penfield Ave",
  "address_line2": "Suite 100",
  "city": "Woodland Hills",
  "state": "CA",
  "country": "US",
  "zipcode": "91364",
  "email": "billing@acme.com",
  "legal_name": "Acme Corporation",
  "legal_number": "US123456789",
  "tax_identification_number": "EU123456789",
  "timezone": "UTC",
  "email_settings": [
    "invoice.finalized"
  ],
  "eu_tax_management": false,
  "logo_url": "https://getlago.com/logo.png",
  "created_at": "2022-04-29T08:59:51Z",
  "updated_at": "2022-04-29T08:59:51Z"
}

Authorizations

Authorization
string
header
required

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

Body

application/json

The billing entity payload

Billing entity create input

billing_entity
object
required

Response

200
application/json

Billing entity created

Billing entity object

lago_id
string
required

A unique identifier for the billing entity in the Lago application

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

code
string
required

The unique code of the billing entity

Example:

"acme_corp"

name
string
required

The name of the billing entity

Example:

"Acme Corp"

default_currency
enum<string>
required

The default currency of the billing entity

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,
GHS,
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
Example:

"USD"

document_locale
string
required

The language of the documents generated for this billing entity

Example:

"en"

document_numbering
enum<string>
required

The type of document numbering for this billing entity:

  • per_customer: document numbers are unique per customer
  • per_billing_entity: document numbers are unique per billing entity
Available options:
per_customer,
per_billing_entity
Example:

"per_customer"

finalize_zero_amount_invoice
boolean
required

Whether to finalize invoices with zero amount for this billing entity

Example:

true

invoice_grace_period
integer
required

The grace period (in days) for invoice finalization

Example:

0

net_payment_term
integer
required

The net payment term (in days) for this billing entity

Example:

0

timezone
enum<string>
required

The timezone of the billing entity

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
Example:

"America/Los_Angeles"

created_at
string
required

The date and time when the billing entity was created

Example:

"2022-04-29T08:59:51Z"

updated_at
string
required

The date and time when the billing entity was last updated

Example:

"2022-04-29T08:59:51Z"

document_number_prefix
string | null

The prefix used in document numbers for this billing entity

Example:

"ABC-123"

The footer text to be displayed on invoices for this billing entity

Example:

"Thank you for your business"

is_default
boolean

Whether this billing entity is the default billing entity for the organization. Default billing entity will be used as fallback in services if no billing entity is specified when billing_entity is not provided. Default billing entity is the billing entity that will be used to generate invoices if no billing entity is specified when invoice is created. is the oldest active billing entity and this flag cannot be changed

Example:

false

address_line1
string | null

The first line of the billing address

Example:

"5230 Penfield Ave"

address_line2
string | null

The second line of the billing address

Example:

"Suite 100"

city
string | null

The city of the billing address

Example:

"Woodland Hills"

state
string | null

The state of the billing address

Example:

"CA"

country
enum<string>

The country code of the billing address

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
Example:

"US"

zipcode
string | null

The zipcode of the billing address

Example:

"91364"

email
string | null

The email address of the billing entity

Example:

"billing@acme.com"

The legal name of the billing entity

Example:

"Acme Corporation"

The legal registration number of the billing entity

Example:

"US123456789"

tax_identification_number
string | null

The tax identification number of the billing entity

Example:

"EU123456789"

email_settings
enum<string>[]

The email notification settings for this billing entity

eu_tax_management
boolean

Whether EU tax management is enabled for this billing entity

Example:

false

logo_url
string | null

The URL of the billing entity's logo

Example:

"https://getlago.com/logo.png"