Response Bodies

The product's identifier. Store it, and pass it as productId everywhere else, including GET /v1/catalog/products/{ref}. A ref is case-sensitive: send it exactly as returned, since Framed-Print or the product's display name returns 404. Use the ref on every route, and don't rely on any other id being accepted.

What to show your customer and how to group products. category.ref is a token to compare, not to parse. New kind values can appear over time; treat one you don't recognize as a product you don't handle yet.

"api" means you can build this product entirely through the API. "editor" means a person has to finish its design in a WHCC editor before it can be ordered.

The finished size in inches, its shape (portrait, landscape or square), the image resolution it needs, and the print bleed. These are optional, and most list rows carry none of them. When width and height are missing, the size usually depends on a selection you haven't made yet, and the product's detail names which one in sizedBy. A product with no sizedBy and no resolution, such as an accessory or a sample set, has no printed size at all.

How many can be ordered at once, when the product lists a quantity range. step counts up from min; a quantity outside the range or step is rejected, not rounded.

The link to this product's full detail. Follow it rather than building the URL yourself. The url is absolute, like every action URL. See Follow links between calls.

How many products match, and the cursor for the next page. Pass nextCursor back as the cursor query parameter; it's missing on the last page. Treat the cursor as opaque, and keep category and q the same while you page: a cursor sent with different filters returns 400. The 400 has no code. Its title says what was wrong: cursor is malformed (which is also what you get for a cursor that was edited or cut short) or cursor was issued for a different set of filters. A cursor expires after 24 hours and returns 410. Either way, start again without one. You can change limit between pages.

A short marketing line for the product, ready to show your customer. Optional: many products don't have one.

Which field(s) in configuration.fields[] decide the product's physical size. Absent on products with no printed size.

The dictionary for your selections: each entry's field is a key you send, and each values[].id is a value for it. name and an optional description are for display. Key your code on id, never on name: two values in one field can share a name (a frame can list several mouldings called "black"), and the same field can be named differently from one product to the next. default is a suggested value; send every applicable choice rather than assuming a default will be filled in. Values shown here may not work in every combination. Step 4 checks the complete set; choose options in Step 3.

enum is a list of choices in values[]. Show a picker, and grey out any value with enabled: false. Size values also carry width and height in inches. dimension is a custom size: it carries unit and constraints (a min and max for each of width and height) instead of values[], so show two number inputs. Quick Start Step 3 shows the request. Treat a kind you don't recognize as a field you can't offer yet.

Where to build the configured product from your selections and images. The create response includes product pricing.

The submission ID. Save it to look up this request with GET /v1/commerce/submissions/{submissionId} or share it with WHCC support.

Where the submission is on its way to becoming a shipped order. See Submission Lifecycle for all seven values, including partially_failed.

When WHCC accepted the submission, as an ISO 8601 timestamp in UTC.

Read this, not status alone. One entry for each WHCC order this submission produced. An entry that failed carries a failure object (see Errors). Each entry has confirmationId, orderNumber, status (order_placed, order_received, order_shipped, order_canceled, order_failed and so on), shippingInfo (once it ships), and actions.fulfillment. An entry that failed has only status and failure, with no confirmationId and no actions. The key is missing until the submission reaches WHCC. orderNumber is the WHCC order number. It appears once WHCC has received the order (order_received or later) and the key is absent before that. The fulfillment order carries the same number, and GET /v1/fulfillment/orders/{orderNumber} reads an order by it.

