Skip to main content
Product images live in the project’s media library. A file is stored once, as an asset, and products show it by linking to it. This page explains that model, the two ways to get a file into the library, and how to control which images a product shows and in which order.

How media is modelled

An asset response describes the file and where it is used:
  • url is the durable path of the file, relative to the WISEPIM app origin. It looks like /api/portal-assets/<token>. Store it as returned. The token in the example is shortened.
  • To download the file, prefix the path with https://wisepim.com. No API key is needed: the token in the path grants read access and redirects to a short-lived storage URL. Treat the path like a public link. thumbnail_url is the same token with ?rendition=thumbnail.
  • source_url is set when the asset was imported from a URL.
  • products lists at most 100 products, ordered by position. products_truncated is true when the asset may be attached to more products than are listed.
main_image is read-only on product writes. Sending it to POST /products, PATCH /products/{product_id} or POST /products/batch is a 422, because the field is not part of the writable schema. Change the main image with the media routes on this page. Every product whose images change gets a new version and updated_at, so an incremental sync with updated_since picks it up.

Endpoints and scopes

Media uses three scopes. Reading needs assets:read. Everything that adds files or changes a product’s images needs assets:write. Only removing a file from the library needs assets:delete. See the scope catalog.
Give a sync integration assets:write but not assets:delete. It can then attach, reorder and detach images, but it cannot remove a file that other products, or people working in the app, still use.

Import an image from a URL

Use this when your images are already reachable on a public web address, such as a CDN or your current storefront. WISEPIM downloads the file in the background, so the request returns quickly and you poll for the result.
1

Register the import

Name the product with product_id or sku. Send exactly one of them.
The response is 202 Accepted with an import receipt, not an asset. Nothing has been downloaded yet.
2

Poll until it settles

Call GET /asset-imports/{import_id} until status is linked or failed. The status moves through pending, processing, then linked or failed.
When status is linked, asset_id holds the new asset’s UUID and the image is attached to the product. When it is failed, error explains why, for example an HTTP error from your server or an unsupported content type.
3

Add alt text

The import does not accept alt text. Sending alt_text, or any other field the route does not list, is a 422 validation error with a per-field detail; it is not ignored. Once the import is linked, set alt text on the asset with PATCH /assets/{asset_id}. See Alt text.

Rules for the download

The download runs behind the same safety guard as every WISEPIM image import:
  • Only http and https addresses on public hosts. Private, local and internal addresses are refused, and the check runs again on every redirect.
  • A URL that is not a public http(s) address, or that contains credentials, is refused up front with 422 invalid_url. URLs are limited to 2,000 characters.
  • Only image content is accepted. HTML pages, PDFs and other types fail the import.
  • At most 25 MB per file.
  • WISEPIM asks for the file uncompressed. If your server answers with a Content-Encoding other than identity (for example gzip), the import fails. Serve images without transfer compression.

Placement and repeats

  • position places the image among the product’s images. When you omit it, the image goes after the product’s current images, counting imports that are still pending.
  • is_main: true puts the image first, so it becomes the main_image once it lands. It takes precedence over position, and the product’s other images move one place back.
  • A URL is stored once per project. Importing the same URL again does not create a second copy of the file. If an import of that URL for that product is still pending, the latest request decides its position.
  • URL imports are not jobs. They do not appear under GET /jobs. GET /asset-imports lists them, including imports started by connectors and the web app.

Upload a file

Use an upload when the file is not on a public address, for example an export from a private DAM or a file on your own server. POST /assets/upload takes multipart/form-data and stores the file in the same request.
  • The file’s content decides its type, not its name or the declared Content-Type. A renamed text file is refused with 422 unsupported_file_type. An empty file is 422 empty_file.
  • The whole request body is limited to 10 MiB. A larger request is refused with 413 payload_too_large before anything is stored. For bigger images, use a URL import (25 MB).
  • The same bytes are stored once per project. Uploading a file that is already in the library returns the existing asset with 200 instead of 201, so a retried upload never creates a duplicate. If you named a product, the file is still attached to it.
  • With an Idempotency-Key, the upload is identified by the file’s content hash, its file name and the form fields. A retry of the same upload with the same key replays the original response. The same key with a different file or different fields is 409 idempotency_conflict.
  • The response is the asset. When you named a product, that product’s entry is listed first in products.

Alt text

Alt text describes an image for screen readers and search engines, and exports read it from the asset. Set it with PATCH /assets/{asset_id}, either as one text for every language:
or as a map of locale to text:
  • Each text is at most 500 characters, and a map holds at most 100 locales. Locale keys look like en, nl-NL or pt_BR.
  • Send null or an empty value to clear the alt text. Empty entries in a map are dropped.
  • A map replaces the whole previous value. To change one language, send the full map.
  • Channels receive the text for their locale, falling back to the same language.
  • Alt text belongs to the asset, so it applies on every product that shows the asset. Each of those products gets a new version.

Manage a product’s images

These routes change which assets a product shows and in which order. Each one, except detach, returns the product’s images in order together with its main_image:

Attach an existing asset

POST /products/{product_id}/assets attaches an asset that is already in the library. It goes after the product’s current images unless you send position. is_main: true also makes it the main image.
The response is 201 when the asset was attached, or 200 when it was already attached. A product’s first image becomes its main_image.

Move one image

PATCH /products/{product_id}/assets/{asset_id} changes one image’s position. Two images on the same position keep the order they were attached in.

Set the full order

