Customer

/api/integration/customer — domain: Customer

Who the customer is, where they ship, what they may buy, and what they owe.

PUT / — customers

Purpose. Upsert a trading account with its ship-to addresses, and optionally nominate an administrator to be provisioned as a portal user.

Domain. Customer, which owns accounts, addresses and the ledger. The optional admin crosses into Authentication — see the note at the end.

Request

IntegrationEnvelope<CustomerEnvelopeDto>.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "account": {
        "accountNo": "C00123",
        "name": "Acme Workwear Pty Ltd",
        "status": "Active",
        "paymentTermsCode": "NET30",
        "billToAddress1": "1 Example Street",
        "billToAddress2": "Level 4",
        "billToPostCode": "3000",
        "billToCity": "Melbourne",
        "billToState": "VIC",
        "billToCountryRegionCode": "AU",
        "billToCountryRegionName": "Australia",
        "phoneNo": "+61 3 0000 0000",
        "email": "ap@acme.example",
        "defaultShipToCode": "MAIN",
        "primaryContactNo": "CT-001",
        "creditLimit": 50000,
        "creditBalance": 12750.40,
        "priceMode": "PriceList",
        "priceGroup": "TRADE",
        "discGroup": "STD",
        "allowedBrands": "ACME,BETA",
        "indentBrands": "GAMMA",
        "taxLiable": true,
        "taxAreaCode": "AU-VIC",
        "gstBusinessPostingGroup": "DOM"
      },
      "shipToAddresses": [
        {
          "shipToCode": "MAIN",
          "shipToName": "Acme Warehouse",
          "shipToAddress1": "9 Depot Road",
          "shipToAddress2": "Gate 2",
          "shipToPostCode": "3020",
          "shipToCity": "Sunshine",
          "shipToState": "VIC",
          "shipToCountryRegionCode": "AU",
          "taxLiable": true,
          "taxAreaCode": "AU-VIC",
          "isFirstNations": false
        }
      ],
      "admin": {
        "name": "Jane Smith",
        "email": "jane@acme.example"
      }
    }
  ]
}

account

Field	Type	Required	Description
accountNo	string	Yes	The natural key. Every order, price and ledger entry hangs off it
name	string	Yes	Registered or trading name, shown to the user
status	string	Yes	Account standing. A non-active account cannot transact
paymentTermsCode	enum		Payment terms code, for example net 30
billToAddress1	string		Invoice address, first line
billToAddress2	string		Invoice address, second line
billToPostCode	string		Invoice postcode
billToCity	string		Invoice city
billToState	string		Invoice state or region
billToCountryRegionCode	string		Invoice country code
billToCountryRegionName	string		Invoice country name, for display
phoneNo	string		Account contact telephone
email	string		Account contact address, typically accounts payable
defaultShipToCode	string		Which ship-to is preselected at checkout. Must match a shipToCode in the same item
primaryContactNo	string		Upstream reference for the main contact
creditLimit	decimal		Credit ceiling, displayed to the user. Commerce never calculates it
creditBalance	decimal		Current balance, displayed to the user. Commerce never calculates it
priceMode	string		How this account is priced — which pricing strategy applies
priceGroup	string		Price group code. Pricing rules target this
discGroup	string		Discount group code, used by pricing rules
allowedBrands	string		Comma-separated brand codes the account may buy. Blank means every brand
indentBrands	string		Comma-separated brand codes available on indent, added to the allowed set
taxLiable	bool		Whether the account is taxed at all
taxAreaCode	string		Join key into a Tax area, which resolves the rate
gstBusinessPostingGroup	string		Join key into Tax GST posting rates

Important

allowedBrands is entitlement, and blank is permissive, not restrictive — an empty value grants every global brand. It is enforced inside the search query, so getting it wrong silently changes what a customer can see and buy rather than producing an error.

shipToAddresses[]

Field	Type	Required	Description
shipToCode	string	Yes	The natural key within the account. Identifies a delivery destination
shipToName	string		Destination name, shown at checkout
shipToAddress1	string		Delivery address, first line
shipToAddress2	string		Delivery address, second line
shipToPostCode	string		Drives freight — matched against Fulfilment postcode routing
shipToCity	string		Delivery city
shipToState	string		Delivery state or region
shipToCountryRegionCode	string		Delivery country code. Selects which country's freight rules apply
taxLiable	bool		Overrides the account's liability for deliveries to this destination
taxAreaCode	string		Overrides the account's tax area for this destination
isFirstNations	bool		Flags a First Nations destination, where different tax treatment may apply

Ship-to addresses are a snapshot. Send the complete set every time — an address stored against the account but absent from the payload is removed.

admin

Field	Type	Required	Description
name	string	Yes, when admin is present	Display name of the person to provision
email	string	Yes, when admin is present	Their sign-in address, and where the invitation is sent

Optional. When present, Commerce raises a provisioning request that creates or links a portal user for this account and sends them an invitation. Omit it and nothing happens.

Note

This replaced an earlier contacts[] array that drove user provisioning. That array no longer exists. If your integration still sends it, the field is ignored and no user is provisioned.

Response

One entry per account, keyed by accountNo, with nested results for the addresses.

{
  "data": [
    {
      "key": "C00123",
      "outcome": "Upserted",
      "type": "Account",
      "children": [
        { "key": "MAIN", "outcome": "Upserted" }
      ]
    }
  ]
}

---

PUT /ledger — ledger entries

Purpose. Push invoices, credits and payments so a customer can see what they owe.

Domain. Customer.

Request

IntegrationEnvelope<LedgerEntryUpsertDto>.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "entryNo": 884213,
      "accountNo": "C00123",
      "documentNo": "INV-00042",
      "externalDocumentNo": "PO-9981",
      "documentType": "Invoice",
      "originType": "Sales",
      "documentDate": "2026-08-01",
      "dueDate": "2026-08-31",
      "postingDate": "2026-08-01",
      "amount": 1320.00,
      "remainingAmount": 1320.00,
      "currencyCode": "AUD",
      "relatedOrderNo": "ORD-0000123",
      "isOpen": true,
      "creditBalance": 12750.40
    }
  ]
}

Field	Type	Required	Description
entryNo	long	Yes	The natural key — the upstream ledger entry number
accountNo	string	Yes	Which customer the entry belongs to
documentNo	string	Yes	The document reference, shown to the user
externalDocumentNo	string		The customer's own reference, typically their purchase order number
documentType	string	Yes	What kind of document this is, sent as a case-sensitive enum literal
originType	string	Yes	Where the entry originated, sent as a case-sensitive enum literal
documentDate	date	Yes	Date of the document. Date only, no time component
dueDate	date		When payment falls due. Drives any overdue presentation
postingDate	date	Yes	When the entry was posted upstream
amount	decimal		The original document value
remainingAmount	decimal		Still outstanding. This is what "what you owe" is built from
currencyCode	string		ISO 4217 code the amounts are expressed in
relatedOrderNo	string		Links an invoice back to an order placed in Commerce
isOpen	bool		Whether the entry is still outstanding or has been settled
creditBalance	decimal		The account balance as at this entry

Response

One entry per ledger row, keyed by entryNo.

{
  "data": [
    { "key": "884213", "outcome": "Upserted" }
  ]
}