POST

Quick order (product + order)

Recommended single-call flow for API integrators (V1-style). Send your shop `orderid` (required), shipping address, and one or more product lines with `sku` + print-file URLs. **How it works — read this before integrating.** The response returns the full order **immediately** (in about 1 second) with `status: "PENDING"` and `assets: "PROCESSING"`. At that moment the order exists and has an `id`, but the print files are still being downloaded and attached to the catalog product in the background. This endpoint does **not** charge the wallet — the order stays a PENDING draft until you submit it (from the portal, via POST /orders/{id}/submit, or by using POST /orders/quick/submit instead). Use `assets` (or poll GET /orders/quick-order/{id}/assets) to know when the print files have landed: `PROCESSING` → `READY` (all files attached) or `FAILED` (a design URL could not be downloaded — the order stays PENDING and unpaid so nothing is charged). **SKU resolution.** When `blueprintId` is omitted, the server resolves blueprint + provider from `sku` automatically; if the same sku matches more than one catalog row, the API returns an error — add `blueprintId` and retry. A brand-new catalog product is created for each order line and the print files in `designUrlsByArea` are attached to it. Sending the same `orderid` twice returns HTTP 409 (duplicate) — cancel the existing order first if you need to recreate it. Optional per line: `blueprintId` (disambiguation), `productId` (pin a catalog product), `providerBlueprintId` (narrow provider). Legacy V1 aliases (`firstname`, `zipcode`, `methodship`, `areafront`, …) are still accepted.

POSThttps://api-sandbox.merchfox.com/api/v1/orders/quick

Request body

string

Your shop order reference (required — same field as MerchFox API V1). The gateway sets `externalId = orderid` and an internal idempotency key. Sending the same orderid twice returns **HTTP 409** with the existing order id — cancel that order first if you need to recreate it with the same reference.

string

System-managed — auto-filled from `orderid`. Do not send unless you need to override the default idempotency key.

string

System-managed — auto-filled from `orderid`. Shown in webhooks and the seller portal. Do not send unless you need a different display reference.

string

Recipient first name. Legacy alias: `firstname`.

string

Recipient last name. Legacy alias: `lastname`.

string

Street address line 1.

string

Street address line 2 (apartment, suite, etc.).

string

City.

string

State / province code.

string

ISO 3166-1 alpha-2 country code (uppercase).

string

Postal / ZIP code. Legacy alias: `zipcode`.

string

Buyer email (informational — not used for fulfillment routing).

string

Recipient phone number.

string

Provider shipping service: FIRST_CLASS (default), PRIORITY, RUSH, EXPEDITE, or OVERNIGHT. Legacy alias: `methodship` integer 1–5 maps to the same values.

string

Seller-provided shipping label URL or S3 key (from POST /assets/upload-seller-label). Sets shippingMode=SELLER_LABEL. Legacy alias: `label`.

boolean

When true, enables the Early In-Transit Scan add-on. Legacy alias: `scanrequest` "0"/"1".

integer

Set to 2 for double-sided / special print. Legacy alias: `special_print` "0"/"1".

boolean

When true, also calls POST /orders/{id}/submit after creating the draft — charges the wallet and sends to fulfillment. Default false (PENDING draft only).

boolean

Opt into the product-mint flow: a brand-new catalog product is created for each line and its print files are attached in the background (`assets: PROCESSING` → `READY`). Set to `true` to apply the per-line `sellingPrice`, `largeFormatAreas`, `hasSpecialPrintArea`, and neck-label (`NECK_LABEL_INNER` / `MOCKUP_NECK_LABEL_INNER`) fields. Default false.

json

Array of product lines (max 50). Minimum per line: `sku` + print-file URLs via designUrlsByArea. `blueprintId` is optional when sku is unique. Optional mockupFrontUrl / mockupBackUrl for order-list previews. Per-line `sellingPrice`, `largeFormatAreas`, `hasSpecialPrintArea` and neck-label areas apply when `createProducts` is true.

Authenticate first using the “Auth” button in the header.

Example responses

reference · no API call

Response fields

Field
Type
Description
code*
int
Application status code. 0 = success; non-zero = error (1xxx auth, 2xxx request, 4xxx rate/quota, 5xxx server). HTTP status is always 200 — the envelope code is what callers branch on.
message
string
Human-readable result. Empty on success, error reason on failure.
request_id*
string
Hex correlation id (16 chars). Propagates across services; include in support reports so logs can be grep-ed.
data
object
Endpoint-specific payload. See nested fields below.
id
string
Order id (UUID).
externalId
string
Caller-supplied reference (e.g. Shopify order number).
status
enum
PENDING | PAYMENT_PENDING | PAID | SUBMITTED | IN_PRODUCTION | SHIPPED | DELIVERED | CANCELLED | REFUNDED.
currency
string
Order currency (USD, CAD, GBP, EUR, AUD).
items
[]object
Line items.
shippingAddress
object
Recipient address.
itemsTotal
string
Sum of all lineTotals.
shippingTotal
string
Shipping cost.
taxTotal
string
Tax amount.
grandTotal
string
itemsTotal + shippingTotal + taxTotal.
tracking
object
Carrier + tracking number (after SHIPPED).
timeline
[]object
Lifecycle events in chronological order.
assets
enum
Print-file download state: PROCESSING (attaching in background) | READY (all files attached) | FAILED (a design URL could not be downloaded — order stays PENDING, unpaid). Poll GET /orders/quick-order/{id}/assets to follow it.
createdAt
string
ISO-8601 creation timestamp.

Example

HTTP 200code=0The order exists immediately with status PENDING and assets PROCESSING. Print files attach in the background; poll GET /orders/quick-order/{id}/assets for READY/FAILED. No wallet charge on this endpoint.
{
  "code": 0,
  "data": {
    "id": "019f276a-f9bb-7728-be66-cbb08f82b92e",
    "externalId": "TEST-PUSH-0029",
    "status": "PENDING",
    "assets": "PROCESSING",
    "currency": "USD",
    "items": [
      {
        "productId": "665f0a2b1c9d440012ab34cd",
        "variantId": "55104",
        "quantity": 1,
        "unitPrice": "11.95",
        "lineTotal": "11.95"
      }
    ],
    "itemsTotal": "11.95",
    "shippingTotal": "7.99",
    "grandTotal": "19.94",
    "createdAt": "2026-07-03T09:58:47.263Z"
  },
  "message": "Success",
  "request_id": "a1b2c3d4e5f6a7b8"
}

Code samples

curl -X POST 'https://api-sandbox.merchfox.com/api/v1/orders/quick' \
  -H 'X-Mfx-App-Key: <YOUR_API_KEY>' \
  -H 'X-Mfx-App-Secret: <YOUR_API_SECRET>' \
  -H 'Content-Type: application/json' \
  -d '{"orderid":"354354354353","firstName":"Jane","lastName":"Doe","address1":"1 Main St","city":"Austin","state":"TX","country":"US","zip":"78701","email":"[email protected]","phone":"+1-555-0100","fulfillmentServiceKey":"FIRST_CLASS","priorityTrackingAddOnEnabled":false,"printAreaCount":1,"submit":false,"createProducts":true,"products":[{"sku":"55104","quantity":1,"sellingPrice":24.99,"hasSpecialPrintArea":true,"largeFormatAreas":["FRONT"],"designUrlsByArea":{"FRONT":"https://cdn.example.com/front.png","BACK":"https://cdn.example.com/back.png","NECK_LABEL_INNER":"https://cdn.example.com/neck.png"},"mockupUrlsByArea":{"MOCKUP_FRONT":"https://cdn.example.com/mockup-front.jpg","MOCKUP_NECK_LABEL_INNER":"https://cdn.example.com/mockup-neck.jpg"}}]}'