Editor Handoff

Updated November 13, 2026

Some products need your customer in the WHCC editor before you can order them. They carry completion: "editor" in the catalog. This page covers the handoff they share: getting an edit link, sending your customer to the editor and back, and knowing when they've finished.

What your customer does in the editor depends on the product, and its guide covers that: see Albums & Books. The examples use the test host, https://apis-stage.whcc.com/api.

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

Returns a link that opens one item in the WHCC editor. It's the route in the Quick Start's edit link section. 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. Each is { "text": "...", "url": "https://..." }. complete is where your customer lands after they finish, and cancel is where the editor's back arrow goes. Send a non-empty text: the editor can label its finish button with it.
  • Put %EDITOR_ID% in the path or query string. WHCC replaces it with the item's configuredProductId, so https://yourdomain.com/return?checkout=12345&item=%EDITOR_ID% tells you which item came back. Don't put it in the URL's # fragment, which the editor can rewrite. If complete has no %EDITOR_ID%, the response carries a guidance[] entry with the code card.redirect.complete_missing_editor_id_token.
  • The last call wins. Each call replaces the redirects stored on the item, including for links you asked for earlier.
  • Settings are optional. Send them as the Quick Start's editor settings describe. Each product's guide says which ones apply. An unknown key, or a value that isn't true or false, returns 400.
  • 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 your customer opens the editor. A link stops working after 30 days.
1
2
3
4
5
6
7
8
9
10
11
curl -X POST https://apis-stage.whcc.com/api/v1/commerce/configured-products/<CONFIGURED_PRODUCT_ID>/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&item=%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/<CONFIGURED_PRODUCT_ID>?token=…", "method": "GET" }
	}
}

Send your customer's browser to actions.edit.url.

  • If complete or cancel is missing, WHCC returns 400 with an invalidParams[] entry named redirects.complete or redirects.cancel.
  • If a url isn't https, WHCC returns 400 with <label> must be an https URL.
  • If the id doesn't exist or isn't yours, WHCC returns 404.

Know when it's finished

When your customer finishes, the editor waits for their work and any photo uploads to save, then sends their browser to your complete url with a GET, %EDITOR_ID% filled in. That redirect is the only signal you get. Finishing sends nothing else to WHCC or to you, and if your customer closes the tab, you won't hear from the editor at all.

  • Record it per item. When a request arrives on your complete url, read the item's configuredProductId from the %EDITOR_ID% you put there, and mark that item finished in your checkout. Submit only items you've marked finished.
  • Accept each return once. The redirect comes from your customer's browser, not from WHCC, so anyone can replay it. Add a one-time token of your own to the complete url each time you ask for an edit link, and accept a return only with the latest token for that item in that customer's checkout.
  • Clear it when they go back in. When you send your customer back into a finished item, clear its mark and its price until the editor returns them again.
  • A cancel isn't a finish. If your customer left through cancel or closed the tab, the item isn't finished: ask for a fresh edit link and send them back.

Rely on your own record of the complete redirect. The API's status doesn't tell you that your customer finished in the editor. For an album or book, also check calculate before you submit, as the Albums & Books guide describes.

After the editor

Calculate and submit use what the editor saved, not what you sent to create. Your customer can change selections in the editor, so show them the price and selectionsSummary[] that calculate returns.

If an item needs more work, don't create it again. A new create makes a new, blank item, and the work your customer did stays on the old one. Ask for a fresh edit link and send them back to finish it.

Back to Top πŸ‘†