Customiser labels
Replace the background images
Replaces the customiser's Scene Editor background images, the photographs shoppers preview their sign against, with the list you send, in order.
Overview
For each row send upload_id, a background_image upload
(PNG, JPEG or WebP, at most 2 MiB), or image_url, the URL the labels
read publishes for an image the list already holds. width_cm and
height_cm (or width_in and height_in, with authored_units as on
the read) are the real size the photograph shows. sign_area is where
the sign sits, as fractions of the image from its top-left corner, each
side at least 0.05. linked_size_ids shows the background for those
sizes; a size links to one background only, and at most one row is
is_default_background. mobile is an optional portrait version with
its own image, size and sign area, or null.
Send revision, the labels read's background_images_revision; a
stale one is refused with 409 stale_revision. A write attaches at most
10 new images and holds at most 50 rows. Each upload is single use. An
image the list no longer holds is deleted once the write commits.
Requires customisers:write and an Idempotency-Key. The write clears
the storefront cache; it never regenerates Shopify products.
Authorisation
Bearer token required. Include it in the Authorization header.
Required scope: customisers:write
Path parameters
The customiser id.
Example: 1
Request body
Request body example
{
"revision": 3,
"background_images": [
{
"image_url": "https://cdn.signcustomiser.com/files/brick-wall.jpg"
},
{
"upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
"name": "brick-wall.jpg"
}
]
}curl https://web.signcustomiser.com/api/v3/customisers/1/labels/background-images \
--request PUT \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"revision": 3,
"background_images": [
{
"image_url": "https://cdn.signcustomiser.com/files/brick-wall.jpg"
},
{
"upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
"name": "brick-wall.jpg"
}
]
}'{
"data": {
"object": "customiser_background_images",
"customiser_id": 42,
"revision": 4,
"background_images": [
{
"name": "brick-wall.jpg",
"image_url": "https://cdn.signcustomiser.com/files/brick-wall.jpg",
"width_cm": 152.4,
"height_cm": 101.6,
"sign_area": {
"x": 0.2,
"y": 0.3,
"w": 0.6,
"h": 0.4
},
"linked_size_ids": [
1201
],
"is_default_background": false,
"mobile": {
"image_url": "https://cdn.signcustomiser.com/files/brick-wall-portrait.jpg",
"width_cm": 76.2,
"height_cm": 101.6,
"sign_area": {
"x": 0.1,
"y": 0.3,
"w": 0.8,
"h": 0.3
},
"width_in": 30,
"height_in": 40,
"authored_units": {
"width_cm": "inches",
"height_cm": "inches"
}
},
"width_in": 60,
"height_in": 40,
"authored_units": {
"width_cm": "inches",
"height_cm": "inches"
}
}
]
},
"links": {
"self": "https://web.signcustomiser.com/api/v3/customisers/42/labels/background-images",
"documentation": "https://www.signcustomiser.com/help/api/"
},
"meta": {
"api_version": "v3",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
}{
"type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
"title": "Insufficient scope",
"status": 403,
"code": "insufficient_scope",
"detail": "This operation requires the customisers:write scope.",
"required_scopes": [
"customisers:write"
],
"granted_scopes": [
"customisers:read"
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/stale_revision",
"title": "Stale revision",
"status": 409,
"code": "stale_revision",
"detail": "The background image list revision 3 is stale; the current revision is 4. Read the labels again and retry.",
"errors": [
{
"pointer": "/revision",
"code": "stale_revision",
"detail": "The background image list changed since it was read."
}
],
"expected_revision": 4,
"submitted_revision": 3,
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
"title": "Validation failed",
"status": 422,
"code": "validation_failed",
"detail": "The request body failed validation.",
"errors": [
{
"pointer": "/background_images/0/image_url",
"code": "invalid",
"detail": "The image_url is not an image this list holds. Send a background_image upload_id for a new image."
}
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}