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.
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 |
|---|---|---|
| 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.
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://, 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.
/v1/catalog/productsLists 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"
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.
/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.
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":
cover_material with a material cover.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.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.
/v1/commerce/configured-productsCreates 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:
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.content key returns 400.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.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.
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" }
]
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.
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.
/v1/commerce/configured-products/{configuredProductId}/edit-linkReturns 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:
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.%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.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.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.
The album or book is designed in the Album Editor, and the editor sends the designer back to you. Here's how it goes:
images[] waiting in the photo strip. Each empty spread prompts for photos.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.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.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.
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.
/v1/commerce/submissions/calculatePrices 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:
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.
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.
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.
/v1/commerce/submissionsSubmits 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.
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.
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 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. |
Build with our API
Start adding our products into your app today. You don't need to talk to us first. Platforms and individual photographers or studios building for their own business are all welcome. Test API key access is available for every WHCC account. New to WHCC? Create an account first.
Established businesses with existing print volume
Tell us about your business and the partnership you have in mind, and we'll be in touch.
Tell us about your business and the partnership you have in mind, and we'll be in touch.