v1

latestOpenAPI 3.0.32026-08-0623677345.2 KB

Billing

Create customer

post/customers/

Headers

x-simple-workspacestring required

Workspace (account) identifier. Required for every request.

x-piriod-test-modeboolean

Whether to operate against test-mode data. Defaults to false.

Request body

namestring required

addressstring required

countrystring required

Country ID (e.g. CL, MX, CO).

stateinteger required

State ID. Must belong to the chosen country.

currencystring

ISO currency code. Defaults from the country if omitted.

emailstring email nullable

phonestring nullable

websitestring uri nullable

zip_codestring nullable

managerstring nullable

referencestring nullable

tax_idstring nullable

tax_settingsobject

metadataobject

send_invoicesboolean

send_collectionsboolean

send_vouchersboolean

Response

Customer created.

idstring

namestring required

addressstring required

currencystring

ISO currency code (e.g. CLP, USD).

emailstring email nullable

phonestring nullable

websitestring uri nullable

zip_codestring nullable

managerstring nullable

Account manager name (free text).

referencestring nullable

External reference for the customer.

tax_idstring nullable

Tax identifier. Required when the customer's country has tax regulation (e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's country.

tax_settingsobject

Country-specific tax configuration. Schema and required keys depend on the tax agency of the customer's country.

metadataobject

Arbitrary key/value metadata. Filterable via ?metadata__key=value.

send_invoicesboolean

Whether to email invoices to the customer.

send_collectionsboolean

Whether to email collection reminders to the customer.

send_vouchersboolean

Whether to email payment receipts to the customer.

status'active' | 'archived' | 'pending'

sourcesstring[]

IDs of reusable payment sources currently chargeable or pending.

test_modeboolean

createdstring date-time

updatedstring date-time

Example response

{
  "id": "cus_01H8XYZ123ABC",
  "country": {
    "id": "CL",
    "name": "Chile",
    "code": "+56",
    "currencies": [
      "CLP"
    ]
  },
  "state": {
    "country": "CL"
  },
  "currency": "CLP",
  "contacts": [
    {
      "id": "con_01H8XYZ123ABC"
    }
  ]
}