Merch Factory API

You design products once in the Merch Factory editor and save them. Each saved product gets one SKU per size. Your system sends an order with those SKUs and the customer's address; we price it, pick a courier, charge your prepaid wallet and start production, exactly as if you had placed it in the dashboard. When the order is printed, shipped, delivered or returned, we tell your server through a webhook.

If you sell on Shopify, WooCommerce or Wix, use those integrations instead: they do all of this without code. The API is for everything else.

1. Save your products. Create your designs in the editor (dashboard → New product) and save them. Only saved products can be ordered through the API.
2. Create an API key. In the dashboard open Connectors → REST API and press Create key. Copy it once, it is not shown again. Store it as an environment variable on your server, for example MF_API_KEY.
3. Get your SKUs. Call GET /v1/products. Map each of your own products and sizes to a Merch Factory SKU such as MF-7kQpL2xVr9TzWm4BnC1d-L (kids sizes are age ranges: MF-7kQpL2xVr9TzWm4BnC1d-7-8Yr). SKUs never change, so map them once and store them.
4. Send an order. When a customer buys, call POST /v1/orders with the SKUs and their address. Keep enough balance in your wallet: the order is paid from it at once.

Every request needs an API key in the Authorization header. Keys look like mf_live_ followed by 32 letters and digits.

• Full access keys can read everything and create and cancel orders. Read only keys can only read; a write with one returns 403 FORBIDDEN.
• A brand can have up to 5 keys. Create one per website or tool, so you can revoke one without breaking the others.
• A key works for one brand only. Orders it places are charged to that brand's wallet and recorded under the team member who created it. If that person leaves the brand, the key stops working.
• Revoking a key in the dashboard stops it within 30 seconds.

• Send JSON with Content-Type: application/json. Bodies are limited to 64 KB.
• Responses are JSON. Single objects come back as { "data": { … } }, lists as { "data": [ … ], "has_more": true, "next_cursor": "…" }.
• Every response has an X-Request-Id header. Quote it if you contact support.
• Times are ISO 8601 in UTC. Money is in Indian rupees (INR) as a number, for example 1349.12.
• To read the next page of a list, pass the previous page's next_cursor as starting_after. When has_more is false you have everything.

For 429 and 503 responses, read the Retry-After header (seconds). Retrying any order request is always safe, see safe retries.

Every order carries your own reference, order_ref, which must be unique within your brand. Merch Factory turns it into the order's id, so the same order_ref can never create two orders or two charges.

If a request times out or your server restarts mid-call, send exactly the same request again. If the first one succeeded you get the existing order back with 200 and "duplicate": true; if it did not, the order is created now with 201. Use your store's own order number as order_ref.

A cancelled order keeps its order_ref. To order the same thing again, use a new reference such as WEB-1042-2.

Returns { "data": <product> }, or 404 NOT_FOUND.

Prices include GST and are what an order would be charged for shipping today. They can change between this call and the order; the order always uses the price at the moment it is placed. Ekart, Amazon Shipping and India Post / Speed Post are not offered through the API, so they are never listed or picked.

Orders take an optional courier field:

• Leave it out to use your brand's default rule, set in Connectors → REST API (cheapest unless you change it).
• A rule: "cheapest", "fastest" (fewest estimated days, then price) or "best_rated" (highest courier rating, then price).
• A courier name, as returned by GET /v1/couriers. Matching ignores case: "Delhivery" picks the cheapest Delhivery service, "Delhivery Air" only that one.

If the courier you named does not deliver to that pincode, the order uses your default rule instead and the response says "courier_fallback_used": true. Send "courier_fallback": false to get a 422 COURIER_NOT_AVAILABLE error instead.

If you set a highest shipping price in the dashboard, couriers above it are never chosen; when every courier is above it the order is refused with SHIPPING_TOO_EXPENSIVE. Once a parcel ships, the order shows the courier that actually carried it, which can differ when our hub reroutes a parcel.

• 201: the order was created and paid. 200 with "duplicate": true: this order_ref was already used by an earlier API call, nothing new was charged.
• Prices are always worked out by Merch Factory. Do not send prices; the wallet is charged the production cost of the items plus shipping.
• Before charging, we check stock for every size and colour, that each design is still current and sharp enough to print, and that your wallet covers the total. If any check fails, nothing is charged.
• Placing an order usually takes 3 to 8 seconds because design files are copied into the order. Use a timeout of at least 60 seconds.

Returns { "data": <order> }. Pass our id or your order_ref (URL-encode it if it contains # or /). Orders placed outside the API can be read too.

All of your brand's orders, newest first, whatever their source. For updates as they happen, use webhooks instead of polling this list.

Only orders that are still PLACED can be cancelled. The full amount goes back to your wallet at once and the response includes refund_inr. Once printing has started the request returns 409 CANNOT_CANCEL.

1. Open Connectors → REST API → Webhooks and press Add webhook.
2. Enter a public https:// address on your server, choose the events and whether you want updates for orders sent through the API only or for all your orders.
3. Copy the signing secret (whsec_…) into your server settings and use Send test to check your endpoint answers.

A brand can have up to 3 webhook addresses. Your endpoint must answer with any 2xx status within 8 seconds. Do slow work after answering. Redirects are not followed.

Order events carry the same order object as GET /v1/orders/{id}. While an RTO is on its way back the order's status still reads SHIPPED; it becomes RETURNED when our warehouse logs the parcel. Stock events list every affected SKU of yours in one event, so you can pause those products in your store.

Each event is sent once per webhook. If you see the same MF-Event-Id twice (because your server answered too slowly the first time), ignore the second one.

1. Read t and v1 from the MF-Signature header.
2. Compute HMAC-SHA256 of t + "." + raw request body with your whsec_… secret, as lowercase hex.
3. Compare it with v1 using a constant-time comparison, and refuse requests whose t is more than 5 minutes old.

Use the raw body bytes exactly as received. Parsing the JSON and serialising it again changes the bytes and the check fails.

You can see or change the secret any time with Signing secret on the webhook. After changing it, the old secret stops verifying at once.

If your endpoint does not answer 2xx within 8 seconds, we try again after 1 minute, 5 minutes, 15 minutes, 30 minutes, 1, 2, 3 and 4 hours, then every 6 hours, until 24 hours after the event. The dashboard shows each delivery and its last answer under Recent deliveries.

If every delivery to an address fails for 24 hours in a row, the webhook is removed and the brand sees a notice in the dashboard. Fix your server and add the address again. One successful delivery resets the clock.

We send at most 60 events a minute to one address; anything above that follows a minute later.

There is no separate sandbox: the API works on your real brand and wallet. A safe way to test:

1. Use a Read only key while you build the product mapping and order-status screens.
2. Place one real order to your own address with a full-access key and a test order_ref such as TEST-1.
3. Cancel it right away with POST /v1/orders/TEST-1/cancel. While it is still PLACED the full amount returns to your wallet.
4. Point a webhook at a request inspector or your staging server and press Send test.

Every write and every failed request appears under Recent activity on the REST API page for 30 days.

A machine-readable description of every endpoint is at https://www.merchfactory.in/api/v1/openapi.json (OpenAPI 3.1). Import it into Postman, Insomnia or a code generator to get a ready client.

Changes inside v1 only ever add fields or endpoints. Anything that would break an existing integration will come as v2, announced in advance.

Stuck? Open a ticket in the dashboard under Help → Integrations with the X-Request-Id of the call, or contact us. For what the API can do for your business, see the print on demand API overview.