Customers · TradeCatalog docs

A customer is a trade account: a business you sell to, with an account code, an optional account discount, and the people (buyers) who can sign in to order for it.

The customer objectLink to this section#

json

{
  "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
  "accountCode": "OAK01",
  "name": "Oakfield Joinery",
  "legalName": "Oakfield Joinery Ltd",
  "email": "accounts@oakfieldjoinery.co.uk",
  "discountBp": 500,
  "active": true,
  "newsOptOut": false,
  "catalogueScope": "all",
  "createdAt": "2026-07-02T10:12:44.000Z"
}

Field	Type	Description
`id`	string	Customer id.
`accountCode`	string	Your account code. Unique in the workspace, ignoring capitals. It can be changed in the app, so keep the `id` for anything long-lived.
`name`	string	Trading name.
`legalName`	string or null	Registered name, when different.
`email`	string or null	Main contact email, lowercased.
`discountBp`	integer or null	The customer’s own percentage on the whole list, in basis points. `null` for none.
`adjustment`	string	`discount` (taken off the list) or `markup` (added on). Existing customers are `discount`.
`active`	boolean	Inactive customers can’t sign in or order.
`newsOptOut`	boolean	The customer turned off offers and news emails. Price-change emails still go.
`catalogueScope`	string	`all` (sees the whole catalogue) or `approved` (sees and orders only its approved list). Set on the customer page; read-only in the API.
`createdAt`	string	When the customer was added.

Anywhere the API takes a customer, you can use the id or the accountCode.

List customersLink to this section#

GET/api/v1/customers

Every customer, sorted by name.

Name	Type	Required	Description
`limit`	integer	no	1 to 100. Default 100.
`offset`	integer	no	Rows to skip. Default 0.

bash

curl "https://tradecatalog.app/api/v1/customers?limit=100" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/customers?limit=100', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: customers, nextOffset } = await res.json()

json

{
  "data": [
    {
      "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
      "accountCode": "OAK01",
      "name": "Oakfield Joinery",
      "legalName": "Oakfield Joinery Ltd",
      "email": "accounts@oakfieldjoinery.co.uk",
      "discountBp": 500,
      "active": true,
      "newsOptOut": false,
      "catalogueScope": "all",
      "createdAt": "2026-07-02T10:12:44.000Z"
    }
  ],
  "nextOffset": null
}

Get one customerLink to this section#

GET/api/v1/customers/{id}

The customer plus everything that affects their prices, and who can sign in for them.

Name	In	Type	Required	Description
`id`	path	string	yes	Customer id or account code.

bash

curl https://tradecatalog.app/api/v1/customers/OAK01 \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

const res = await fetch('https://tradecatalog.app/api/v1/customers/OAK01', {
  headers: { Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}` },
})
const { data: customer } = await res.json()

json

{
  "data": {
    "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
    "accountCode": "OAK01",
    "name": "Oakfield Joinery",
    "legalName": "Oakfield Joinery Ltd",
    "email": "accounts@oakfieldjoinery.co.uk",
    "discountBp": 500,
    "priceListId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "priceList": "Standard",
    "active": true,
    "newsOptOut": false,
    "createdAt": "2026-07-02T10:12:44.000Z",
    "discountRules": [
      {
        "id": "d0e1f2a3-4b5c-4d6e-9f7a-8b9c0d1e2f3a",
        "scope": "product",
        "discountBp": 2000,
        "productId": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
        "sku": "HX-8510",
        "target": "Hex bolt M10 x 50 zinc",
        "list": 2280,
        "unit": 1824
      },
      {
        "id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
        "scope": "brand",
        "discountBp": 1500,
        "productId": null,
        "sku": null,
        "target": "Northgate",
        "list": null,
        "unit": null
      },
      {
        "id": "f2a3b4c5-6d7e-4f80-9a1b-2c3d4e5f6a7b",
        "scope": "category",
        "discountBp": 1250,
        "productId": null,
        "sku": null,
        "target": "Hinges",
        "list": null,
        "unit": null
      }
    ],
    "agreedPrices": [
      {
        "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "productId": "6c7d8e9f-0a1b-4c2d-9e3f-4a5b6c7d8e9f",
        "price": 1450,
        "note": "Contract price to March 2027",
        "noteVisible": true,
        "internalNote": "Agreed with their buyer",
        "sku": "HX-8512",
        "name": "Hex bolt M12 x 50 zinc",
        "list": 1980,
        "unit": 1450
      }
    ],
    "buyers": [{ "name": "Sam Patel", "email": "sam@oakfieldjoinery.co.uk" }],
    "pendingInvitations": [{ "email": "orders@oakfieldjoinery.co.uk" }]
  },
  "currency": "GBP"
}

Field	Description
`priceList`	Name of the price list this customer buys from. `priceListId` is that list’s id. A product with no price on the list is price on request.
`discountRules`	Product, category and brand percentages. `scope` is `product`, `category` or `brand`; `adjustment` is `discount` or `markup`; `target` is its name. Product rules also give `sku`, `list` and `unit` (what they pay).
`agreedPrices`	Agreed (fixed) prices valid now, per SKU, in minor units, with the current `list` price and the `unit` price they pay. `note` is the remark; `noteVisible` says whether that customer sees it. `internalNote` is staff-only and is never shown to the customer.
`buyers`	People who can sign in and order for this customer.
`pendingInvitations`	Invitations sent but not yet accepted, and not expired.

See how prices are worked out for how these combine.

Create or update customersLink to this section#

PUT/api/v1/customerswrite key

Send up to 100 customers per call. Each row is matched to an existing customer like this:

If accountCode is set, by account code. No match means a new customer with that code.
Otherwise, if email is set, by email. No match means a new customer.
Otherwise by name, ignoring case.

New customers without an account code get one made from their name.

BodyLink to this section#

Field	Type	Required	Description
`customers`	array	yes	1 to 100 customers. Account codes must be unique within the call.
`customers[].accountCode`	string or null	yes	Up to 50 characters. `null` to match by email or name.
`customers[].name`	string	yes	Trading name, up to 160 characters.
`customers[].email`	string or null	yes	Main contact email. `null` clears it.
`customers[].discountBp`	integer or null	yes	Whole-list percentage, 0 to 10,000, for a discount or a markup. `null` clears it.
`customers[].adjustment`	`discount` or `markup`	no	Which way `discountBp` moves the price. Omit it to leave the current direction. New customers default to `discount`.
`customers[].priceList`	string or null	no	Name of an existing price list. Omit it to leave the list unchanged. `null` puts the customer on Standard. An unknown name is rejected.
`customers[].region`	string or null	no	Name of an existing region. Omit it to leave the region unchanged. `null` clears it. An unknown name is rejected.
`customers[].rep`	string or null	no	Email or username of a staff member assigned to this customer. Omit it to leave the rep unchanged. `null` clears it. An unknown email or username is rejected.

accountCode, name, email and discountBp are required, and written as sent: null clears email and discountBp. That way a missing field in your code can’t silently leave an old percentage in place. adjustment and priceList are optional: leave adjustment out to keep a markup or a discount as it is.

The customer spreadsheet has the same choice. Beside Discount % it can have an Adjustment column (discount or markup), a Price list column and a Sales rep column. The rep cell is that person’s email, or their username when they sign in without email. A blank cell leaves that field as it is. An unknown list name or rep is an error on that row.

Updating a customer doesn’t email anyone or invite buyers. Invite buyers from the customer’s page in the app. Registered name, active status, discount rules and agreed prices are changed in the app too.

bash

curl -X PUT https://tradecatalog.app/api/v1/customers \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "accountCode": "OAK01",
        "name": "Oakfield Joinery",
        "email": "accounts@oakfieldjoinery.co.uk",
        "discountBp": 500
      },
      {
        "accountCode": "BRK07",
        "name": "Brookside Builders",
        "email": null,
        "discountBp": null
      }
    ]
  }'

const res = await fetch('https://tradecatalog.app/api/v1/customers', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ customers }),
})
const { data } = await res.json()
console.log(`${data.created} new, ${data.updated} updated`)

json

{
  "data": { "created": 1, "updated": 1 }
}

The change appears in the activity log as the key’s name.