Getting started

The Merchable Account API lets you place orders from your own systems: read your designs (with the variant ids, unit prices and stock an order line needs), quote and place account orders, track fulfilment, and be notified by webhook. Account, shop and design data are read-only in v1 — content is managed in the web app or over MCP.

Base URL

https://api.merchable.co/v1

All requests and responses are JSON (application/json). Errors use application/problem+json (see Pagination, errors & rate limits).

1. Create an API key

In app.merchable.co go to Settings → Developer and create a key. Pick the scopes the integration needs (see Authentication & scopes). The key (mchp_…) is shown once — store it in your secrets manager.

2. Make a request

curl https://api.merchable.co/v1/account \
  -H "Authorization: Bearer mchp_your_key"

{
  "data": {
    "id": "6a1d…",
    "name": "Acme Climbing",
    "slug": "acme-climbing",
    "country": "AU",
    "currency": "AUD",
    "payment_method_on_file": true,
    "owner": { "email": "ops@acme.example", "name": "Sam Lee" }
  }
}

3. Find the designs you can order

curl "https://api.merchable.co/v1/designs?status=active" \
  -H "Authorization: Bearer mchp_your_key"

Each design lists its colours and sizes and two prices: retail_price, what it sells for in your shops, and purchase_price, what your account pays Merchable per unit. GET /v1/designs/{id} adds the variants array with everything an order line needs — the id you use as variant_id, the option names, the unit purchase price and the stock status — plus quantity tiers and any personalisation_zones (customer text such as a name on the back). The Designs guide walks through all of it.

Price delivery with POST /v1/shipping/estimate — see Placing an order.

4. Quote, then place an order

Quote first to see totals without committing:

curl -X POST https://api.merchable.co/v1/orders/quote \
  -H "Authorization: Bearer mchp_your_key" -H "Content-Type: application/json" \
  -d '{
    "items": [{ "design_id": "d8Xk2mQz", "colour": "Black", "size": "L", "quantity": 12 }],
    "delivery": { "type": "delivery", "shipping_method": "standard",
      "address": { "line1": "1 Example St", "city": "Melbourne", "state": "VIC",
                   "postcode": "3000", "country": "AU" } }
  }'

Then place it with an Idempotency-Key (see Placing an order):

curl -X POST https://api.merchable.co/v1/orders \
  -H "Authorization: Bearer mchp_your_key" -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-2026-0042" \
  -d '{ ...same body..., "external_reference": "PO-2026-0042" }'

5. Follow the order

Poll GET /v1/orders/{id} or, better, pass a webhook_url when placing the order — see Webhooks. Every status change (order.approved, order.shipped, order.delivered, …) is delivered to it with the full order, including tracking numbers.

Interactive reference

The full endpoint reference with request/response schemas is at /docs; the raw OpenAPI document is at /v1/openapi.json.