Connect your store to POD Mfg.

The basics

Base URL

https://app.podmf.com/api/v1 (paths below are relative to it)

Auth

Authorization: Bearer <key> on every request. Keep keys on your server, never in a web page.

Keys

podmfg_test_... test mode: orders are stored and answered but never charged and never made. podmfg_live_... live mode. Same base URL; the key decides the mode. A test key never sees live data and the other way round.

Format

JSON only. Times are ISO 8601 UTC. Money is integer cents plus currency (2800 is $28.00 USD). Ids are prefixed (prd_, var_, ord_, shp_, evt_, whk_).

Lists

Cursor pages: ?limit=50&starting_after=<id> answers { data, has_more, next_cursor }.

Versioning

Within v1 changes are additive only: ignore fields you don't know.

Coverage

US ship-to only. Products with names or numbers can't be ordered yet (422 personalization_unsupported).

Check your key:

curl https://app.podmf.com/api/v1/me \
  -H "Authorization: Bearer $PODMFG_API_KEY"

The minimal flow

1. GET /products: your published products, each with variants (a color and size) carrying our id (var_...), our sku, your external_sku, retail_price, wholesale_price and in_stock. Use ?updated_since= to sync changes. Images are signed links that expire after 24 hours: re-fetch rather than store them.
2. Map variants to your store. Either store our variant_id / sku against your products, or set your own SKU on ours with PATCH /variants/{id} { "external_sku": "..." } (or on the Developers page, Product mapping, which also downloads the whole catalog as CSV with every id).
3. POST /orders when your customer pays. Each line names exactly one of variant_id, sku or external_sku. Always send an Idempotency-Key and your external_order_id (unique per brand and mode). Answers 201 with the order's status and charge. A live order is charged now: paid, or payment_failed (retried automatically), or on_hold (not charged until released). A test order answers paid with charge.status: simulated.
4. Handle webhooks (below): mark the order shipped with tracking on order.shipped, and react to order.paid, order.payment_failed, order.on_hold and order.cancelled.

curl -X POST https://app.podmf.com/api/v1/orders \
  -H "Authorization: Bearer $PODMFG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_order_id": "1042",
    "shipping_method": "standard",
    "ship_to": { "name": "Jane Smith", "address1": "123 Main St", "city": "Irvine",
                 "state": "CA", "postal_code": "92618", "country": "US" },
    "line_items": [
      { "variant_id": "var_...", "quantity": 2, "external_line_id": "li_1" }
    ]
  }'

Optional: POST /orders/estimate prices a cart (wholesale plus shipping) without creating anything. GET /orders/{id} and GET /orders?external_order_id= read an order back. POST /orders/{id}/cancel cancels before production (full refund if paid). POST /orders/{id}/retry_payment charges a failed order again after the owner fixes the card. shipping_method is standard (cheapest, the default) or expedited (fastest).

Webhooks

Add an endpoint on the Developers page (Webhook endpoints) or with POST /webhook_endpoints { "url": "...", "enabled_events": ["*"] }. The answer's secret (whsec_...) is shown once; POST /webhook_endpoints/{id}/rotate_secret replaces it (the old one stops at once). A test key makes a test endpoint, which gets only test-order events; live endpoints get live events and must be https://. Product events go to both. Every endpoint must be a public address; we don't follow redirects.

Each delivery is a POST of { id, type, created_at, livemode, api_version, data } with headers PODMFG-Signature, PODMFG-Event-Id and PODMFG-Event-Type. Order events carry order_status and the whole order object.

• Verify every delivery. PODMFG-Signature: t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of "<t>.<raw body>" keyed with the endpoint's whole whsec_... secret. Use the raw bytes before JSON parsing, compare in constant time, and refuse a t more than 5 minutes from your clock. Full samples: quickstart, step 5.
• Answer fast. Any 2xx within 10 seconds counts. Queue the work, then answer.
• Retries. Anything else is retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h, 24 h and 24 h: 9 tries over about 3 days. Then the delivery has failed, the owners are emailed, and the Developers page (or POST /events/{id}/resend) can send it again.
• Dedupe on the event id. Delivery is at least once, so the same event can arrive twice.
• Order isn't guaranteed. Use order_status and the times in data, or fetch the order.
• Polling fallback. GET /events?since=<ISO time>&type=<type> lists the last 30 days of events exactly as sent, to backfill after downtime or instead of a webhook.
• Auto-disable. An endpoint whose deliveries fail for good 5 times in a row is turned off and the owners are emailed. Fix it, then Turn on (or PATCH /webhook_endpoints/{id} {"status":"active"}).

// Node: check PODMFG-Signature on the RAW body before you trust a webhook.
const [t, ...sigs] = header.split(",").map((p) => p.trim().split("="));
// secret = the endpoint's whole whsec_... string
const expected = crypto.createHmac("sha256", secret)
  .update(`${t[1]}.`).update(rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t[1])) <= 300;
const ok = fresh && sigs.some(([k, v]) => k === "v1" && v.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));

Test vector: secret whsec_test, t=1700000000, body {"a":1} gives v1=38877139021993b830af32feea6e18a8da83eb2f6e49ee50bd9e4cf4ca4d3789.

Test mode and the sandbox

With a test key, build the whole flow end to end. After you create a test order, make things happen to it: POST /orders/{id}/simulate/ship (a parcel with TEST... tracking, sends order.shipped), .../simulate/payment_failed (sends order.payment_failed; then retry_payment sends order.paid) and .../simulate/cancel (as if we cancelled it, sends order.cancelled). Simulations refuse a live key (403 test_mode_only). Send test event on the Developers page sends a signed ping to one endpoint: ignore event types you don't know.

Retries, rate limits and errors

• Idempotency. Send Idempotency-Key (a UUID) on every POST. A timeout? Send the same request with the same key: you get the first answer (Idempotent-Replayed: true), never a second order or charge. Keys last 24 hours; a request that failed frees its key.
• Rate limit. 10 requests a second per key, bursts of 50. Every answer has X-RateLimit-Limit and X-RateLimit-Remaining; a 429 has Retry-After. Repeated bad keys from one address are paused for a while.
• Request ids. Every answer has X-Request-Id. Log it, and quote it when you contact us. The Developers page's API request log shows the last 30 days of calls.

Errors always have this shape, with the right HTTP status:

{
  "error": {
    "type": "invalid_request_error",
    "code": "variant_not_found",
    "message": "Variant var_123 does not exist or is not published.",
    "param": "line_items[0].variant_id",
    "request_id": "req_..."
  }
}

Developer go-live checklist

• Swap the test key for the live key the owner gives you, stored as a server secret.
• Add a live webhook endpoint (https) and store its own whsec_ secret. Test and live endpoints have different secrets.
• Signatures verified on the raw body; event ids deduped; work queued and answered within 10 seconds.
• Every POST sends an Idempotency-Key; retries reuse it.
• external_order_id is your real, unique order number.
• Every product you sell maps to a published variant (variant_id, sku or external_sku).
• You handle payment_failed and on_hold (tell the owner) and order.shipped (one per parcel).
• Non-US addresses and personalized products are stopped before they reach us.
• A backfill from GET /events runs after any downtime.