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 opens it, for whoever is designing.

Four products use the Album Editor. See Albums & Books on whcc.com for sizes, covers and finishes.

Product Catalog ref (the productId you create with) kind
Albumalbumalbum
Layflat Booklayflat-bookbook
Hardcover Bookhardcover-bookbook
Softcover Booksoftcover-bookbook

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 describes, and this guide links there rather than repeating it. Editor Handoff 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 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 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. 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. Ask for limit=200, follow nextCursor to the end, and keep the products whose ref is in the table above, 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.

1
2
3
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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
	"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:

1
2
3
{
	"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 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
	"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:

1
2
3
4
5
6
7
8
9
10
11
12
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. 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.

1
2
3
4
"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)

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
	"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. 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.

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 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 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.
1
2
3
4
5
6
7
8
9
10
11
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 }
		}'
1
2
3
4
5
{
	"actions": {
		"edit": { "url": "https://editor-stage.dragdrop.design/editor/GLW3mbihY3MxZ4PbF?token=…", "method": "GET" }
	}
}

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

1
2
3
4
5
6
"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 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 has the details. If the editor was left through cancel or the tab closed, it isn't finished: ask for a fresh edit link 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: 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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)

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
	"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 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 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. 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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.

Step 8: Follow the order

An album or book follows the same submission lifecycle as a print. Create an event subscription 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 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 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 environment400, product_not_availableUse a product the catalog lists.
Create with a designId400, 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_count400, unknown_selection_fieldSend only the fields in configuration.fields[]. Add spreads or pages in the editor.
Create with selections that conflict, such as every catalog default400 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 content400 naming the keySend redirects to the edit link. Design the content in the editor.
Create more than 20, or mix them with prints, in one request400, nothing createdSplit the request.
Edit link without complete or cancel, or with an http url400 naming redirects.complete or redirects.cancelSend both, with https urls.
Submit an unfinished album or book400, submission.not_submittableGet a fresh edit link and finish it. Don't create it again.
Back to Top πŸ‘†