Product image uploads - OmniCommerce

POST /api/v1/products/{productId}/images stores an image file and adds it to the product’s gallery. It requires catalog:write. To use images that are already online, send their URLs in images on PATCH /api/v1/products/{productId} instead.

Upload an image

Send the file as multipart/form-data in a part named file:

curl -sS -X POST "https://omnicommerce.sg/api/v1/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -F "file=@./front.jpg" \
  -F "position=0"

Field	Description
`file`	Required. JPEG, PNG, WebP, AVIF, or HEIC up to 8 MB. WebP, AVIF, and HEIC are stored as JPEG.
`position`	Zero-based place in the gallery. `0` makes it the main image. Defaults to the end of the gallery.

productId can be a variant UUID to set a variant’s own image. The response is 201 with the stored image and the gallery in order:

{
  "ok": true,
  "data": {
    "image": { "url": "https://…/front.jpg", "position": 0 },
    "images": [
      { "url": "https://…/front.jpg", "position": 0 },
      { "url": "https://…/side.jpg", "position": 1 }
    ]
  }
}

The upload changes the OmniCommerce product and sends a product.updated webhook. Marketplaces get the new gallery the next time you publish: POST /api/v1/products/{productId}/publish.

SDK and CLI

import { readFile } from "node:fs/promises";

await client.products.uploadImage({
  productId,
  file: new File([await readFile("front.jpg")], "front.jpg", {
    type: "image/jpeg",
  }),
  position: 0,
});

with open("front.jpg", "rb") as file:
    client.products.upload_image(product_id=product_id, file=file, position=0)

omni products upload-image --product-id "$PRODUCT_ID" --file ./front.jpg