> Part of [WHCC Developer Documentation](https://www.whcc.com/developer/llms.txt) # Creating an Editor Version 1.0 · Updated 2026-09-03 Creating an editor is the core call of the Editor API, and it is simple: POST a small JSON object with your user's chosen [product](https://www.whcc.com/developer/docs/editor-api/products/index.html.md), and the response is a URL that opens their editor session. Everything around that call is yours: your own UI handles product selection before it, and your redirect URLs direct the user after it. Most integrations make the call server side and redirect immediately, so the editor feels like part of your app. If you have your own product UI, an editor can also be created and completed headlessly for many products, without the customer ever opening the editor URL. Reach out for details on that path. > **Designs apply only to some products** such as cards, ornaments, and designer acrylic blocks. Other products like prints, wall art, albums, and books etc do not have designs. For products that do not have designs, you will create the editor with a `productId` alone and omit `designId` entirely. Including a `designId` with a product that does not support designs returns an error. > The `userId` property in the payload needs to match the `accountId` claim used when requesting your access token (See: [Authentication](https://www.whcc.com/developer/docs/editor-api/authentication/index.html.md) for more information). In most integrations, all editors and orders run through a single top-level account, usually your own, and `userId` is simply your own identifier for the user you're redirecting into the editor. ## POST `/editors` Content-type: application/json ## curl ### CURL Example Request ```shell curl https://prospector.dragdrop.design/api/v1/editors \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.r3udhowqndkwqneoiqwndjwndei12u390912hrbfhaslkdjbqwiei21nbrhewiuornqwjkfhbaiwodnqwjkbdawuosdhowqubdfjkwbdusandbiwquebio12nedbwbaodpqwnebou12rbwkjalndawuobdnwqndfqwbdfoiwqndpiqwhfiwqnkjdlnwqdnioqwhniorqw3nfjwbaodnwdnqwopd" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"userId":"{{accountId}}","productId":"uLSWZLZzEWY5KWr9z","redirects":{"complete":{"text":"Checkout","url":"https://yourdomain.com/return"},"cancel":{"text":"Cancel","url":"https://yourdomain.com/cancel"}}}' ``` ### Example Request Payloads by editor type Every product has an `editorCompatibility` classification, returned by the [products call](https://www.whcc.com/developer/docs/editor-api/products/index.html.md), that determines which editor the session opens and which create-time fields apply. The three examples below show a typical create call for each editor type. #### Simple Editor: prints and wall art Products with `editorCompatibility: simpleEditor`, such as photo prints, framed prints, metal prints, and canvas wraps. No `designId` and no `selections` are required. ```json { "userId": "{{accountId}}", "productId": "uLSWZLZzEWY5KWr9z", "redirects": { "complete": { "text": "Checkout", "url": "https://yourdomain.com/return?editor=%EDITOR_ID%" }, "cancel": { "text": "Cancel", "url": "https://yourdomain.com/cancel" } }, "settings": { "quantity": { "default": 1 }, "client": { "vendor": "default", "accentColor": "#ff0000", "hidePricing": false, "disableUploads": false, "markupType": "PERCENT", "markupAmount": 30 }, "controls": { "productSwitcher": "enabled", "sizeSelector": "enabled" } }, "photos": [ { "id": "1", "name": "Photo IMG_1", "url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_1.jpg", "printUrl": "https://s3.amazonaws.com/test-bucket-whoa/nonwatermarkedimage.jpg", "filetype": "jpg", "size": { "original": { "width": 3600, "height": 2401 } } }, { "id": "2", "name": "Photo IMG_2", "url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_2.jpg", "filetype": "jpg", "size": { "original": { "width": 2400, "height": 3600 } } } ] } ``` #### Card Editor: designed products, adding a `designId` Products with `editorCompatibility: cardEditor` are the designed products: cards, ornaments, and designer acrylic blocks. For these, also pass the `designId` of a design from the [designs call](https://www.whcc.com/developer/docs/editor-api/designs/index.html.md): ```json { "userId": "{{accountId}}", "productId": "YeEEATumTpKCv3dcz", "designId": "K5zXncofXrAu9f4uN", "redirects": { "complete": { "text": "Checkout", "url": "https://yourdomain.com/return?editor=%EDITOR_ID%" }, "cancel": { "text": "Change Design", "url": "https://yourdomain.com/cancel" } }, "settings": { "quantity": { "default": 25 }, "client": { "vendor": "default", "accentColor": "#ff0000", "studioName": "Sample Studio", "hidePricing": false, "disableUploads": false, "markupType": "PERCENT", "markupAmount": 30 } }, "photos": [ { "id": "1", "name": "Photo IMG_1", "url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_1.jpg", "printUrl": "https://s3.amazonaws.com/test-bucket-whoa/nonwatermarkedimage.jpg", "filetype": "jpg", "size": { "original": { "width": 3600, "height": 2401 } } }, { "id": "2", "name": "Photo IMG_2", "url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_2.jpg", "filetype": "jpg", "size": { "original": { "width": 2400, "height": 3600 } } } ] } ``` #### Album Editor: Albums and Books, setting the spread count Products with `editorCompatibility: albumEditor` are Albums and Books. They do not take a `designId`. The album editor provides the design functionality, and the size of the book is set with a `spread_count` in `selections`. If `spread_count` is omitted, the album defaults to the product's default page count. Albums require a minimum `spread_count` of 5; Layflat Books and Hardcover Books require a minimum of 10. ```json { "userId": "{{accountId}}", "productId": "qfouMijJRwiMAfW9W", "selections": { "spread_count": 5 }, "redirects": { "complete": { "text": "Checkout", "url": "https://yourdomain.com/return?editor=%EDITOR_ID%" }, "cancel": { "text": "Cancel", "url": "https://yourdomain.com/cancel" } }, "photos": [ { "id": "1", "name": "Photo IMG_1", "url": "https://s3.amazonaws.com/test-bucket-whoa/IMG_1.jpg", "filetype": "jpg", "size": { "original": { "width": 3600, "height": 2401 } } } ] } ``` - **`userId`** (string - 255): An internally used ID that's specific to the user you're redirecting into the editor. This value is based on whatever you use to identify who is creating this editor. Your Key combined with your userId is what we use to tie an individual user to just their editors. So if you create multiple editor sessions with the same value that user will be able to load all of them simultaneously, but no one else will be able to load those editors, without being passed into them with the appropriate JSON Web Token (JWT). - **`productId`** (string - 255): The ID of a product that is able to be edited (from a [products call](https://www.whcc.com/developer/docs/editor-api/products/index.html.md)). - **`designId`** (string - 255, optional): Only for designed products (cards, ornaments, and designer acrylic blocks): the ID of a design from the [designs call](https://www.whcc.com/developer/docs/editor-api/designs/index.html.md). Omit this field for all other products. Passing a `designId` with a product that does not support designs returns an error. - **`selections`** (object, optional): Initial selections for the editor session, as attribute category and attribute ID pairs. Anything not specified starts at the product's defaults. For Albums and Books, `spread_count` sets the number of spreads in the book. - **`redirects`** (array): A set of routes that you'd like your user sent to if they leave the editor. A key value of **complete** is where a user is sent when they leave the editor via completing their design and choosing to purchase it, this URL is requested containing a payload of what the end outcome of their editor session was. A key value of **cancel** is where a user is sent when they click the back or cancel action inside the editor. They are returned without an end output, because they abandoned the design work they did inside the editor. - **`url`** (string): The URL you'd like them to be sent to. This URL can contain the placeholder value of `%EDITOR_ID%`, which will be dynamically replaced by the `editorId` for the session. - **`text`** (string): The text they should see in the editor UI when completing that action (for example if you're sending them right to Checkout, versus to a Proofing related stage). - **`settings`** (array, optional): Settings to modify and customize your editor experience. All settings are expected to be present on the initial editor create call. They configure the editor session itself, and there is currently no partner-facing way to change them after the session is created. - **`quantity`** (string - 255): Items related to the quantity of items that can be ordered. - **`default`** (int): Provides the ability to specify the default qty of an editor. - **`client`** (string - 255): Options tied to customize the look and functionality of the editor - **`vendor`** (string): The visual theme used for display. The string `default` will use the brand-specific accent color created when provisioning your credentials. - **`accentColor`** (string): A hex color value used as an accent inside the editor. We dynamically determine buttons and actions based on this color, and attempt to optimize contrast, so even light color values should result in a positive user experience. - **`studioName`** (string): Only relevant for card designs. Every card design our designers have created has a spot for studio branding on the back of the card. This will affect two things in the editor, the ability to pre-populate that text field with a brand name or allow a user to dynamically edit it. No other products use this field, not even other designed products like ornaments or designer acrylic blocks. - **`hidePricing`** (bool): If set to true all pricing in the editor will be hidden. - **`disableUploads`** (bool): If set to true, the user cannot upload their own photos inside the editor and can only work with the assets you provide in the `photos` array. Useful when your integration owns the image workflow and the editor should not accept new uploads. - **`markupType`** (string): Apply a pricing markup to the prices inside the editor, the only supported value is `PERCENT`. - **`markupAmount`** (int - 3): The percentage amount (a positive integer) you'd like to markup, requires also passing `markupType: PERCENT`. - **`controls`** (object): Feature controls that turn individual editor UI capabilities on or off for the session. Each control takes the string value `enabled` or `disabled`, and any control not specified defaults to `enabled`. Use these when your integration wants additional control over the user's experience within the editor UI. - **`productSwitcher`** (string): Whether the user can change their product from within the editor session. In the Simple Editor this is a top-level selection that lists the available products (based on what is in the assigned org) and lets the user select a new one. In the Album Editor it lets the user click the product title to change an Album to a Layflat Book or a Layflat Book to an Album. When `disabled`, the user will not see the selection, and in the Album Editor the product name is not clickable. Not applicable to the Card Editor at this time. - **`sizeSelector`** (string): Whether the user can change their product's size from within the editor session, with an interaction similar to `productSwitcher`. Valid for Simple Editors and Album Editors, but not for Card Editors at this time. - **`photos`** (object, optional): An object that pre-populates the photo gallery inside the editor with assets provided. Currently JPEG and PNG assets are supported. - **`id`** (string - 255): The unique id to refer to this photo. - **`name`** (string - 255): The unique name to refer to this photo. - **`url`** (string): Publicly accessible file path to get at an image asset to be used in the editor (sometimes watermarked or a smaller version of the image) - **`printUrl`** (string): Publicly accessible file path to get the image asset you want to print with (same aspect ratio as url needed) - **`filetype`** (string): A value of either "jpg" or "png" - **`size`** (array): Pass in the key of "original" to denote the aspect ratio of your file. - **`width`** (int): Value in pixels representing the width of the image asset. - **`height`** (int): Value in pixels representing the height of the image asset. ### Example Response ```json { "editorId": "2321ej2101293a4e57cdf605", "url": "https://www.dragdrop.design/editor/2321ej2101293a4e57cdf605?token=3h2ebaksndohe2o1nen2jkeVCJ9.eyJjbGllbnRLZXlJZCI6InJFMnVlbU1tOGV3ZVFMa243IiwidXNlcklkIjoiMTAwMDEtdGVzdCIsInByb2R1Y3RJZCI6ImI3alc3UG1zZkJ5b1N4UTVtIiwiZGVzaWduSWQiOiJ6dFJNRGlIdXA4b29GaHhMciIsImlzcyI6InBpY2theGUiLC2ebwqhdowqjdnwqjdjkwndw0100218uead0xzUVc5S0ZvR3VaNnR5IiwiZXhwIjoxNTM1MTY2NjM5OTMyfQ.bVnY1DmC9JZYQRklIlCaqusd90109eujnwdnjalXwMtXN4KezaR2-NLpOBIs" } ``` - **`editorId`** (string - 64): A unique identifier of the editor session. - **`url`** (string): The path you redirect your user to for them to start editing. > ## What's Next > > Successful [Completion](https://www.whcc.com/developer/docs/editor-api/complete/index.html.md) of the editor redirects a user to the specified `complete` URL.