Skip to content
Docs menu

Get started

REST API

MCP

Guides

Reference

Get started

Quickstart

Make an API key and make your first TradeCatalog API calls in five minutes.

View as MarkdownOpen in ClaudeOpen in ChatGPT

You need to be the owner of a TradeCatalog workspace with an active subscription, a free trial or a pilot account. Demo workspaces can’t use the API.

1. Make an API keyLink to this section#

  1. Open your workspace and go to Settings → API.
  2. Give the key a name you’ll recognise later, like “Sage stock sync”.
  3. Choose Read only to look things up, or Read & write to also update products, customers and orders.
  4. Choose Create key and copy it. It starts with tc_live_.

Copy it now

We only show a key once, and we only keep a hash of it. If you lose it, revoke it and make a new one.

Put the key in an environment variable so it stays out of your code:

bash
export TRADECATALOG_API_KEY="tc_live_…"

2. Check the key worksLink to this section#

bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
json
{
  "data": {
    "id": "0b6c1f5e-6f7a-4a57-9a0c-2f4d4c1e8a11",
    "slug": "northgate",
    "name": "Northgate Fixings",
    "currency": "GBP",
    "timezone": "Europe/London",
    "taxLabel": "ex VAT",
    "key": { "name": "Sage stock sync", "scope": "write" }
  }
}

3. Search productsLink to this section#

bash
curl "https://tradecatalog.app/api/v1/products?q=hinge&limit=2" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

Money is always in minor units of the workspace currency, so 1850 is £18.50. See Conventions.

4. Get a customer’s priceLink to this section#

Pass a customer’s account code (or id) and a SKU:

bash
curl "https://tradecatalog.app/api/v1/prices?customer=OAK01&sku=HX-8510&qty=10" \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
json
{
  "data": {
    "customer": {
      "id": "7d2e4f0a-1b3c-4d5e-8f90-a1b2c3d4e5f6",
      "accountCode": "OAK01",
      "name": "Oakfield Joinery"
    },
    "sku": "HX-8510",
    "name": "Hex bolt M10 x 50 zinc",
    "qty": 10,
    "unit": 1573,
    "line": 15730,
    "list": 1850,
    "discountBp": 1500,
    "source": "brand",
    "label": "Brand discount −15%"
  },
  "currency": "GBP"
}

How prices are worked out explains source and label.

5. Create or update a productLink to this section#

This needs a Read & write key.

bash
curl -X PUT https://tradecatalog.app/api/v1/products \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "sku": "HX-8512",
        "name": "Hex bolt M12 x 50 zinc",
        "listPrice": 2240,
        "unitLabel": "Box of 100",
        "brand": "Northgate",
        "category": "Bolts"
      }
    ]
  }'
json
{
  "data": {
    "created": 1,
    "updated": 0,
    "priceChanges": 0,
    "priceChangeId": null,
    "unknownCustomers": []
  }
}

New products go live at their list price straight away. If you send a different price for a product that already has one, the price doesn’t change yet. It goes into a draft price change that you review and publish in the app. See Products.

The same in JavaScriptLink to this section#

js
const api = (path, init = {}) =>
  fetch(`https://tradecatalog.app/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  }).then(async (res) => {
    const body = await res.json()
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
    return body
  })

const { data: workspace } = await api('/workspace')
const { data: price } = await api('/prices?customer=OAK01&sku=HX-8510&qty=10')
console.log(`${workspace.name}: ${price.name} is ${price.unit / 100} each`)

Next stepsLink to this section#