> Part of [WHCC Developer Documentation](https://www.whcc.com/developer/llms.txt)

# Albums & Books

Updated November 19, 2026

Order albums and books through the WHCC API. You create the album or book from its product and a size, design it in the WHCC Album Editor, then check it's finished and submit it like any other item.

## Albums and books require the editor UI

**Designs and customization must be done inside the Album Editor.** There's no headless path for albums and books today: the API creates and prices one, and you, or your customer if you send them in, lay out its pages in the editor before it can be ordered. The edit link in [Step 4](https://www.whcc.com/developer/docs/guides/albums/#step-4) opens it, for whoever is designing.

Four products use the Album Editor. See [Albums & Books](https://www.whcc.com/products/albums-books/index.html.md) on whcc.com for sizes, covers and finishes.

| Product | Catalog `ref` (the `productId` you create with) | `kind` |
| --- | --- | --- |
| Album | `album` | `album` |
| Layflat Book | `layflat-book` | `book` |
| Hardcover Book | `hardcover-book` | `book` |
| Softcover Book | `softcover-book` | `book` |

Two boxes use the Album Editor too: Album Box (`album-box`) and Print Box (`print-box`), listed as `kind: "keepsake"`. They also require the editor UI at this time, and follow the same create, edit link and submit steps.

- **The product and a size are all a create needs.** The product detail lists every option, says which ones are required, and gives each a standard default. Anything you leave out gets its default, so you don't need to make every choice before the create call. Choose the rest in the editor.
- **Spreads or pages.** The editor works in full spreads. For Hardcover and Softcover Books, it also takes single pages, so you can bring in full-spread designs or page designs.
- **Autofill.** The editor's autofill places your photos or pre-made designs into the empty spreads in one step, adding spreads if it needs to.
- **No full PDF.** The editor can't take a finished album or book as one PDF at this time. Bring your designs in as images, by spread or by page.
- **Page and spread minimums are enforced.** Each product has its own minimum page or spread count. The editor shows it, and won't let you finish below it.

Everything an album or book shares with a print, from your API keys to the submission and the events that follow it, works as the [Quick Start](https://www.whcc.com/developer/docs/quick-start/index.html.md) describes, and this guide links there rather than repeating it. [Editor Handoff](https://www.whcc.com/developer/docs/api/editor-handoff/index.html.md) covers the edit link and the return from the editor, which albums and books share with cards. The examples use the Album; the steps are the same for each book.

> **Building with an agent?** Give it the prompt on [Build Albums & Books with an Agent](https://www.whcc.com/developer/docs/guides/albums/agent/index.html.md) and a test key, and it orders a test album, with you designing the album in the editor.

> **Before you start**, you need what the Quick Start lists: a [test key](https://www.whcc.com/developer/docs/quick-start/#api-keys) from Connected Accounts and a ship-to address. The examples use the test host, `https://apis-stage.whcc.com/api`, and every path below is relative to it. Send a `WHCC-API-Version: 2026-10` header on every request; see [API Versions](https://www.whcc.com/developer/docs/api/versioning/index.html.md). Whoever designs the album or book needs a browser, and your application needs an `https://` page for the editor to send them back to.

## Step 1: Find album and book products

### GET `/v1/catalog/products`

Lists the products your account can order, the same call as [Quick Start Step 1](https://www.whcc.com/developer/docs/quick-start/#step-1). Ask for `limit=200`, follow `nextCursor` to the end, and keep the products whose `ref` is in the [table above](https://www.whcc.com/developer/docs/guides/albums/#editor-required), or one of the two boxes. Match on `ref`: `kind` doesn't pick these products out, because the boxes are `keepsake`, which also covers mugs and keychains.

```shell
curl "https://apis-stage.whcc.com/api/v1/catalog/products?limit=200" \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10"
```

#### The Album in the response

```json
{
	"ref": "album",
	"name": "Album",
	"completion": "editor",
	"actions": {
		"detail": { "url": "https://apis-stage.whcc.com/api/v1/catalog/products/album", "method": "GET" }
	},
	"category": { "ref": "albums", "name": "Albums" },
	"kind": "album",
	"resolution": 300,
	"sizedBy": ["size"],
	"requirements": { "requiresDesign": false, "requiresImage": true, "workflow": "editor_required" }
}
```

These fields tell you what an album or book needs:

- **`completion: "editor"`.** It's designed and finished in the Album Editor before it can be ordered.
- **`requirements.requiresDesign: false`.** There's no design catalog to pick from. You create one from the product and a size.
- **`requirements.requiresImage: true`.** A finished album or book needs photos or designs, but you don't have to send them when you create it. Add them in the editor.

A product that isn't available in an environment doesn't appear in the list, and its detail returns `404` like a `ref` that doesn't exist. If you name it in a create request anyway, WHCC returns `400` with `code: "product_not_available"` and the title `This product isn't available to create yet:` followed by the `productId` you sent. Nothing is created.

## Step 2: Choose a size

### GET `/v1/catalog/products/{ref}`

Returns the product's `configuration.fields[]`: size, cover, paper, endleaves, inserts and the add-ons. Each field says whether it's `required` and carries a standard `default`. For an album or book, only `size` needs your choice. Pick a value the field lists as enabled:

```json
{
	"size": "10x10"
}
```

Every field you leave out is filled with its catalog default, with no error, and you can change most of them in the editor. Check `selectionsSummary[]` on the create response to see what was built.

#### If you choose options up front

You can send more than the size, for example to match options you've already shown your customer. Build `selections` as [Quick Start Step 3](https://www.whcc.com/developer/docs/quick-start/#step-3) describes, with these rules in place of its "send every field the product lists":

- **Send required fields, not every field.** A required field you send needs an enabled value. Send `cover_material` with a material cover.
- **Send an add-on only when it's wanted.** Cameos, dies, debossing and combo covers are `required: false`. Each one can change `unitPrice`, and some add work in the editor: a cameo or combo cover needs a photo, and debossing needs its text. Don't fill them with defaults. Defaults for the different cover options can't all be combined, and a conflict returns `400` naming the field, with `… can't be combined with the other selections on this product.`
- **You can't set the page or spread count.**`spread_count` isn't a published field, so sending it returns `400` with `code: "unknown_selection_field"`. On an Album, `insert_boards` sets the starting number of spreads. Add spreads or pages in the editor.
- **`quantity` is optional.** Leave it out and you get the product's default, as for a print.

The fields differ by product: a Hardcover Book has no `cover_padding` or `page_corner_style`, for example. Here's the Album's required set at its defaults, plus `cover_material`:

```json
{
	"quantity": 1,
	"size": "10x10",
	"cover_type": "material_cover",
	"cover_material": "premium_leather_black",
	"cover_padding": "non-padded_cover",
	"spread_style": "2_page_spread",
	"endleaf_style": "white_textured_endleaves",
	"asset_type": "individual_page_jpg",
	"insert_boards": "thick_white_inserts",
	"ba_paper_type": "ba_photo_lustre",
	"page_corner_style": "square_corners"
}
```

Check it against the product detail in your environment before you rely on it: the catalog says which values are enabled, and which fields are required, today.

## Step 3: Create the album or book

### POST `/v1/commerce/configured-products`

Creates the album or book from the product and a size, through the same route as [Quick Start Step 4](https://www.whcc.com/developer/docs/quick-start/#step-4):

```shell
curl https://apis-stage.whcc.com/api/v1/commerce/configured-products \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10" \
	-H "Content-Type: application/json" \
	-d '{
			"configuredProducts": [
				{
					"productId": "album",
					"selections": { "size": "10x10" }
				}
			]
		}'
```

It differs from a print in a few ways:

- **No `designId`.** If an album or book item carries one, WHCC returns `400` with the title `designId is not accepted for this product:` followed by the product.
- **No page or cover content.** The create takes selections and photos only. The spreads and the cover are designed in the editor, and a `content` key returns `400`.
- **No `redirects`.** Where the editor sends you back to is set when you [ask for the edit link](https://www.whcc.com/developer/docs/guides/albums/#step-4). If you send `redirects` here, WHCC returns `400` naming `redirects`.
- **Up to 20 per request.** Each album or book gets its own editor and its own `configuredProductId`. If a request has more than 20, WHCC returns `400` with the title `A request may include at most 20 editor-completed products`. If it mixes them with products marked `completion: "api"`, WHCC returns `400` with a title that starts `A request must be either all simple-editor products or all editor-completed products, not a mix:`. Nothing is created in either case.

Every `400` from the create is returned before anything is created, so fix the request and send it again.

#### Photos

`images[]` is optional. Leave it out and add photos and designs in the editor. If you already have them, you can send them with the create: each entry is `{ "url": "https://…" }` or `{ "imageId": "…" }`, as for a print. They go into the editor's photo pool, ready to place or autofill. None of them is placed on a spread for you. The same photo listed twice appears in the pool once.

```json
"images": [
	{ "url": "https://yourdomain.com/photos/0001.jpg" },
	{ "url": "https://yourdomain.com/photos/0002.jpg" }
]
```

#### Spreads

The album or book starts with its default number of blank spreads. Fill them, and add more, in the editor. You can't go below the product's minimum.

**Hardcover and Softcover Books count one more spread than they list.** These books open on a single right-hand page and close on a single left-hand page, and the editor treats each of those as a spread with one blank side. So a book whose `selectionsSummary` says 20 spreads has 21 in the editor, and `1050` reports "21 spreads are empty": the single first page, 19 full spreads and the single last page.

#### Example response for the Album (trimmed)

```json
{
	"totalPrice": { "value": "154.75", "code": "USD", "total": { "value": "154.75", "code": "USD" } },
	"items": [
		{
			"configuredProductId": "GLW3mbihY3MxZ4PbF",
			"productId": "zqRtQT4NeWnoa9JPq",
			"quantity": 1,
			"selectionsSummary": [
				{ "id": "size", "label": "size", "name": "size", "description": "10×10" },
				{ "id": "spread_count", "label": "spread_count", "name": "spread count", "description": "5 spreads" },
				{ "id": "cover_material", "label": "cover_material", "name": "material", "description": "black premier leather Non-Padded Cover" },
				{ "id": "endleaf_style", "label": "endleaf_style", "name": "Endleaf Style", "description": "Textured White Endleaves" },
				{ "id": "insert_boards", "label": "insert_boards", "name": "Insert Boards", "description": "Thick White Inserts" },
				{ "id": "ba_paper_type", "label": "ba_paper_type", "name": "Paper", "description": "photo lustre paper" }
			],
			"unitPrice": { "value": "154.25", "code": "USD" },
			"totalPrice": { "value": "154.25", "code": "USD" },
			"metadata": {},
			"status": "awaiting-editor",
			"validationSummary": [
				{ "id": 1050, "level": "error", "message": "5 spreads are empty" },
				{ "id": 1051, "level": "warning", "message": "1 tab is unopened" }
			],
			"links": {
				"proof": "https://share-stage.prints.io/e/GLW3mbihY3MxZ4PbF/241d9735",
				"designSpaceProof": "https://share-stage.prints.io/e/GLW3mbihY3MxZ4PbF/241d9735",
				"placementProof": "https://share-stage.prints.io/e/GLW3mbihY3MxZ4PbF/241d9735"
			}
		}
	],
	"actions": {
		"submit": {
			"instructions": "All items are ready. Build a new submission request referencing items[].configuredProductId and call POST /v1/commerce/submissions with a unique Idempotency-Key header to place the order …",
			"url": "https://apis-stage.whcc.com/api/v1/commerce/submissions",
			"method": "POST"
		},
		"calculate": {
			"instructions": "Optional. To see what the order will cost before placing it, call POST actions.calculate.url with the same body you would send to actions.submit.url. …",
			"url": "https://apis-stage.whcc.com/api/v1/commerce/submissions/calculate",
			"method": "POST"
		}
	}
}
```

A create answers `202`, and each item reads `status: "awaiting-editor"`: it exists and is priced, but it still has to be designed. Keep its `configuredProductId`. You use it for the edit link, the price check and the submission. `selectionsSummary[]` shows what was built, including the defaults that filled what you left out and the starting spread count. The price is a snapshot: spreads and options can change in the editor, and the root `totalPrice` can include surcharges that aren't in the item's price, so use the price from [calculate](https://www.whcc.com/developer/docs/guides/albums/#step-6). Its `validationSummary` already says what's missing: `1050` at `level: "error"` counts the empty spreads, `1051` at `level: "warning"` counts the editor tabs nobody has opened yet, and, depending on the add-ons chosen, `1053` says a cover, cameo or combo-cover photo is missing and `1054` says debossing text is missing. All of them are cleared in the editor. The item has no editor link and no `actions` of its own, and the response has no `actions.poll`.

> **Root `actions.submit` doesn't mean ready here.** The create response for an album or book carries `actions.submit` and `actions.calculate` even though nobody has opened the editor yet, and the `submit` instructions say all items are ready. Ignore that. Design it in the editor first, and submit only once it's [finished](https://www.whcc.com/developer/docs/guides/albums/#step-6).

## Step 4: Get the edit link

### POST `/v1/commerce/configured-products/{configuredProductId}/edit-link`

Returns a link that opens one album or book in the Album Editor. [Editor Handoff](https://www.whcc.com/developer/docs/api/editor-handoff/#edit-link) has the request, the redirect rules and the errors; for albums and books, these matter most:

- **One item, one link.** Each album or book has its own editor, so ask for a link, with its own redirects, for each one.
- **`complete` and `cancel` are required.**`complete` is where the editor sends whoever is designing when they finish, and `cancel` is where its back arrow goes. Use `https` for both.
- **Put `%EDITOR_ID%` in the `complete` url.** WHCC replaces it with the item's `configuredProductId`, so `https://yourdomain.com/return?checkout=12345&album=%EDITOR_ID%` tells you which one came back. Add a new one-time token of your own each time you ask for a link, so an old return can't be replayed. If `complete` has no `%EDITOR_ID%`, the response carries a `guidance[]` entry with the code `card.redirect.complete_missing_editor_id_token`. Despite its name, it applies to albums and books too.
- **Six [editor settings](https://www.whcc.com/developer/docs/quick-start/#edit-link-settings) apply.** They're `hidePricing`, `disableUploads`, `productSwitcher`, `sizeSelector`, `addToProject` and `presentationMode`. The other settings the Quick Start lists are accepted and have no effect on an album or book.
- **The link is a credential.** It carries a session token. Don't log it or store it, and ask for a fresh one each time someone opens the editor. A link stops working after 30 days. Each call replaces the redirects stored on the item, so the last call wins, even for a link you were given earlier.
- **An unknown id returns `404`.** So does an id that isn't yours.

```shell
curl -X POST https://apis-stage.whcc.com/api/v1/commerce/configured-products/GLW3mbihY3MxZ4PbF/edit-link \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10" \
	-H "Content-Type: application/json" \
	-d '{
			"redirects": {
				"complete": { "text": "Back to my cart", "url": "https://yourdomain.com/return?checkout=12345&album=%EDITOR_ID%&t=<ONE_TIME_TOKEN>" },
				"cancel": { "text": "Cancel", "url": "https://yourdomain.com/cart?checkout=12345" }
			},
			"settings": { "hidePricing": true }
		}'
```

```json
{
	"actions": {
		"edit": { "url": "https://editor-stage.dragdrop.design/editor/GLW3mbihY3MxZ4PbF?token=…", "method": "GET" }
	}
}
```

If `complete` has no `%EDITOR_ID%`, the same response also carries:

```json
"guidance": [
	{
		"code": "card.redirect.complete_missing_editor_id_token",
		"message": "The redirects.complete url sent with this request contains no per-item marker, so every card or album you send to this url comes back to the same place. …"
	}
]
```

Open `actions.edit.url` in a browser, or send your customer's browser there.

## Step 5: Design it in the editor

The album or book is designed in the Album Editor, and the editor sends the designer back to you. Here's how it goes:

1. **Start with empty spreads.** It opens with its full set of spreads, all empty, and any photos sent in `images[]` waiting in the photo strip. Each empty spread prompts for photos.
2. **Fill the spreads.** Drag photos or designs from the strip, or press **Autofill Spreads**, which places the unused ones into the empty spreads, adding spreads if it needs to, after you confirm. Set the cover by hand.
3. **Clear what `validationSummary` reported.**`1050` clears when a spread has a photo on it, or drops to a warning when you choose **Leave Empty** for that spread. `1053` clears when the empty cover or cameo cell gets a photo. `1054` clears when the debossing text is typed or the debossing removed.
4. **Review and finish.****Review** opens the summary, where the finish button carries your `complete.text`. While anything still needs fixing, including a page or spread count below the product's minimum, the button opens a list of issues and goes to the first one, so an album or book with errors can't be finished.
5. **Land on your `complete` url.** The editor saves the work and sends the browser there with a `GET`, `%EDITOR_ID%` filled in. The back arrow, labelled with your `cancel.text`, goes to your `cancel` url without any checks. Work is saved as it's done, either way.

Finishing sends nothing to WHCC or to you beyond that redirect. If the tab is closed instead, you won't hear from the editor at all, so [check the item](https://www.whcc.com/developer/docs/guides/albums/#step-6) whenever you need to know.

## Step 6: Confirm it's finished and check the price

When the editor comes back to your `complete` url with that item's latest token, record it as finished. Accept each return once: the redirect comes from a browser, so it can arrive again, and only the latest token counts. When you send someone back into a finished item, clear its mark and its price until the editor returns them again. [Editor Handoff](https://www.whcc.com/developer/docs/api/editor-handoff/#finished) has the details. If the editor was left through `cancel` or the tab closed, it isn't finished: ask for a fresh [edit link](https://www.whcc.com/developer/docs/guides/albums/#step-4) and go back in. Then check it with calculate before you submit.

> **A return to your `complete` url isn't proof on its own.** Calculate is the reliable check for an album or book: it reports an unfinished one as not valid for order. Submit only an item that came back from the editor and that calculate reports valid.

### POST `/v1/commerce/submissions/calculate`

Prices the album or book and lists the shipping options for the ship-to address. Send the body you'll submit, as in [Quick Start Step 5](https://www.whcc.com/developer/docs/quick-start/#step-5): `items` and `shipping`, with the address. Don't send an `Idempotency-Key` to calculate.

**Send the address, even for studio shipping.** Calculate accepts a request without `shipping.address`, but then it prices the product only: no shipping, no tax and no destination surcharges, with a `guidance[]` entry saying so. Submit needs the address whatever the `shipping.type`, and without it returns `400` naming `shipping.address`.

```shell
curl https://apis-stage.whcc.com/api/v1/commerce/submissions/calculate \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10" \
	-H "Content-Type: application/json" \
	-d '{
			"items": [
				{ "configuredProductId": "GLW3mbihY3MxZ4PbF" }
			],
			"shipping": {
				"type": "dropship",
				"priority": "dropship_lowest_cost",
				"address": {
					"name": "John Doe",
					"addr1": "3005 Eagandale Place",
					"city": "Eagan",
					"state": "MN",
					"zip": "55121",
					"country": "US"
				}
			}
		}'
```

While an item has an empty spread nobody has marked **Leave Empty**, `validation.isValidForSubmit` is `false`, the item's `isValidForOrder` is `false`, and its `validationSummary` carries `1050` at `level: "error"`. Here is calculate for the Album from Step 3, before anyone opened the editor:

#### Example response (trimmed)

```json
{
	"accountId": "whcc_474284",
	"items": [
		{
			"configuredProductId": "GLW3mbihY3MxZ4PbF",
			"label": "Album",
			"primaryDisplayName": "10×10 Album",
			"quantity": 1,
			"unitPrice": { "value": "154.25", "code": "USD" },
			"totalPrice": { "value": "154.25", "code": "USD" },
			"productId": "zqRtQT4NeWnoa9JPq",
			"isValidForOrder": false,
			"validationSummary": [
				{ "id": 1050, "level": "error", "message": "5 spreads are empty" },
				{ "id": 1051, "level": "warning", "message": "1 tab is unopened" }
			]
		}
	],
	"totalPrice": {
		"value": "178.04",
		"code": "USD",
		"total": { "value": "164.70", "code": "USD" },
		"subtotals": {
			"product": { "value": "154.25", "code": "USD" },
			"packaging": { "label": "", "value": "0.00", "code": "USD" },
			"shipping": { "label": "Expedited", "value": "9.95", "code": "USD" },
			"surcharges": {
				"minimum": null,
				"delivery": { "value": "0.50", "code": "USD" },
				"value": "0.50",
				"code": "USD"
			},
			"discount": null,
			"salesTax": { "value": "13.34", "code": "USD", "isExempt": false }
		}
	},
	"validation": { "isValidForSubmit": false, "isValidDiscount": null },
	"shippingType": "dropship",
	"shippingPriority": "dropship_lowest_cost",
	"options": {
		"shipping": [
			{ "id": "dropship_lowest_cost", "type": "dropship", "priority": "dropship_lowest_cost", "label": "Expedited", "price": { "value": "9.95", "code": "USD" } },
			{ "id": "dropship_one_day_priority", "type": "dropship", "priority": "dropship_one_day_priority", "label": "Priority One-Day", "price": { "value": "14.50", "code": "USD" } }
		]
	}
}
```

A spread marked Leave Empty keeps `1050`, but at `level: "warning"`, which doesn't block ordering. `1051` is a warning too, though the editor asks for every tab to be opened before finishing. Go by the two validity flags, not by whether `1050` is present. Once both are `true`, `totalPrice.value` is the total including tax, and `subtotals` breaks it into product, packaging, shipping, surcharges and tax, as [Responses](https://www.whcc.com/developer/docs/api/responses/#calculate) describes. `surcharges.delivery` is a retail delivery fee that some destinations charge on deliveries, $0.50 in this example. It appears only when the ship-to address calls for it, which is why calculate needs the address to give you the full total. `options.shipping[]` lists every shipping method for the address, priced. Calculate and submit use what the editor saved, so use the price calculate returns, not the one from the create.

If an album or book needs more work, **don't create it again**. A new create makes a new, empty item, and the work already done stays on the old one. Ask for a fresh [edit link](https://www.whcc.com/developer/docs/guides/albums/#step-4) and go back in to finish it.

#### The status read

`GET /v1/commerce/configured-products?ids=…` reports an album or book as `status: "failed"` until it passes every check, with `1050` at `level: "error"` while any spread is empty, and root `actions` holding only `fix`, with no url. That's how an unfinished item reads, including one nobody has opened yet. The `fix` instructions suggest building the item again or asking for an edit link: take the edit link. The read reports it as `ready` once it passes every check.

## Step 7: Submit

> This example submits to the test host, where nothing is produced or billed. The same request sent to `apis.whcc.com` with a live key becomes a real order that WHCC produces, ships and bills you for.

### POST `/v1/commerce/submissions`

Submits the finished album or book for production. Send the same body as Step 6 plus a required `Idempotency-Key` header, exactly as in [Quick Start Step 6](https://www.whcc.com/developer/docs/quick-start/#step-6). Use your checkout ID, or a UUID you save with the checkout before you send, so a retry after a timeout can't place a second order. See [Idempotency](https://www.whcc.com/developer/docs/quick-start/#idempotency).

```shell
curl https://apis-stage.whcc.com/api/v1/commerce/submissions \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10" \
	-H "Content-Type: application/json" \
	-H "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_CHECKOUT_ATTEMPT>" \
	-d '{
			"items": [
				{ "configuredProductId": "GLW3mbihY3MxZ4PbF" }
			],
			"shipping": {
				"type": "dropship",
				"priority": "dropship_lowest_cost",
				"address": {
					"name": "John Doe",
					"addr1": "3005 Eagandale Place",
					"city": "Eagan",
					"state": "MN",
					"zip": "55121",
					"country": "US"
				}
			}
		}'
```

A valid submission answers `202` with the submission's `id`. Save it. Submitting an unfinished album or book is refused, and nothing is placed: WHCC returns `400` with `code: "submission.not_submittable"` and an `invalidParams[]` entry named `items.N.configuredProductId`, with a reason that names the failing check, such as `This configured product isn't valid for ordering: empty-spread.` Get a fresh edit link and go back in. See [Errors](https://www.whcc.com/developer/docs/api/errors/#submission-error-codes).

## Step 8: Follow the order

An album or book follows the same [submission lifecycle](https://www.whcc.com/developer/docs/api/submission-lifecycle/index.html.md) as a print. Create an [event subscription](https://www.whcc.com/developer/docs/api/event-subscriptions/index.html.md) once, when you set up the integration, and WHCC posts `order.accepted`, `order.rejected`, `order.shipped` and `order.cancelled` to your endpoint as each order moves. Don't poll. Match an event to your checkout by its `ConfirmationId`, which is the `confirmationId` on each entry in the submission's `orders[]`.

If a submission fails before any order exists, there's no event, so read the submission once it settles and act on `failed` or `partially_failed`. [Quick Start Step 7](https://www.whcc.com/developer/docs/quick-start/#step-7) shows that read and how to test the event path with a test key.

## If something goes wrong

Albums and books return the same error shapes as every other route; [Errors & Rate Limits](https://www.whcc.com/developer/docs/api/errors/index.html.md) has them all. These are the ones you're most likely to meet.

| When | What WHCC returns | What to do |
| --- | --- | --- |
| Create a product that isn't available in this environment | `400`, `product_not_available` | Use a product the catalog lists. |
| Create with a `designId` | `400`, `designId is not accepted for this product: …` | Leave it out. Design it in the editor. |
| Create with a field the product doesn't publish, such as `spread_count` | `400`, `unknown_selection_field` | Send only the fields in `configuration.fields[]`. Add spreads or pages in the editor. |
| Create with selections that conflict, such as every catalog default | `400` naming the field, with `… can't be combined with the other selections on this product.` | Send the size, and other options only when they're wanted. |
| Create with `redirects` or `content` | `400` naming the key | Send redirects to the edit link. Design the content in the editor. |
| Create more than 20, or mix them with prints, in one request | `400`, nothing created | Split the request. |
| Edit link without `complete` or `cancel`, or with an `http` url | `400` naming `redirects.complete` or `redirects.cancel` | Send both, with `https` urls. |
| Submit an unfinished album or book | `400`, `submission.not_submittable` | Get a fresh edit link and finish it. Don't create it again. |