8Merch Fulfillment API (1.0.0)

1. Get a key. Keys are issued by 8Merch - email us and we will create one with the scopes you need. You receive it once; store it on your server (never in a browser or app). Every request sends it:

curl https://api.8merch.com/v1/warehouses \
  -H "Authorization: Bearer $EIGHTMERCH_API_KEY"

A partner key (one key, many artist accounts) also says which account each request is for: add -H "8Merch-Account: acc_..." (list yours with GET /v1/accounts).

2. Create your products, keyed by your SKU. Sending a SKU again updates it, so a catalogue sync can simply send everything:

curl -X POST https://api.8merch.com/v1/products \
  -H "Authorization: Bearer $EIGHTMERCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"sku":"KM-TEE-BLK-L","title":"Killer Moon T-shirt","variant_title":"Black / L","artist":"96BB",
       "hs_code":"6109.10","country_of_origin":"PT","customs_description":"Cotton T-shirt, printed"}'

3. Send us stock and tell us it is coming (POST /v1/inbound-shipments). We count it in on arrival; GET /v1/stock shows it as incoming, then on_hand.

4. Send each paid order with an Idempotency-Key, so a retry can never create it twice:

curl -X POST https://api.8merch.com/v1/orders \
  -H "Authorization: Bearer $EIGHTMERCH_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10045" \
  -d '{"external_id":"10045","order_number":"#10045",
       "shipping_address":{"name":"Ann Lee","line1":"1 Main St","city":"Austin","region":"TX",
                           "postal_code":"78701","country_code":"US"},
       "items":[{"sku":"KM-TEE-BLK-L","quantity":1,"unit_price":25}]}'

5. Register a webhook (POST /v1/webhook-endpoints) to hear order.shipped with the tracking number, and the rest of the lifecycle - or poll GET /v1/orders?updated_since=....

Pick whichever fits how you work with your artists. Both use the same endpoints.

A. One account, artists as stores. You are a single 8Merch account. Each artist is a store inside it (POST /v1/stores), and products and orders name their store. 8Merch bills you, monthly, for everything; you settle with your artists. Use an account key.

B. Platform partner, one account per artist. Each artist has their own 8Merch account, with their own billing, payment method and monthly statement, and your partner key can act for all of them. Send 8Merch-Account: <account id> on every request to say which artist it is for; GET /v1/accounts lists the accounts linked to your key. New artists are invited with POST /v1/accounts and finish their own billing set-up from the link we return.

You can mix them: a partner key can act for an account that itself has several stores.

Fulfillment costs are billed monthly to the account an order belongs to, on its statement.

Test the whole integration - products, stock, orders, webhooks - without anything shipping or being billed. Ask us for a sandbox account and a test key (8m_test_...). Same URL, same endpoints, same validation; the differences:

• A test key acts only for sandbox accounts, and a live key never does (403 livemode_mismatch). With a partner test key, POST /v1/accounts creates sandbox accounts (no invitation email is sent) and GET /v1/accounts lists only those.
• Nothing reaches a warehouse and nothing is billed. Instead a simulator, running every 5 minutes, plays the warehouse:
  • an order moves accepted -> in_warehouse -> shipped, at least 2 minutes per step, so allow 5-15 minutes; it ships with tracking SANDBOX-<number> and its stock is deducted;
  • an inbound shipment is received in full 2+ minutes after you announce it;
  • an order with "metadata": {"sandbox": "hold"} goes on_hold, to test that path;
  • pre-order products hold their orders, exactly as live.
• Webhook endpoints registered with a test key receive only sandbox events; live endpoints never do.

When you go live, the same code works with a live key against your real account.

• JSON in, JSON out. Send Content-Type: application/json. Dates are ISO 8601, in UTC.
• Ids are typed: acc_ account, st_ store, wh_ warehouse, ord_ order, ib_ inbound shipment, we_ webhook endpoint, evt_ event. Products are addressed by your SKU, orders also by ext:<your external_id>.
• Lists are paginated: limit (1-100, default 50); follow next_cursor while has_more is true.
• Retries are safe on POST /v1/orders and POST /v1/inbound-shipments with an Idempotency-Key: the same key returns the original object with 200 and Idempotent-Replayed: true instead of creating another (201). POST /v1/products is an upsert and safe to repeat anyway.
• Rate limit: 120 requests a minute per key. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit you get 429 with Retry-After.
• Request-Id: every response has one - quote it when you contact us.
• Fields we do not know are ignored, so you can send your own records without stripping them.

Every error has the same shape:

{ "error": { "type": "invalid_request", "code": "unknown_sku",
             "message": "No product with SKU KM-TEE-BLK-L ...", "param": "items[0].sku",
             "request_id": "req_..." } }

Branch on type and code; message is for people and may change.

Orders

Inbound shipments: announced (on its way) -> received (counted in; received_items has what arrived) or cancelled.

Accounts: pending (new, finishing billing set-up), active (taking orders), on_hold (orders refused - hold_reasons says which warehouse and why), inactive (closed).

Each delivery has 8Merch-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" with your endpoint secret. Verify it against the raw body, before parsing:

// Node 18+
const crypto = require("node:crypto");
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"));
}

# Python 3
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Then respond 2xx within 10 seconds and do the work afterwards. Use the event id to ignore repeats.

Do products have to exist before orders? Yes. An order with an unknown SKU is refused whole (422 unknown_sku) so nothing ships half-complete.

What happens if something is out of stock? The order is accepted and waits in accepted; it is never refused for stock. When open orders need more than we hold, the product is short: stock.shortfall_opened is sent, the account is emailed and sees it on its dashboard. GET /v1/stock?shortfall_only=true lists them.

How do pre-orders work? Mark the product preorder.is_preorder: true. Orders containing it are held (status accepted, counted as preordered, not short) until the account releases them in the 8Merch portal when the stock is ready.

How do I change the items on an order? Cancel it and send a new one. external_id stays unique even after a cancel, so give the new order a new id (e.g. 10045-2).

How do I get tracking? order.shipped carries shipment.carrier, service and tracking_number; GET /v1/orders/{id} shows the same.

What does shipping cost? It is billed on the account's monthly statement (postage by measured weight and destination, plus the per-order and per-item fees agreed with us), visible in the 8Merch portal. Orders do not carry a cost in the API.

Which warehouse ships an order? The one you name, or the store's, or the account's only one. GET /v1/warehouses lists those the account can use; each has one currency.

Do I need customs data? For parcels crossing a customs border (e.g. UK to EU, anywhere to the US): hs_code, country_of_origin and customs_description on the product, and unit_price on order lines.

My server was down - did I miss webhooks? Deliveries are retried for about 3 days. To catch up regardless, list GET /v1/orders?updated_since=<last time you synced>.

How do I test before going live? Use a sandbox account and a test key (see Sandbox): the real API, with a simulated warehouse. To build request code before you have a key, run a local mock from this spec: npx @stoplight/prism-cli mock https://api.8merch.com/docs/fulfillment/openapi.yaml.

Can the rate limit be raised? Yes - tell us what you need.

Platform partners only - the artist accounts your partner key can act for.

Storefronts inside one account - e.g. one per artist.

Where your orders ship from. One warehouse, one currency.

The items we hold and ship for you, keyed by your SKU.

What is in each warehouse, promised to orders, and on its way.

Announce stock you are sending us; we report what was counted in.

Send paid orders for fulfillment and follow them to delivery.

Get told when things change instead of polling.