Skip to main content

Import Media

If you have an external source for your media files like images, you can use the bulk media images endpoint to import images for your products in bulk.

Endpoint​

POST /v2/media/images/bulk

Request body​

[
  {
    "productId": 14733,
    "source": "MyPIM",
    "sourceId": "NCABD70005_1",
    "alt": [
      {
        "language": "EN",
        "value": "Image NCABD70005"
      }
    ],
    "description": [
      {
        "language": "EN",
        "value": "Image of NCABD70005"
      }
    ],
    "tags": [
      {
        "language": "EN",
        "values": ["Product", "front"]
      }
    ],
    "priority": 1,
    "uploadImages": [
      {
        "language": "EN",
        "uploadType": "URL",
        "urlFile": {
          "url": "https://docs.propeller-commerce.com/img/propeller-logo.png",
          "fileName": "NCABD70005_1"
        }
      }
    ]
  }
]

The example URL points at an image on this documentation site, so the request works as it is. In your integration, use the URL of the image in your PIM or media server.

Data fields​

productId: the Propeller product ID of the product you want to add the image(s) to.

source and sourceId: source specifies the origin of the image (for example "MyPIM" or "IMAGE_FTP"). sourceId is the unique identifier of the image in that source system, often the product number followed by _1, _2, _3 etc. See Sources for how source combinations work.

alt, description and tags: localized metadata for the image. These fields accept multiple languages using the standard Localized Strings format, so language codes are uppercase. description and tags are required and need at least one entry. Each alt and description value must be 3 to 255 characters long. The tags field takes an array of separate values per language rather than one comma-separated string.

priority: determines the order in which images are shown. A lower number means a higher priority. An image with priority 1 will be shown before an image with priority 5.

uploadImages: specifies the image URLs per language. Each entry contains:

  • language — the language code
  • uploadType — always URL
  • urlFile — an object with:
    • url — the full URL to the image file. Propeller downloads the image from this URL during the call. When the download fails, that image is reported with success: false and an error such as Image could not be uploaded. Request failed with status code 404, while the call still answers 200
    • fileName — the file name for the image

Response​

Each image in the batch returns a result:

{
  "data": [
    {
      "id": "0826c75d-2e2e-422d-b064-1c2296d5c8e7",
      "key": "NCABD70005_1",
      "lookupKey": "sourceId",
      "action": "update",
      "success": true
    }
  ],
  "messages": ["Completed"],
  "total": 1
}
  • success indicates whether the operation succeeded
  • key is the sourceId of the image
  • id is the Propeller internal media ID (UUID)
  • action is create or update depending on whether the image already existed
  • lookupKey confirms the identifier type used

See also​