Orders & Fulfillment

Version 1.7 · Updated 2026-10-09

Read and manage orders you've already placed: their status, line items, where they ship, and cancellation. Same host, same API key: these routes live under /v1/fulfillment.

If you placed the order through POST /v1/commerce/submissions, start from the submission. GET /v1/commerce/submissions/{submissionId} tells you whether it produced orders. Each entry in its orders[] carries an actions.fulfillment.url that returns the matching fulfillment orders here. Follow an item's links.self for its current status, statusHistory, and shipments. See Submission Lifecycle for the whole path.

Base URL

Every path on this page is relative to that prefix, so /orders means https://apis-stage.whcc.com/api/v1/fulfillment/orders. Send WHCC-API-Version: 2026-10 on every request; see API Versions.

Authentication

Send your API key as a bearer token:

1
2
curl https://apis-stage.whcc.com/api/v1/fulfillment/orders \
	-H "Authorization: Bearer <YOUR_API_KEY>"

Your key needs the apikey scope. Keys WHCC issues carry it by default. If yours doesn't, these routes return 403. See Refusals.

You never send an account identifier. WHCC resolves your account from the key itself, and no field, header, or query parameter can point a key at another account. An order that isn't yours returns 404.

Operations

These are the routes an API key can call, along with Event Subscriptions. Parameters, response schemas, and status codes for each are in the OpenAPI spec at GET /openapi.yaml, served without authentication. Routes open to API keys are marked x-whcc-api-key: true there. If this page and the spec ever disagree, the spec is right.

Listing orders

GET /orders returns your orders newest first as { "items": [...], "pagination": {...} }. Filter and page with these query parameters. Any other name returns 400.

There is no orderNumber filter: it returns 400 like any other unknown name. To read an order by its number, call GET /orders/{orderNumber}.

GET /orders/configured-products requires sourceOrderId and returns, for each order from that submission, the configuredProductId values it holds: { "items": [{ "orderId", "orderNumber", "sourceOrder", "configuredProducts": [{ "configuredProductId" }] }] }. GET /orders/{id}/configured-products returns the same ids for one order as { "items": [{ "configuredProductId" }] }.

Reading an order

GET /orders/{id} takes a fulfillment order id (FO_ followed by 14 characters, case-sensitive) or the numeric WHCC order number. A well-formed id that isn't an order on your account returns 404 with a detail of Order not found: …. Anything else in that position, such as a confirmation id, a submission id, or an FO_ id of the wrong length, returns a 404 whose detail begins No route matches.

Timestamps on fulfillment orders carry the lab's UTC offset, such as 2026-02-06T13:38:34.348-06:00. Submission timestamps are UTC.

Canceling an order

1. POST /orders/{id}/cancel-actions returns a single-use token.
2. POST /orders/{id}/cancellation with that value as cancelToken in the body performs the cancellation.

Treat the token as opaque. It works exactly once and expires after a few minutes. To retry, start again from the first call. A successful cancellation returns 200 with { id, orderNumber, outcome: "canceled" }.

Whether an order can be canceled depends on the order, not the environment. An order's response includes links.cancelActions only while it is cancelable, so if you follow links you'll never be offered a cancellation that would be refused. Asking anyway is safe: on an order that can't be canceled, the first call returns no token, just a 422 with code order_not_cancelable and a cancelEligibility object that explains why. The same object appears on order detail.

On this route an id that names no order on your account returns 422 with cancelEligibility.reason of order_not_found, not a 404. Reading the same id with GET /orders/{id} returns 404. An id that isn't shaped like an order id or order number returns 404 here too. See Reading an order.

Changing where an order ships

Four routes cover one resource:

Preview first, then send the ETag the preview returned as the PUT's If-Match header. That way you write exactly what you previewed.

The request body

The preview and the PUT take the same body: the whole new address as shipTo, and optionally the option to move to.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -X PUT https://apis-stage.whcc.com/api/v1/fulfillment/orders/<orderId>/shipping \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "Content-Type: application/json" \
	-H 'If-Match: <ETAG>' \
	-d '{
			"shipTo": {
				"attn": "Dana Whitfield",
				"name": "Whitfield Studio",
				"addr1": "64 Dikeman St",
				"city": "Brooklyn",
				"state": "NY",
				"zip": "11231",
				"country": "US"
			},
			"shippingOptionId": "<id from GET /orders/{id}/shipping/options>"
		}'

