orders

Create one order

Name the SKU and where it goes. The SKU decides the product, the variant and the price — sending a product id alongside would let a client name its own price, so the server reads all three from the SKU and ignores anything else you send about them.

Two ways to name what you want: product_variant_id from the catalogue, or product_id plus an options map of catalog-v2 axis codes (the server resolves those to a physical SKU, creating it on first use).

An Idempotency-Key header is REQUIRED. Without one, a dropped response leaves you unable to retry safely — which is exactly how duplicate orders get made. Replaying a key returns the original order with status 200 instead of 201.

post/orders

Request

  • Base URL: https://0.0.0.0:3000/api/v1
  • URL: https://0.0.0.0:3000/api/v1/orders
  • Auth: API key in header x-api-key

Headers

Idempotency-Keystring required

Any unique string of your choosing. Scoped to your account, so it cannot collide with another seller's.

Request body

external_idstring required

Your own order id. Not unique here — one marketplace order can split into several rows — but it is how support finds anything.

product_variant_idinteger

The SKU, from GET /catalog. Send this OR product_id + options.

product_idinteger

Catalog v2: the product, paired with options.

optionsobject

Catalog v2: one active value code per option axis, e.g. { "method": "P", "color": "KL" }. Keys are axis codes and are NOT converted — send them exactly as the catalogue lists them.

quantityinteger required

1–10000.

shippingobject required

name, company, email, phone, line1, line2, city, state, zip, country. name, line1, city, state, zip and country are REQUIRED and must be the customer's real details: a placeholder such as 1, x, n/a or a masked 73** **** is refused with invalid_request, and error.fields names each field. state is the two-letter code, e.g. IL or WA — a full name such as Texas, or anything longer than two letters, is refused the same way. company, email, phone and line2 are optional.

shipping_typestring required

REQUIRED. Who ships the parcel — exactly Ship by OP or Ship by Platform. Ship by OP: we ship it, we buy the label, and postage is added to what you pay. Ship by Platform: you or the marketplace ships it and already holds the label, so no postage is charged and the customer-ship price applies. There is no default — an order with none would be priced as though you shipped it, and no label could be bought for it. A carrier service (Standard, express) is a different thing and is refused here. Letter case does not matter; ship by op is accepted and stored as Ship by OP.

marketplacestring

Which shop it came from, e.g. Etsy UK.

placed_atstring

When the marketplace took the order. Defaults to now.

deadlinestring

When it must ship by.

image_urlstring required

REQUIRED. The design to print. An order cannot be produced without one, so it is refused rather than accepted and held.

mockup_urlstring required

REQUIRED (or mockup_id). The mockup picture — what the listing shows. Stored once per picture per account, so re-sending the same link reuses the same mockup rather than making another.

mockup_idinteger

A mockup already in your library, from a previous order. An alternative to mockup_url; either one satisfies the mockup requirement.

add_onboolean

true adds the product's add-on — a gift box, say — to every unit of this order, at the per-unit price GET /catalog shows as add_on. It is billed inside base_cost. Refused on a product whose add_on is null.

notestring

Anything the floor should read.

Response

Created. Status 200 instead when the Idempotency-Key was a replay.

Changes

No recorded changes to this operation across all 1 revision of this API.