Developers

Connect your website

The TFM Manufacturing API lets your website show live stock status, send in orders, and read order status and tracking. It's a JSON REST API over HTTPS. Webhooks (Growth plan) tell your site when stock or orders change.

Overview

Authentication

Create an API key in Settings → API keys (owners and admins). Choose only the scopes the key needs. The key is shown once; we store only a hash of it, so keep it somewhere safe. Send it as a bearer token:

curl https://twelfthfretmfg.com/api/v1/ping \
  -H "Authorization: Bearer tfm_your_key_here"

Errors

Errors use standard HTTP status codes and always have the same shape:

{
  "error": {
    "code": "invalid_request",
    "message": "items must be a list of 1 to 500 lines.",
    "request_id": "req_6pV0..."
  }
}

Rate limits

Each key can make 120 requests a minute on Starter and 600 on Growth. Every response includes:

Tip: cache stock status for a minute or two, or use webhooks, rather than calling the API on every page view.

Pagination

List endpoints return { data, has_more, next_cursor }. Pass next_cursor back (as starting_after for products, created_before for orders) to get the next page. limit is 1–100, default 50.

Idempotency

Networks fail. To retry an order safely, send an Idempotency-Key header (any unique string, e.g. a UUID, up to 255 characters). Retrying with the same key and body returns the original response instead of creating a second order. Keys are kept for 24 hours. Orders with the same external_id are also never created twice.

Stock status

List products

GET/v1/products

Scope products:read. Active products and their variants, with price and stock status.

{
  "data": [{
    "id": "8f0c…", "name": "Koa Guitar Stand", "category": "Stands", "active": true,
    "track_inventory": true, "lead_time": "2-3 weeks",
    "variants": [{
      "id": "c1a2…", "sku": "KOA-WAL", "attributes": { "wood": "Walnut" },
      "price": 189.00, "available": 7, "stock_status": "in_stock", "lead_time": null
    }]
  }],
  "has_more": false,
  "next_cursor": null
}

Check inventory

GET/v1/inventory?sku=KOA-WAL,PANEL-2X4

Scope inventory:read. Stock status for up to 200 SKUs (case-insensitive) or variant_ids.

const res = await fetch('https://twelfthfretmfg.com/api/v1/inventory?sku=KOA-WAL', {
  headers: { Authorization: `Bearer ${process.env.TFM_API_KEY}` },
});
const { data } = await res.json();
const label = data[0].stock_status === 'in_stock' ? 'In stock'
  : data[0].stock_status === 'made_to_order' ? `Made to order: ${data[0].lead_time}`
  : 'Out of stock';

Create an order

POST/v1/orders

Scope orders:write. Send it when a customer checks out. Units on the shelf are reserved straight away; the rest goes onto the build list, and the order's status follows automatically. Returns 201 (or 200 with the existing order if this external_id was already sent).

curl -X POST https://twelfthfretmfg.com/api/v1/orders \
  -H "Authorization: Bearer $TFM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2e9a-website-order-10457" \
  -d '{
    "external_id": "10457",
    "customer": { "name": "Sam Rivera", "email": "sam@example.com" },
    "items": [ { "sku": "KOA-WAL", "quantity": 1 }, { "sku": "PANEL-2X4", "quantity": 2 } ],
    "shipping": 25, "tax": 31.40,
    "payment": { "amount": 434.40, "method": "Stripe", "reference": "pi_3Q…" }
  }'

Retrieve an order

GET/v1/orders/{id}

GET/v1/orders/by-external-id/{external_id}

Scope orders:read. Status, items (with ready, shipped and refunded counts) and shipments with carrier and tracking.

List orders

GET/v1/orders

Webhooks

Growth plan. Add an HTTPS endpoint in Settings → Webhooks and choose events. We POST JSON to it and retry with backoff for about a day if your endpoint doesn't answer with a 2xx within 10 seconds; an endpoint that fails 50 times in a row is switched off (you'll see it in the app).

POST https://your-site.com/webhooks/tfm
TFM-Event-Id: 1c9e…
TFM-Event-Type: order.shipped
TFM-Signature: t=1792300000,v1=5f2b…

{
  "id": "1c9e…",
  "type": "order.shipped",
  "created": 1792300000,
  "data": {
    "id": "a41f…", "order_number": 1043, "external_id": "10457", "status": "partially_shipped",
    "shipment": { "carrier": "UPS", "tracking_number": "1Z999…", "items": [ { "sku": "KOA-WAL", "quantity": 1 } ] }
  }
}

Events can arrive more than once or out of order: use id to skip duplicates and fetch the order if you need its latest state.

Verifying signatures

Every webhook is signed with your endpoint's secret (shown once when you create it). Check the signature on the raw request body before trusting it, and reject old timestamps to stop replays:

import crypto from 'node:crypto';

export function verifyTfmWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 || '', 'hex');
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

Questions or need another endpoint? Contact us.