Read the two totals carefully. totalPrice.value is the grand total including tax; totalPrice.total.value is the total before tax. The price isn't locked in, so the amount placed can differ from what you saw at submit. subtotals.salesTax has three states. Normally it is money. When the address is complete but tax can't be worked out yet (a country other than the US or Canada, an APO/FPO address, Canada without a province or zip, or a state or zip WHCC can't place), salesTax.value is the string "TBD" and the two totals match. For Alaska and the US territories it is 0.00. When a US address is missing its state or zip, or either is too short, salesTax is null or absent and totalPrice.value is the pre-tax amount. Check for both before parsing money.

The breakdown: product, packaging, shipping, surcharges, discount, salesTax and minimumSurcharge. Each is money or null, apart from the salesTax states above. packaging, shipping and salesTax also carry a label and an items[] split by line item. shipping can carry a description too, such as "Actual Postage". When a minimum-order surcharge applies, minimumSurcharge and surcharges.minimum hold the same object: the amount plus an items[] naming the product group it applies to. It depends on the shipping priority as well as the items, so the same item can carry it at one priority and not at another. It is already included in surcharges.value and the totals.

Present when a destination fee applies: the Minnesota or Colorado retail delivery fee, or the Canada import surtax. It is money plus an items[] naming the products it applies to, and it is already included in surcharges.value and the totals. The Canada surtax can be a large share of the order, so show it to your customer. The key is absent when no fee applies. It can also appear on a build response's totalPrice.

Money is { "value": "76.45", "code": "USD" }, and value is a string. One exception: subtotals.packaging.items[].value is a number with no code.

isValidForSubmit tells you whether the submission can be placed. On calculate with a partial address, invalidParams[] names each missing field, such as shipping.address.zip. Ignore isValidDiscount.

Your WHCC account, the one your key belongs to.

What you sent, returned as-is. instructions is an optional free-text note that is sent to WHCC with the order. Calculate accepts and returns it, but places nothing. metadata is {} when you didn't send one; instructions and reference come back as "" when unset, and as null if you sent null. Calculate enforces no length limit on instructions. See Metadata & Reference.

The address the order ships to. Fields you didn't send come back as null. The shipTo on the fulfillment routes is a different shape: it has no email, and if you sent no phone it shows the account's phone number rather than null. See Changing where an order ships.

The shipping type and method WHCC is actually using, and the packaging choice (null for the default). Check these to confirm you got the shipping you asked for. An order can ship in more than one package; for what actually ships, follow each orders[] entry's actions.fulfillment. See Shipping.

Plain-language notes about this response that aren't errors, such as a reminder that one submission can become several WHCC orders. Each is { code, message }. The codes you'll see are listed under Guidance codes; new ones can appear, so show or ignore one you don't recognize.

A { url, method: "GET" } link to the fulfillment orders created from this submission. The submission-level link covers every order it produced; each orders[] entry has its own link for just that order. The link returns a list ({ "items": [...], "pagination": {...} }), which can be empty for a little while after placement or contain several fulfillment orders. Follow an item's links.self to read its production status and shipments. See which order endpoint to use.

The configured product you built and submitted. Match response items to what you sent by this ID. productId names the catalog product, so it repeats when two items use the same product. Items can come back in any order.

Names ready to show your customer: the product's name (label), a fuller description such as "8×10 Framed Print", and an optional second line (often "").

How many, the price of one, and the line total. The unit price can drop as the quantity rises, so the calculate response, not the build response, is the price to show.

WHCC's ID for the underlying product.

Rendered previews of the finished item, in order; the first is the primary. Empty until rendering completes. Each has a stable key (such as main, front_cover, or inside) and a human-readable label, plus image URLs at four widths (scale_256 to scale_2048) for thumbnails and full views. Each element also carries its own previewUrl: a convenience alias for that element's scale_1024, null when that width has not rendered.

Custom-size products only. When the dimensions you sent were rounded up to the next priced size, this is the size you were charged for, as { "width", "height" } in inches and in the orientation you submitted, for example { "width": 11, "height": 14 } for a 10.5×13.5 gallery wrap. Absent on an exact match and on products without custom dimensions. It's on the build response. Calculate doesn't repeat it.

The choices that describe this item, ready to display. For example, name "Moulding" with description "Woodland 3/4" walnut frame". id matches the selection's field in the catalog. It isn't a copy of your selections: fields that don't change how the item is described are left out, and an option you turned off can read "None". A selection you sent that is missing here may have been dropped, so check before you submit. See Quick Start Step 3.

Whether this item is ready to order and, when it isn't, a list of what's missing (decoded in Quick Start Step 4).

Proof images to show your customer what was ordered: designSpaceProof (the design) and placementProof (the image as placed on the product). A build response can also carry proof, a shareable page showing the product preview. All of these open without your API key or a login, and they don't expire, so anyone who has the URL can view it. Share them with your customer, and don't post them publicly.

The item's own metadata map, returned as you sent it, or {} when you didn't send one. See Metadata & Reference.

Appear on some products only: how WHCC produces the item and the packaging chosen for it. Useful for display; safe to ignore.

The primary preview at 1024 px wide: identical to previews[0].scale_1024 (and to previews[0].previewUrl). null until rendered.

The same values as on the full submission. A list row doesn't carry items or metadata. Fetch the submission for those.

How many items the submission holds, and its grand total as { value, code }. For the full price breakdown, fetch the submission itself.

Every order number in orders[], as a flat list. Handy when a customer reads you a number off their packing slip. Missing until WHCC has received the first order.

Links to the full submission and to its fulfillment orders.

Whether there's another page, and the cursor to fetch it: pass nextCursor back as the cursor query parameter. nextCursor is missing on the last page. Treat it as opaque, and don't change your filters mid-walk: a cursor that was altered returns 400 with code: "CURSOR_INVALID", and one issued for different filters returns 400 with code: "CURSOR_FILTER_MISMATCH". An expired cursor returns 410. Either way, start again from the first page.

Plain-language notes about the list, the same shape as a submission's own guidance[].

true returns only submissions with at least one failed order, so both failed and partially_failed. This is the quickest way to find what needs your attention.

Only submissions in one status. On a long history this can be slower than hasFailure.

Only submissions carrying that exact value. These filter the list; they don't look up a single submission, so you get a page back (possibly empty), never a 404. orderNumber matches only once the submission carries that number, which is after WHCC has received the order.

Only submissions created after or before an ISO 8601 timestamp.

Page size, from 1 to 100 (default 25), and the nextCursor from the previous page.

The shipping methods available for this basket and address, each with its price. Each entry has id, type, priority, label and price. To choose one, send its type and priority as shipping.type and shipping.priority. Only present when you send a shipping address, because the price depends on where it's going.

Read the code as naming totalPrice.total, which is the pre-tax amount. totalPrice.value includes tax, and that is what to bill. See Submission fields.

You calculated without an address, so shipping and tax are absent and totalPrice is a product subtotal. See Calculating with no shipping address.

One submission can become several WHCC orders, each with its own number and confirmation ID, shipping and tracking on its own. Track each entry in orders[].

WHCC's order system rejected the order. Contact support with the submission ID. See Errors & Rate Limits.

The submission is queued and not yet placed. Hear the outcome through an event subscription, and read the submission once after it settles.

An order's id is its permanent identifier. Use it to look the order up and to match it to your records.

The WHCC order number isn't assigned yet. Use id until orderNumber appears.

Items in a response aren't in a guaranteed order. Match them by configuredProductId, never by position.

Shipment details appear once the order reaches order_shipped. Treat the order's status as the truth about whether it shipped; a shipped order can, rarely, carry no shipment detail.

Appears on orders that have reached fulfillment. Cancellation through the API is possible only while an order is eligible; see Canceling an order, and contact customer service otherwise.