Sign Customiser

Navigation

Dark mode

Replaces the customiser's Scene Editor background images, the photographs shoppers preview their sign against, with the list you send, in order.

PUT/api/v3/customisers/{customiser_id}/labels/background-images
PUTReplace the background images
PUT/api/v3/customisers/{customiser_id}/labels/background-images

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. 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

The Authorization header expects a Bearer token. Generate one on the API keys page in your dashboard.

Path

The customiser id.

Body
Replace the background images

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

customiser_idstringpathrequired

The customiser id.

Example: 1

Request body

revisionintegerbody
background_imagesarraybody

Request body example

application/json
{
  "revision": 3,
  "background_images": [
    {
      "image_url": "https://cdn.signcustomiser.com/files/brick-wall.jpg"
    },
    {
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
      "name": "brick-wall.jpg"
    }
  ]
}
Replace the background images
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"
    }
  ]
}'
Response
{
  "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 a question and press Enter. Use the arrow keys to move between the results.