Create a customer

POST /accounting/customers

Group: Accounting › Customers · Operation ID: createCustomer

Creates one customer under the given legal entity and returns only its id (a UUID) — the identifier every other customer route is keyed by. Read the created record back with GET accounting/customers/:id.

name, entityId are required; entityId names an existing legal entity and is not itself updatable afterwards — create a new customer under the right entity instead of moving one. customerType defaults to 'default' when omitted; the combination of (name, entityId, customerType) must be unique, and a collision fails the call with DUPLICATE_CUSTOMER, naming the existing customer's id.

customerType 'endCustomer' is not supported by this endpoint today: linking the required partner business record has no equivalent field anywhere in this API's read contract, so a request naming it fails with END_CUSTOMER_NOT_SUPPORTED rather than guessing at that shape.

addresses carries the customer's addresses, each naming its own type ('billTo', 'soldTo'); mark at most one entry per type with isDefault, and when a type has none marked its first entry becomes that type's default. externalIdentifiers accepts the customer's initial set, each fieldName matching an active CustomerExternalIdentifierConfiguration (call enumValues/list-style discovery, or POST accounting/customers/search's externalIdentifier filter, to see one already in use).

The call runs in a transaction: a failure writes nothing.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createCustomerInput.

Field Type Required Description
name string yes Customer display name, as it will appear on invoices and official documents.
entityId string yes Id of the legal entity that owns this customer (a UUID). Not updatable afterwards.
customerType string no Customer type. One of 'default', 'partner', 'endCustomer'. Defaults to 'default' when omitted. 'endCustomer' is not yet supported by this endpoint (see END_CUSTOMER_NOT_SUPPORTED).
partnerType string no Partner type, relevant when customerType is 'partner'. One of 'reseller', 'thirdPartyPayer'.
businessType string no Whether the customer is a registered company or an individual. One of 'company', 'individual'. Defaults to 'company' when omitted.
invoiceEmail string no Email address that receives invoices and billing statements.
mainEmail string no Primary business contact email for general correspondence.
taxExempt boolean no Whether the customer is exempt from tax on all transactions. Defaults to false when omitted.
defaultCurrency string no Default transaction currency as a 3-letter ISO 4217 code (e.g. USD, EUR, GBP). Defaults to the owning legal entity's own currency when omitted.
segment string no Market segment classification. One of 'SMB', 'MidMarket', 'Enterprise'. Ignored when businessType is 'individual'.
exemptionNumber string no Government-issued tax-exemption certificate number. Only storable when taxExempt is true; supplying one otherwise fails with EXEMPTION_NUMBER_REQUIRES_TAX_EXEMPT (taxExempt defaults to false).
paymentTermCode string no Payment-term code applied to this customer's invoices. Fails with UNKNOWN_REFERENCE when no such payment term exists.
parentId string no Customer UUID of this customer's parent in the business-partner hierarchy. Fails with UNKNOWN_REFERENCE when no such customer exists.
partnerId string no Customer UUID of the partner this customer buys through. Fails with UNKNOWN_REFERENCE when no such customer exists.
salesChannel string no Channel the customer was won through. A SalesChannel member.
additionalContactEmail string no Further contact addresses, beyond the invoice and main contacts.
mainContactName string no Name of the customer's main contact person.
preferredLanguage string no Language the customer prefers correspondence in. A PreferredLanguage member.
crmCustomerId string no The customer's identifier in the CRM system it was sourced from.
businessIdentificationNumber string no Government-issued business registration number.
invoiceConsolidation string no How invoices are consolidated for this customer. An InvoiceConsolidation member.
invoiceDeliveryMode string no How invoices reach the customer. An InvoiceDeliveryMode member.
isExemptFromCreditCardFee boolean no Whether the customer is exempt from credit-card surcharges.
billableTravelExpenseInvoiceDetail string no Whether billable travel and expense items appear itemised or consolidated. An InvoiceDetail member.
status string no Lifecycle status of the customer record. A CustomerStatus member.
taxExemptCode string no Code behind the tax exemption, as the authority categorises it. Only meaningful when taxExempt is true.
taxRegistrations array of object no Tax registrations to record for this customer. Upserted by (country, type): an entry matching an existing registration updates it, anything else is added; registrations left out are untouched.
taxRegistrations[].country string yes ISO 3166-1 country code the registration applies in.
taxRegistrations[].taxNumber string yes Official tax identification number issued by the tax authority.
taxRegistrations[].type string yes Kind of tax identification number. One of 'tax', 'salesTax', 'VAT', 'GST', 'EIN', 'TIN'.
taxRegistrations[].effectiveDate string (date) no Date the registration becomes valid for tax calculations (YYYY-MM-DD).
taxRegistrations[].isActive boolean no Whether the registration is used for tax calculations. Defaults to true.
payment object no Payment-provider link for this customer. externalPaymentMethodId requires an externalCustomerId, either in the same request or already stored.
payment.provider string no Payment provider name, e.g. 'Stripe'. Required when any other payment field is supplied.
payment.externalCustomerId string no The customer's identifier in the payment provider's system, e.g. a Stripe customer id.
payment.externalPaymentMethodId string no The customer's default payment-method identifier in the provider's system, e.g. a Stripe payment method id.
addresses array of object no The customer's addresses, each naming its own type. Mark at most one entry per type with isDefault; when a type has none marked, its first entry becomes that type's default.
addresses[].type string yes Which address this is. One of 'billTo', 'soldTo'.
addresses[].attention string no Person or department correspondence at this address is directed to.
addresses[].isDefault boolean no Marks this entry as its type's default. At most one per type; when a type has none marked, its first entry becomes the default.
addresses[].line1 string yes Street address line 1: number, street name, or PO box.
addresses[].line2 string no Apartment, suite, unit, building, floor, etc.
addresses[].city string yes City or locality.
addresses[].stateProvince string no State, province, or region.
addresses[].country string yes Country, as a name or ISO 3166-1 code.
addresses[].zipCode string yes Postal or ZIP code.
externalIdentifiers array of object no External identifiers owned by other systems. At most one entry per fieldName; each fieldName must match an active CustomerExternalIdentifierConfiguration or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER.
externalIdentifiers[].fieldName string yes Configured key of the external identifier, e.g. 'netsuiteSoNumber'.
externalIdentifiers[].value string yes The identifier as the source system holds it.
externalIdentifiers[].externalUrl string no Absolute http(s) link to the object in the originating system.

