Bulk Image Import

This API is a pilot. Access is restricted to retailers who have been granted access by bol. If you are not part of the pilot and would like to join, please contact your bol account manager.

The bulk image import pilot allows you to submit a batch of images for an offer and track the processing status of each individual asset. This is useful when you need to import a large number of images for a given offer in one request rather than uploading them one by one.

The pilot exposes two endpoints:

  • Submit a bulk import: submit a list of image URLs to be imported for a specific offer.

  • Get import status: retrieve the processing status of a previously submitted import batch.

Access

Access to this pilot is controlled via a retailer allow-list. Only retailers that have been added to the allow-list can use these endpoints. Requests from retailers that are not on the allow-list will receive a 403 response with problem type /problems/unauthorized.

Media type

All requests to this pilot must use the following media type for both the Content-Type and Accept headers:

application/vnd.retailer.v11-pilot-bulk-image-import+json

Requests that do not carry this media type are rejected.

Submit a bulk import

POST /retailer/offers/{offerId}/image-imports

Submit a list of image assets to be imported for a given offer. The endpoint returns a batchId which you can use to poll the status of each asset.

Path parameters

Parameter Type Description

offerId

UUID

The identifier of the offer for which you want to import images.

Request body

Field Type Required Description

assets

array

Yes

The list of image assets to import. Must contain between 1 and 30 items.

assets[].url

string

Yes

The publicly accessible URL of the image to import.

assets[].labels

array of strings

No

Optional labels to assign to this asset. Supported value: PRIMARY. Use PRIMARY to designate the main product image.
Example request
{
  "assets": [
    { "url": "https://example.com/front.jpg", "labels": ["PRIMARY"] },
    { "url": "https://example.com/side.jpg" }
  ]
}

Response body

Field Type Description

batchId

long

The identifier of the submitted import batch. Use this value to retrieve the processing status via the get import status endpoint.
Example response
{
  "batchId": 42
}

Validation

  • The assets array must contain at least 1 and at most 30 items. Requests outside this range are rejected with a 400 error.

  • Each url must be a publicly accessible URL from which bol can download the image.

Get import status

GET /retailer/offers/{offerId}/image-imports/{batchId}

Retrieve the processing status of a previously submitted import batch. Poll this endpoint after submitting an import to check whether your assets have been processed.

Path parameters

Parameter Type Description

offerId

UUID

The identifier of the offer for which the import was submitted.

batchId

long

The batch identifier returned by the submit import endpoint.

Response body

Field Type Description

batchId

long

The identifier of this import batch.

status

string

The overall status of the batch. See Batch status values.

assets

array

The list of assets in this batch and their individual processing results.

assets[].url

string

The URL of the asset as submitted.

assets[].labels

array of strings

The labels assigned to this asset.

assets[].status

string

The processing status of this individual asset. See Asset status values.

assets[].subStatus

string

An optional code providing more detail on a DECLINED asset (e.g. DOWNLOAD_FAILED_404).

assets[].subStatusDescription

string

A human-readable description of the subStatus.
Example response
{
  "batchId": 42,
  "status": "COMPLETED",
  "assets": [
    {
      "url": "https://example.com/front.jpg",
      "labels": ["PRIMARY"],
      "status": "ACCEPTED"
    },
    {
      "url": "https://example.com/side.jpg",
      "labels": [],
      "status": "DECLINED",
      "subStatus": "DOWNLOAD_FAILED_404",
      "subStatusDescription": "Failed to download image: 404 Not Found."
    }
  ]
}

Batch status values

Value Description

PROCESSING

The batch has been received and one or more assets are still being processed.

COMPLETED

All assets in the batch have been processed. Check each asset’s individual status to see the outcome.

Asset status values

Value Description

PENDING

This asset is queued and has not yet been processed.

ACCEPTED

This asset was successfully downloaded and imported.

DECLINED

This asset could not be imported. Check subStatus and subStatusDescription for the reason.

Error responses

HTTP status Problem type Cause

400 Bad Request

/problems/bad-request

The request is invalid. Common causes: assets array is empty, contains more than 30 items, or the payload is malformed.

401 Unauthorized

—

No valid authentication credentials were provided.

403 Forbidden

/problems/unauthorized

The authenticated retailer is not on the pilot allow-list.

404 Not Found

/problems/not-found

The offer (on submit) or the import batch (on status retrieval) does not exist, or does not belong to the authenticated retailer.