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

Add Product Image

Upload one product image (multipart/form-data).

What this means in plain English

Adds a single image file to a product. On live products the image is staged in pendingRevision until admin approval. Requires OWNER, ADMIN, or EDITOR role.

When to use this

Appending a new photo without replacing the full gallery.
Uploading product photography after create.

Path parameters

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

Request body

Name	Type	Required	Description
file	file	Yes	Image file (jpeg, png, webp, or gif; max 5 MB).
alt	string	No	Alt text (max 255 characters).
sortOrder	integer	No	Sort order.
isPrimary	boolean	No	Send `"true"` to set as primary.

Request example

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

Response examples

201Created

{
  "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": null,
  "pendingRevisionSubmittedAt": null,
  "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).

Example: `curl -X POST '{API_ORIGIN}/api/v1/vendor/products/{id}/images' -H "Authorization: Bearer TOKEN" -F "file=@front.png" -F "alt=Front" -F "isPrimary=true"`

On live products the image is staged in `pendingRevision` until an admin approves.

Response / product `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 *file *altsortOrderisPrimary

Copy-only

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