Example:

{
  "name": "Example Robotics Inc",
  "entityId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
  "customerType": "default",
  "partnerType": "<partnerType>",
  "businessType": "company",
  "invoiceEmail": "billing@example-robotics.com",
  "mainEmail": "<mainEmail>",
  "taxExempt": true,
  "defaultCurrency": "USD",
  "segment": "<segment>",
  "exemptionNumber": "<exemptionNumber>",
  "paymentTermCode": "<paymentTermCode>",
  "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "salesChannel": "<salesChannel>",
  "additionalContactEmail": "<additionalContactEmail>",
  "mainContactName": "<mainContactName>",
  "preferredLanguage": "<preferredLanguage>",
  "crmCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessIdentificationNumber": "<businessIdentificationNumber>",
  "invoiceConsolidation": "<invoiceConsolidation>",
  "invoiceDeliveryMode": "<invoiceDeliveryMode>",
  "isExemptFromCreditCardFee": true,
  "billableTravelExpenseInvoiceDetail": "<billableTravelExpenseInvoiceDetail>",
  "status": "<status>",
  "taxExemptCode": "<taxExemptCode>",
  "taxRegistrations": [
    {
      "country": "<country>",
      "taxNumber": "<taxNumber>",
      "type": "<type>",
      "effectiveDate": "2026-01-15",
      "isActive": true
    }
  ],
  "payment": {
    "provider": "<provider>",
    "externalCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalPaymentMethodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "addresses": [
    {
      "type": "billTo",
      "line1": "500 Market St",
      "city": "San Francisco",
      "stateProvince": "CA",
      "country": "US",
      "zipCode": "94105",
      "isDefault": true
    }
  ],
  "externalIdentifiers": [
    {
      "fieldName": "<fieldName>",
      "value": "<value>",
      "externalUrl": "<externalUrl>"
    }
  ]
}

Response

200 Success

Under data (createCustomerOutput):

Field Type Required Description
id string yes Platform id (a UUID) assigned to the newly created customer. Read the full record with GET accounting/customers/:id.

Response headers

Errors

Code Status
INVALID_ENTITY 400
INVALID_FIELD_VALUE 400
MULTIPLE_DEFAULT_ADDRESSES 400
DUPLICATE_CUSTOMER 400
END_CUSTOMER_NOT_SUPPORTED 400
UNKNOWN_EXTERNAL_IDENTIFIER 400
DUPLICATE_EXTERNAL_IDENTIFIER 400
UNKNOWN_REFERENCE 400
UNKNOWN_PAYMENT_PROVIDER 400
PAYMENT_METHOD_REQUIRES_CUSTOMER_ID 400
EXEMPTION_NUMBER_REQUIRES_TAX_EXEMPT 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses