Klanten · TradeCatalog documentatie

Een klant is een handelsrekening: een bedrijf waar je naar verkoopt, met een accountcode, een optionele accountkorting en de personen (kopers) die kunnen inloggen om voor het bedrijf te bestellen.

Het klantobjectLink naar deze sectie#

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"
}

Veld	Type	Beschrijving
`id`	string	Klant-ID.
`accountCode`	string	Je accountcode. Uniek in de workspace, onafhankelijk van hoofdletters. Het kan worden gewijzigd in de app, dus houd het `id` voor iets dat langdurig is.
`name`	string	Handelsnaam.
`legalName`	string of null	Geregistreerde naam, wanneer anders.
`email`	string of null	Hoofdcontact e-mail, in kleine letters.
`discountBp`	integer of null	De korting van de klant op de hele lijst, in basispunten. `null` voor geen korting.
`adjustment`	string	`discount` (afgenomen van de lijst) of `markup` (toegevoegd). Bestaande klanten zijn `discount`.
`active`	boolean	Inactieve klanten kunnen niet inloggen of bestellen.
`newsOptOut`	boolean	De klant heeft de offertes en nieuwsbrieven uitgeschakeld. Prijsveranderingsemails worden nog steeds verstuurd.
`catalogueScope`	string	`all` (ziet de hele catalogus) of `approved` (ziet en bestelt alleen zijn goedgekeurde lijst). Instelbaar op de klantpagina; alleen-lezen in de API.
`createdAt`	string	Wanneer de klant is toegevoegd.

Overal waar de API een klant nodig heeft, kun je het id of het accountCode gebruiken.

KlantenlijstLink naar deze sectie#

GET/api/v1/customers

Elke klant, gesorteerd op naam.

Naam	Type	Verplicht	Beschrijving
`limit`	integer	nee	1 tot 100. Standaard 100.
`offset`	integer	nee	Aantal rijen om over te slaan. Standaard 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
}

Een klant ophalenLink naar deze sectie#

GET/api/v1/customers/{id}

De klant plus alles wat hun prijzen beïnvloedt, en wie er voor hen in kan loggen.

Naam	In	Type	Verplicht	Beschrijving
`id`	pad	string	ja	Klant-ID of accountcode.

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"
}

Veld	Beschrijving
`priceList`	Naam van de prijslijst waar deze klant van koopt. `priceListId` is het ID van die lijst. Een product zonder prijs op de lijst is op verzoek.
`discountRules`	Product-, categorie- en merkpercentages. `scope` is `product`, `category` of `brand`; `adjustment` is `discount` of `markup`; `target` is zijn naam. Productregels geven ook `sku`, `list` en `unit` (wat ze betalen).
`agreedPrices`	Overeengekomen (vaste) prijzen geldig nu, per SKU, in mindere eenheden, met de huidige `list` prijs en de `unit` prijs die ze betalen. `note` is de opmerking; `noteVisible` zegt of die klant het ziet. `internalNote` is personeelsgebruik en wordt nooit aan de klant getoond.
`buyers`	Personen die kunnen inloggen en bestellen voor deze klant.
`pendingInvitations`	Aanbiedingen die zijn verstuurd maar nog niet zijn geaccepteerd, en niet verlopen.

Zie hoe prijzen worden berekend voor hoe deze combineren.

Klanten aanmaken of bijwerkenLink naar deze sectie#

PUT/api/v1/customersschrijf sleutel

Stuur maximaal 100 klanten per oproep. Elke rij wordt gekoppeld aan een bestaande klant op deze manier:

Als accountCode is ingesteld, op accountcode. Geen overeenkomst betekent een nieuwe klant met die code.
Anders, als email is ingesteld, op e-mail. Geen overeenkomst betekent een nieuwe klant.
Anders op naam, ongeacht hoofdletters.

Nieuwe klanten zonder accountcode krijgen er een gemaakt van hun naam.

LichaamLink naar deze sectie#

Veld	Type	Verplicht	Beschrijving
`customers`	array	ja	1 tot 100 klanten. Accountcodes moeten uniek zijn binnen de oproep.
`customers[].accountCode`	string of null	ja	Maximaal 50 tekens. `null` om te matchen op e-mail of naam.
`customers[].name`	string	ja	Handelsnaam, maximaal 160 tekens.
`customers[].email`	string of null	ja	Hoofdcontact e-mail. `null` verwijderd het.
`customers[].discountBp`	integer of null	ja	Gehele lijst percentage, 0 tot 10.000, voor een korting of een mark-up. `null` verwijderd het.
`customers[].adjustment`	`discount` of `markup`	niet verplicht	Welke kant `discountBp` beweegt de prijs. Laat het weg om de huidige richting te behouden. Nieuwe klanten standaard `discount`.
`customers[].priceList`	string of null	niet verplicht	Naam van een bestaande prijslijst. Laat het weg om de lijst onveranderd te laten. `null` zet de klant op Standard. Een onbekende naam wordt afgewezen.
`customers[].region`	string of null	niet verplicht	Naam van een bestaande regio. Laat het weg om de regio onveranderd te laten. `null` verwijderd het. Een onbekende naam wordt afgewezen.
`customers[].rep`	string of null	niet verplicht	E-mail of gebruikersnaam van een medewerker die aan deze klant is toegewezen. Laat het weg om de verkoopafdeling onveranderd te laten. `null` verwijderd het. Een onbekende e-mail of gebruikersnaam wordt afgewezen.

accountCode, name, email en discountBp zijn verplicht en worden zoals verstuurd: null verwijderd email en discountBp. Zo kan een ontbrekend veld in je code niet ongemerkt een oude percentage laten staan. adjustment en priceList zijn optioneel: laat adjustment weg om een mark-up of korting zoals het is te houden.

Het klantenspreadsheet heeft dezelfde keuze. Naast Korting % kan het een Aanpassing kolom hebben (discount of markup), een Prijslijst kolom en een Verkoopafdeling kolom. De verkoopafdeling cel is het e-mailadres van die persoon, of hun gebruikersnaam wanneer ze zich aanmelden zonder e-mail. Een lege cel laat dat veld zoals het is. Een onbekende lijstnaam of verkoopafdeling is een fout op die rij.

Het bijwerken van een klant e-mailt niemand of nodigt kopers niet uit. Nodig kopers uit vanaf de klantpagina in de app. Geregistreerde naam, actieve status, kortingregels en overeengekomen prijzen worden ook in de app gewijzigd.

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 }
}

De wijziging verschijnt in de activiteitenlog als de naam van de sleutel.