PUT /products/{product_id}/asset-order is the clearest way to make a product match an external order. Positions become 0, 1, 2 and so on, and the first asset becomes the main_image.
asset_ids must name every asset attached to the product exactly once, with at least 1 and at most 1,000 entries. A list that does not match is 422 invalid_order, and the error lists missing_asset_ids and unknown_asset_ids so you can see what differs. Each of those lists shows at most 200 ids, so on a large product the difference may be partial. An empty list fails schema validation before that check, so a product with no images cannot be reordered. This route only orders; it does not attach or detach.

Choose the main image

PUT /products/{product_id}/main-asset makes one image the main image. It moves to the front of the product’s images.
The asset does not have to be attached to the product yet, so a variant can take one of its parent’s photos in one call. Only images qualify: a PDF is 422 not_an_image.

Detach an image

DELETE /products/{product_id}/assets/{asset_id} removes the asset from this product only. It returns 204 with no body. The asset stays in the library and on other products. The product’s next image becomes its main_image, or it has none when no image is left. Detaching needs assets:write.
An asset that is not attached to the product is 404 not_found.

Positions

position is an integer from 0 to 1,000,000. Lower comes first. A value outside that range is a 422 (invalid_position on an upload, a schema validation error on the JSON routes). Positions do not have to be consecutive; use the reorder route when you want them renumbered.

Delete an asset

DELETE /assets/{asset_id} removes the file from the media library and from every product it is attached to. Each of those products falls back to its next image as main_image, gets a new version, and channels stop receiving the image. It returns 204 and needs assets:delete.
Delete is library-wide. To remove an image from one product, detach it instead. Check products and products_truncated on the asset before you delete it.
Filter the library by product to get every image of that product:
  • The list is keyset-paged like every other list (limit up to 200, then next_cursor), ordered by asset id. It is not ordered by position.
  • For each asset, the requested product’s entry is always listed first in products, even when the asset is shared by more than 100 products. Read products[0].position and products[0].is_main and sort by position to rebuild the gallery.
  • An unknown product_id returns an empty list, not a 404.
  • The product’s own main_image is on GET /products/{product_id}.
  • Images added before the media library existed can show on a product, and in its main_image, without being listed by GET /assets. You cannot reorder or detach them through these routes. Re-import them to manage them here.

Recipe: migrate a product’s images from your old PIM

This recipe moves the image gallery of each product, keeps the old order, and sets per-locale alt text. It is safe to run again after a failure.
1

Create a key with the right scopes

The migration needs products:read to resolve SKUs to product ids, assets:read to poll and verify, and assets:write to import and order. It does not need assets:delete.
2

Resolve SKUs to product ids

The import routes accept a sku, but reading a gallery and setting its order take a numeric product_id. Call GET /products?skus=TEE-ORG-NAVY-M,TEE-ORG-NAVY-L (up to 200 SKUs per call) and keep each product’s id. Each import receipt also carries the product_id.
3

Check what the product already has

Call GET /assets?product_id=. If the product already shows images, decide whether to keep them. New imports without a position go after them. Images added before the media library existed are not listed here, even though the product may show them; compare with main_image on GET /products/{product_id}.
4

Register one import per image, in the old order

For each image, call POST /assets with the product’s sku, the image URL and position set to its index in the old PIM (0 for the old main image). Use an Idempotency-Key derived from SKU and index, such as img-TEE-ORG-NAVY-M-0, so a rerun replays instead of registering twice.If an image is behind a login on the old system, download it yourself and send it to POST /assets/upload with the same sku and position.
5

Wait for the imports to settle

Poll GET /asset-imports?product_id=8841, or each receipt’s GET /asset-imports/{import_id}, with a backoff. Collect asset_id from every linked import and record every failed one with its error.
6

Set alt text

For each asset_id, call PATCH /assets/{asset_id} with the old PIM’s alt text as a locale map.
7

Verify and fix the order

Read GET /assets?product_id= and sort by the product’s position. If the order is not what you expect, for example because some images were already attached, send the complete order with PUT /products/{product_id}/asset-order. The first asset in that list becomes the main_image.
8

Retry the failures

Fix the cause shown in error (a 404 on the old CDN, an HTML login page, a compressed response) and register those URLs again with new idempotency keys.
Share one file across products by importing or uploading it once and then attaching the returned asset_id to the other products with POST /products/{product_id}/assets. Importing the same URL for each product also works, because a URL is stored once per project.

Gotchas

  • Asset ids are UUIDs, but URL import ids (/asset-imports/{import_id}) are integers.
  • A URL import returns a receipt, not an asset. asset_id is only set once the import is linked.
  • is_main on a URL import shifts the product’s other images back by one, including imports that are still pending.
  • Retries replay the stored response. A retry with the same Idempotency-Key returns the original response even if the product has changed or the URL’s DNS has changed since.
  • Product writes cannot set images. main_image and file or image attribute values are not writable on product writes. Use the media routes.
  • Older images can be invisible to these routes. Images added before the media library existed may show on a product without being listed by GET /assets, so you cannot reorder or detach them here. Re-import them to manage them.
  • Request bodies are closed. A field the route does not list, such as alt_text on POST /assets or is_main on the move route, is a 422, not ignored.

Common errors

A URL import that fails after the 202 does not return an error status. Its receipt has status: "failed" and an error text.

Products and variants

Create products and variants before attaching their images.

Imports and exports

Move whole catalogs as files, including image columns.

Webhooks

Get notified when products change instead of polling.

Authentication and scopes

Which scopes exist and how to create a key that carries them.