Admin Images API — Attach Product and Variant Images

The Admin Images API manages the visual media for your catalog. Because the platform uses ImageKit as its CDN, your workflow is always the same: first upload the image directly to ImageKit using a signed authentication token from the API, then register the resulting URL against a product or variant. The API controls display ordering, primary image promotion, and clean-up on deletion so you never need to manage those constraints manually.

All image endpoints require an authenticated session with the ADMIN or SUPER_ADMIN role. Include the x-csrf-token header on all POST, PATCH, and DELETE requests.

ImageKit Upload Workflow

Before attaching any image, you must upload the file to ImageKit and obtain a hosted URL. The API provides a dedicated endpoint that issues short-lived signed credentials for direct browser or server-side uploads.

Get signed ImageKit credentials

Call GET /admin/products/uploads/imagekit-auth to retrieve a set of signed upload parameters. No query parameters are needed — the folder is fixed server-side for admin uploads.

curl -X GET https://api.example.com/api/v1/admin/products/uploads/imagekit-auth \
  -H "Cookie: session=<your-session-cookie>"

Response:

{
  "success": true,
  "data": {
    "token": "ik_upload_token_abc123",
    "expire": 1717228800,
    "signature": "sha1_signature_string",
    "publicKey": "public_ik_key",
    "urlEndpoint": "https://ik.imagekit.io/yourstore",
    "folder": "/products"
  }
}

Upload the image to ImageKit

Use the ImageKit SDK or a direct multipart form POST to upload the file to ImageKit using the credentials from the previous step. ImageKit returns a hosted URL for your uploaded file.

import ImageKit from 'imagekit';

const imagekit = new ImageKit({
  publicKey: data.publicKey,
  urlEndpoint: data.urlEndpoint,
});

const uploadResult = await imagekit.upload({
  file: fileBuffer,           // Buffer or base64 string
  fileName: 'runner-sneaker-front.jpg',
  folder: data.folder,
  token: data.token,
  expire: data.expire,
  signature: data.signature,
});

const hostedUrl = uploadResult.url;
// e.g. "https://ik.imagekit.io/yourstore/products/runner-sneaker-front.jpg"

Once you have the hosted ImageKit URL, call POST /admin/products/{product_public_id}/images (or the variant images endpoint) to attach it to the catalog record.

curl -X POST \
  https://api.example.com/api/v1/admin/products/prd_01H/images \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "image_url": "https://ik.imagekit.io/yourstore/products/runner-sneaker-front.jpg",
    "alt_text": "Runner Sneaker – front view",
    "display_order": 0,
    "is_primary": true
  }'

display_order controls the sort position in the product gallery. Lower values appear first. Set display_order: 0 for the hero image and increment subsequent images by 10 to leave room for future inserts without a full re-order.

Product Images

List Product Images

Retrieve a paginated list of images attached to a product, ordered by display_order ascending.

GET /admin/products/{product_public_id}/images

Path Parameters

string

required

The product’s public ID, prefixed prd_.

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Items per page. Accepted range: 1–100.

Response

array

Ordered array of product image objects.

Show Product image fields

string

Image public ID, prefixed pimg_.

string

Fully qualified ImageKit URL.

string | null

Accessibility alt text, or null.

integer

Zero-based sort index within the product gallery.

boolean

Whether this image is the product’s primary (thumbnail) image.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-updated timestamp.

Attach Product Image

Register a hosted ImageKit URL as a product image. image_url is the only required field. The API validates the URL host against an allowlist and enforces the one-primary constraint.

POST /admin/products/{product_public_id}/images

Path Parameters

string

required

The product’s public ID, prefixed prd_.

Request Body

string

required

Fully qualified https:// URL to an image hosted on ImageKit. Maximum 2048 characters.

string

Descriptive alt text for accessibility. Maximum 255 characters. Optional.

integer

Zero-based gallery sort position. Defaults to appending at the end. Must be ≥ 0.

boolean

If true, this image becomes the product’s primary image and any existing primary is demoted. If this is the first image attached to the product, it is automatically set as primary regardless of this value.

Every product maintains exactly one primary image at all times. Setting is_primary: true on a new or existing image atomically promotes it and demotes the previously primary image. You cannot have zero primary images on a product that has at least one image attached.

Example

curl -X POST \
  https://api.example.com/api/v1/admin/products/prd_01H/images \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "image_url": "https://ik.imagekit.io/yourstore/products/runner-front.jpg",
    "alt_text": "Runner Sneaker front view",
    "display_order": 0,
    "is_primary": true
  }'

const response = await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/images',
  {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'x-csrf-token': csrfToken,
    },
    body: JSON.stringify({
      image_url: 'https://ik.imagekit.io/yourstore/products/runner-front.jpg',
      alt_text: 'Runner Sneaker front view',
      display_order: 0,
      is_primary: true,
    }),
  }
);

201 Response

{
  "success": true,
  "data": {
    "public_id": "pimg_01H",
    "image_url": "https://ik.imagekit.io/yourstore/products/runner-front.jpg",
    "alt_text": "Runner Sneaker front view",
    "display_order": 0,
    "is_primary": true,
    "created_at": "2024-06-01T09:10:00.000Z",
    "updated_at": "2024-06-01T09:10:00.000Z"
  }
}

Get Product Image

Fetch a single product image by its public ID.

