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, 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 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.
/editorsContent-type: application/json
1
2
3
4
5
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"}}}'
Every product has an editorCompatibility classification, returned by the products call, 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.
Products with editorCompatibility: simpleEditor, such as photo prints, framed prints, metal prints, and canvas wraps. No designId and no selections are required.
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
47
48
49
50
51
52
53
54
55
56
57
58
{
"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
}
}
}
]
}
designIdProducts 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:
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
47
48
49
50
51
52
53
54
55
56
{
"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
}
}
}
]
}
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.
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
{
"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).
designId
string - 255
Only for designed products (cards, ornaments, and designer acrylic blocks): the ID of a design from the designs call. Omit this field for all other products. Passing a designId with a product that does not support designs returns an error.
selections
object
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
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
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.
1
2
3
4
{
"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.
Successful Completion of the editor redirects a user to the specified complete URL.