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

- Source URL: https://www.signcustomiser.com/help/api/v3-put-replace-the-background-images/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-put-replace-the-background-images.md
- Group: Customiser labels
- OpenAPI for this group: https://www.signcustomiser.com/help/openapi/customiser-labels.json
- Method: PUT
- Path: /api/v3/customisers/{customiser_id}/labels/background-images
- Auth: Bearer token
- Required scopes: `customisers:write`

## Path parameters

- customiser_id (string, required): The customiser id. Example: 1

## Body parameters

- revision (integer, optional): No description provided.
- background_images (array, optional): No description provided.

## Request body example

```json
{
  "revision": 3,
  "background_images": [
    {
      "image_url": "https://cdn.signcustomiser.com/files/brick-wall.jpg"
    },
    {
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
      "name": "brick-wall.jpg"
    }
  ]
}
```

## cURL example

```bash
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 examples

### 200 PUT 200 example 1

```json
{
  "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"
  }
}
```

### 403 Insufficient scope

```json
{
  "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"
}
```

### 409 Stale revision

```json
{
  "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"
}
```

### 422 Unknown image

```json
{
  "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"
}
```