GET /admin/products/{product_public_id}/images/{image_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

string

required

The image’s public ID, prefixed pimg_.

Update Product Image

Partially update a product image. Supply any combination of image_url, alt_text, display_order, and is_primary. At least one field is required.

PATCH /admin/products/{product_public_id}/images/{image_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

string

required

The image’s public ID, prefixed pimg_.

Request Body

string

Replacement ImageKit URL. Maximum 2048 characters.

string | null

Updated alt text. Pass null to clear.

integer

Updated sort position. Must be ≥ 0.

boolean

Promote this image to primary. The current primary is automatically demoted.

Delete Product Image

Delete a product image. If the deleted image was the primary, the API automatically promotes the next-lowest display_order image to primary so the constraint is never violated. Returns 204 No Content on success.

DELETE /admin/products/{product_public_id}/images/{image_public_id}

Path Parameters

string

required

The product’s public ID, prefixed prd_.

string

required

The image’s public ID, prefixed pimg_.

Example

curl -X DELETE \
  https://api.example.com/api/v1/admin/products/prd_01H/images/pimg_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/images/pimg_01H',
  {
    method: 'DELETE',
    credentials: 'include',
    headers: { 'x-csrf-token': csrfToken },
  }
);

Variant Images

Variant images show color- or configuration-specific photos. They follow the same upload workflow as product images but have no is_primary field — the full set of a variant’s images is displayed in order.

List Variant Images

Retrieve paginated images for a specific variant.

GET /admin/products/{product_public_id}/variants/{variant_public_id}/images

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

Query Parameters

integer

default:"1"

Page number.

integer

default:"20"

Items per page. Accepted range: 1–100.

Attach Variant Image

POST /admin/products/{product_public_id}/variants/{variant_public_id}/images

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

Request Body

string

required

Fully qualified ImageKit URL. Maximum 2048 characters.

string

Accessibility alt text. Maximum 255 characters. Optional.

integer

Zero-based gallery sort position. Must be ≥ 0. Optional.

Example

curl -X POST \
  https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H/images \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "image_url": "https://ik.imagekit.io/yourstore/variants/runner-black-42.jpg",
    "alt_text": "Runner Sneaker Black size 42 – front view",
    "display_order": 0
  }'

await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H/images',
  {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'x-csrf-token': csrfToken,
    },
    body: JSON.stringify({
      image_url: 'https://ik.imagekit.io/yourstore/variants/runner-black-42.jpg',
      alt_text: 'Runner Sneaker Black size 42 – front view',
      display_order: 0,
    }),
  }
);

Get Variant Image

Fetch a single variant image by its public ID.

GET /admin/products/{product_public_id}/variants/{variant_public_id}/images/{variant_image_public_id}

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

string

required

The variant image’s public ID, prefixed vimg_.

Update Variant Image

Partially update a variant image’s URL, alt text, or display order.

PATCH /admin/products/{product_public_id}/variants/{variant_public_id}/images/{variant_image_public_id}

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

string

required

The variant image’s public ID, prefixed vimg_.

Request Body

At least one field is required.

string

Replacement ImageKit URL. Maximum 2048 characters.

string | null

Updated alt text. Pass null to clear.

integer

Updated sort position. Must be ≥ 0.

Delete Variant Image

Delete a variant image. Returns 204 No Content on success. Returns 404 if the product, variant, or image does not exist.

DELETE /admin/products/{product_public_id}/variants/{variant_public_id}/images/{variant_image_public_id}

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

string

required

The variant image’s public ID, prefixed vimg_.

Example

curl -X DELETE \
  https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H/images/vimg_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H/images/vimg_01H',
  {
    method: 'DELETE',
    credentials: 'include',
    headers: { 'x-csrf-token': csrfToken },
  }
);

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Images API — Attach Product and Variant Images

ImageKit Upload Workflow

Product Images

List Product Images

Path Parameters

Query Parameters

Response

Attach Product Image

Path Parameters

Request Body

Example

201 Response

Get Product Image

Path Parameters

Update Product Image

Path Parameters

Request Body

Delete Product Image

Path Parameters

Example

Variant Images

List Variant Images

Path Parameters

Query Parameters

Attach Variant Image

Path Parameters

Request Body

Example

Get Variant Image

Path Parameters

Update Variant Image

Path Parameters

Request Body

Delete Variant Image

Path Parameters

Example

​ImageKit Upload Workflow

​Product Images

​List Product Images

​Path Parameters

​Query Parameters

​Response

​Attach Product Image

​Path Parameters

​Request Body

​Example

​201 Response

​Get Product Image

​Path Parameters

​Update Product Image

​Path Parameters

​Request Body

​Delete Product Image

​Path Parameters

​Example

​Variant Images

​List Variant Images

​Path Parameters

​Query Parameters

​Attach Variant Image

​Path Parameters

​Request Body

​Example

​Get Variant Image

​Path Parameters

​Update Variant Image

​Path Parameters

​Request Body

​Delete Variant Image

​Path Parameters

​Example

ImageKit Upload Workflow

Product Images

List Product Images

Path Parameters

Query Parameters

Response

Attach Product Image

Path Parameters

Request Body

Example

201 Response

Get Product Image

Path Parameters

Update Product Image

Path Parameters

Request Body

Delete Product Image

Path Parameters

Example

Variant Images

List Variant Images

Path Parameters

Query Parameters

Attach Variant Image

Path Parameters

Request Body

Example

Get Variant Image

Path Parameters

Update Variant Image

Path Parameters

Request Body

Delete Variant Image

Path Parameters

Example