Any other key in the body returns 400. A bad address returns 422 with invalidParams[], such as shipTo.city with the reason Required.. That check runs before the third-party-billing check, so a bad address gets 422 even on an order that can't change shipping, and 409 only follows a body that is valid. A successful PUT returns 200 with the same shape as GET /orders/{id}/shipping (shipTo, shippingOptionId, shippingCharge, thirdPartyBilled, deliveryLocation) and the new ETag.

If-Match is required on the PUT

Send the ETag from GET /orders/{id}/shipping back unchanged. It's opaque, so don't parse or construct one. A PUT without it returns 428 (if-match-required). One with a stale value returns 412 (etag-mismatch), and nothing is written. Both are checked before the third-party-billing check, so they come back even on an order that can't change shipping. They are not checked before the order lookup: an id that names no order returns 404 first. A successful PUT returns the next ETag, so you can make a second change without re-reading. The options list carries no ETag. Its current marker is only a hint, so read GET /orders/{id}/shipping to know which option an order really holds.

Availability

The shipping read always answers. WHCC can pause shipping changes, and while they're paused the options read, the preview, and the PUT all return:

1
2
3
503 Service Unavailable
{"type":"about:blank","title":"Service Unavailable","status":503,
 "detail":"Shipping changes are temporarily unavailable."}

That response carries no Retry-After and retrying won't help. A 503 on the PUT with code shipping_change_not_begun is different: the request ran out of time before anything was sent, and you can retry the identical request right away.

Reading your account

GET /account returns the account your key belongs to: who it is, where it ships and bills, and how it pays. Use it to confirm which account a key is bound to, or to show the studio's own address at checkout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
	"id": "ACCT_vY9KecqAFCwFuY",
	"accountId": "whcc_88888",
	"accountLabel": "88888",
	"brand": "WHCC",
	"name": "Brown Photography",
	"contact": "Doc Brown",
	"emails": ["doc@example.com"],
	"phone": "555-867-5309",
	"tags": [],
	"addresses": {
		"shipping": { "attn": "Doc Brown", "name": "Brown Photography", "addr1": "1640 Riverside Drive", "addr2": null, "city": "Hill Valley", "state": "CA", "zip": "95420", "country": "US" },
		"billing": { "…": "the same shape, or null" }
	},
	"financials": {
		"payment": {
			"status": "not_requested",
			"terms": "Per Order Credit Card",
			"methods": [],
			"requirements": { "cardAtCheckout": true, "cardOnFile": true }
		},
		"tax": { "taxable": true, "exemptCertificate": null }
	},
	"identity": { "organizationId": "org_…", "userId": "user_…" }
}

Not available to API keys

API keys can't call GET /orders/{id}/form. It returns WHCC's stored order-form HTML, which isn't a format this API documents or keeps stable.

Refusals

A missing, expired, or revoked key is a 401. The gateway answers before the request reaches WHCC, with a one-field {"message":"Unauthorized"} body and no Problem Details to parse. Ask WHCC support for a new key.

Two different things return 403, and the body tells them apart.

The gateway rejected the key. It isn't valid for this host or route. The body is minimal:

1
2
403 Forbidden
{"message":"Forbidden"}

The service rejected the request. The key is valid but doesn't carry the scope this route needs. The body is RFC 9457 application/problem+json and names the cause:

1
2
3
4
403 Forbidden
Content-Type: application/problem+json
{"type":"about:blank","title":"Forbidden","status":403,
 "detail":"Insufficient scope. Requires: apikey"}

The text after Requires: varies by route and can list more than one scope, so don't match on the whole detail. The words Insufficient scope at the start are the part to check. A path under /v1/fulfillment that isn't a route can also answer 403, not 404.

For the first, fix the key. For the second, contact WHCC to have apikey added. Every other refusal from the service uses the problem+json shape, with a detail and usually a code but no instance field. A path that isn't a route, or a method a route doesn't support, can instead return the framework 404 body described under Other response bodies: