PUT/vendor/products/:id/imagesVendor bearer token required

Replace Product Images

Replace the full image set on a product (multipart/form-data).

What this means in plain English

Replaces all product images in one multipart request. On live (`PUBLISHED` / `HIDDEN`) products, images are staged in `pendingRevision` until admin approval. On draft or pending-approval products, images apply immediately. Requires OWNER, ADMIN, or EDITOR.

When to use this

Syncing product photography from a PIM without touching other catalog fields.
Updating images on a live product without removing it from the storefront.

Path parameters

Name	Type	Required	Description
id	string (UUID)	Yes	Product ID.

Request body

Name	Type	Required	Description
images	file	Yes	One or more image files (same field name `images` for each; jpeg, png, webp, or gif; max 5 MB each).
metadata	string	No	Optional JSON array matching file order: `[{"alt":"front","sortOrder":0,"isPrimary":true},{"alt":"back"}]`.

Request example

curl -X PUT 'https://api.next.gcommerce.glass/api/v1/vendor/products/a0000000-0000-4000-8000-000000000050/images' \
  -d '{
  "images": "front.png"
}'

Response examples

200Success

{
  "id": "550e8400-e29b-41d4-a716-446655440020",
  "name": "Widget Pro",
  "slug": "widget-pro",
  "sku": "WIDGET-001",
  "shortDescription": "Premium widget",
  "warranty": "1 year limited",
  "description": "High-quality widget for industrial use.",
  "pageTitle": "Widget Pro | Jane's Store",
  "pageDescription": "Shop the Widget Pro — durable, lightweight, made in USA.",
  "brand": "Acme",
  "countryOfOrigin": "US",
  "manufacturer": "Acme Corp",
  "leadTime": 3,
  "unspc": "53120000",
  "commodityCode": "12345678",
  "eccn": "EAR99",
  "freeShipping": false,
  "abilityOne": false,
  "madeInUsa": true,
  "greenProduct": false,
  "keyFeatures": ["Durable", "Lightweight"],
  "videos": null,
  "accountCode": "ACC-001",
  "programCode": "PROG-001",
  "resourceCode": "RES-001",
  "status": "PUBLISHED",
  "pendingRevision": {
  "name": "Widget Pro v2",
  "shortDescription": "Updated short description",
  "description": "Updated long description pending review",
  "images": [
    {
      "base64Image": "data:image/png;base64,iVBORw0KGgo...",
      "alt": "Widget Pro v2 front view",
      "sortOrder": 0,
      "isPrimary": true
    }
  ]
},
  "pendingRevisionSubmittedAt": "2026-07-10T14:30:00.000Z",
  "bulkImportJobId": null,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-03-01T08:30:00.000Z",
  "variants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "productId": "550e8400-e29b-41d4-a716-446655440020",
      "sku": "WIDGET-001",
      "upc": "012345678905",
      "unitOfMeasure": "EA",
      "partNumber": "MPN-001",
      "name": "Default",
      "price": "29.99",
      "listPrice": "39.99",
      "vendorPrice": "19.99",
      "weight": "1.50",
      "initialInventory": 100,
      "attributes": { "color": "red" },
      "isActive": true,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-03-01T08:30:00.000Z"
    }
  ],
  "images": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440022",
      "productId": "550e8400-e29b-41d4-a716-446655440020",
      "variantId": null,
      "url": "https://api.next.gcommerce.glass/assets/products/images/550e8400-e29b-41d4-a716-446655440022",
      "alt": "Widget Pro front view",
      "sortOrder": 0,
      "isPrimary": true
    }
  ],
  "documents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440023",
      "productId": "550e8400-e29b-41d4-a716-446655440020",
      "title": "Spec sheet",
      "type": "spec",
      "url": "https://example.com/spec.pdf",
      "document": "https://api.next.gcommerce.glass/assets/products/widget-pro/docs/spec.pdf",
      "size": "245.50",
      "sortOrder": 0,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ],
  "categories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440070",
      "name": "Industrial Supplies",
      "slug": "industrial-supplies"
    }
  ],
  "collections": [],
  "tags": [],
  "facetValues": [],
  "reviews": [],
  "averageRating": 4.5,
  "totalReviews": 12
}

Status codes

200

Request succeeded.

401

Unauthorized

Missing or invalid bearer token.

403

Forbidden

Insufficient permissions for this action.

400

Bad Request

Validation failed or invalid parameters.

404

Not Found

Resource not found.

429

Too Many Requests

Global rate limit exceeded (10,000 requests per 10 minutes per IP).

500

Internal Server Error

Unexpected server error.

403

Forbidden

No vendor membership, or insufficient vendor role (requires OWNER, ADMIN, or EDITOR for write operations).

**Admin approval:** New products are created as `PENDING_APPROVAL` and are not visible on storefronts until a platform admin approves them.

**Live product edits:** On `PUBLISHED` or `HIDDEN` products, changes to `name`, `shortDescription`, `description`, or `images` are staged in `pendingRevision` — the product stays `PUBLISHED` and the storefront keeps showing the current live data until an admin approves.

**Immediate updates:** Vendor price (cost) and MSRP, stock, slug, categories, variants, SEO fields, bulk-update fields, and other non-moderated fields apply immediately on live products without re-approval. The customer retail price (derived from vendor price × commission) also updates immediately.

Do not send a `status` field — it is rejected on vendor REST create/update and managed by the platform.

Poll `GET /vendor/products/:id` and inspect `pendingRevision` (non-null with staged fields). List filters: `?status=PENDING_APPROVAL` (never published), `?hasPendingRevision=true` (live products with staged edits), or `?needsModeration=true` (either case).

This endpoint replaces the entire image list — include every image you want to keep.

Example: `curl -X PUT '{API_ORIGIN}/api/v1/vendor/products/{id}/images' -H "Authorization: Bearer TOKEN" -F "images=@front.png" -F "images=@back.png" -F 'metadata=[{"alt":"front","isPrimary":true},{"alt":"back"}]'`

Prefer this endpoint over PATCH when you only need to update images.

Response `images[].url` values are absolute public asset URLs (`{API_ORIGIN}/assets/…`).

Try it

Edit values below to generate a cURL command. This endpoint requires multipart upload — run in your terminal.

Bearer tokenid *images *metadata

Copy-only

Multipart and file-download endpoints cannot be executed from the browser panel. Copy the cURL command and run it in your terminal.