Admin Variants API — Manage Product Variants and SKUs

Every purchasable item in the catalog is represented by a variant. A variant belongs to a product and carries its own SKU, pricing, discount, physical dimensions, and lifecycle status. Use this API to build out your product’s size and color matrix, set prices, manage stock readiness via status flags, and soft-delete discontinued options while retaining order history integrity.

All variant endpoints require an authenticated session with the ADMIN or SUPER_ADMIN role. Call GET /auth/csrf-token before every POST, PATCH, or DELETE request and supply the token in the x-csrf-token header.

Variant Status Reference

A variant’s status field controls its visibility and purchase eligibility on the storefront.

Status	Description
`ACTIVE`	Visible to customers and available for purchase (subject to stock).
`DRAFT`	Hidden from customers; used while the variant is being prepared.
`INACTIVE`	Temporarily hidden from customers but not discontinued.
`ARCHIVED`	Discontinued. Hidden from customers and not expected to return.

The default status when creating a variant is DRAFT. Transition a variant to ACTIVE once it is ready for sale and has an inventory record.

List Variants

Retrieve a paginated list of variants for a given product. Filter by status, include soft-deleted entries, and sort across multiple fields.

GET /admin/products/{product_public_id}/variants

Path Parameters

string

required

The parent 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.

string

Filter by variant status. One of ACTIVE, DRAFT, INACTIVE, or ARCHIVED.

string

default:"false"

Pass "true" to include soft-deleted variants. Must be the string "true" or "false".

string

default:"created_at"

Sort field. Prefix with - for descending order. Accepted values: sku, -sku, price, -price, created_at, -created_at, updated_at, -updated_at.

Response

array

Array of variant objects.

Show Variant fields

string

Variant public ID, prefixed var_.

string

Stock-keeping unit identifier.

string | null

Barcode or UPC, if set.

string | null

Color label, if set.

string | null

Size label, if set.

string

Retail price as a decimal string, e.g. "99.99".

string | null

Cost price as a decimal string, if set.

string | null

Discount percentage as a decimal string (0.00–100.00), if set.

string

Computed selling price after discount, as a decimal string.

string | null

Weight in your configured unit, as a decimal string.

string | null

Length dimension, as a decimal string.

string | null

Width dimension, as a decimal string.

string | null

Height dimension, as a decimal string.

string

Lifecycle status: ACTIVE, DRAFT, INACTIVE, or ARCHIVED.

string | null

ISO 8601 UTC soft-deletion timestamp, or null.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-updated timestamp.

object

Show Pagination fields

integer

Total matching records.

integer

Total pages.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

Create Variant

Add a new variant to a product. sku and price are the only required fields. All other fields are optional and can be set now or updated later via PATCH.

POST /admin/products/{product_public_id}/variants

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

Request Body

string

required

Stock-keeping unit identifier. Must be unique across all variants platform-wide. Between 1 and 80 characters.

string

required

Retail price as a decimal string matching ^\d{1,10}(\.\d{1,2})?$. Example: "99.99". Never use a float.

string

Barcode or UPC. Maximum 255 characters.

string

Color label, e.g. "Black". Maximum 50 characters.

string

Size label, e.g. "42" or "XL". Maximum 50 characters.

string

Cost price as a decimal string. Used for margin calculations; not exposed to customers.

string

Discount applied to price when computing final_price. Decimal string between "0.00" and "100.00".

string

Weight as a decimal string. Unit determined by your store configuration.

string

Length dimension as a decimal string.

string

Width dimension as a decimal string.

string

Height dimension as a decimal string.

string

default:"DRAFT"

Initial lifecycle status. One of ACTIVE, DRAFT, INACTIVE, ARCHIVED. Defaults to DRAFT.

Example

# Step 1: get CSRF token
TOKEN=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" \
  | jq -r '.data.csrf_token')

# Step 2: create variant
curl -X POST https://api.example.com/api/v1/admin/products/prd_01H/variants \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "sku": "RUN-001-BLK-42",
    "price": "99.99",
    "color": "Black",
    "size": "42",
    "discount_percentage": "10.00",
    "weight": "0.35",
    "status": "DRAFT"
  }'

const response = await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/variants',
  {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'x-csrf-token': csrfToken,
    },
    body: JSON.stringify({
      sku: 'RUN-001-BLK-42',
      price: '99.99',
      color: 'Black',
      size: '42',
      discount_percentage: '10.00',
      weight: '0.35',
      status: 'DRAFT',
    }),
  }
);
const data = await response.json();

201 Response

{
  "success": true,
  "data": {
    "public_id": "var_01H",
    "sku": "RUN-001-BLK-42",
    "barcode": null,
    "color": "Black",
    "size": "42",
    "price": "99.99",
    "cost_price": null,
    "discount_percentage": "10.00",
    "final_price": "89.99",
    "weight": "0.35",
    "length": null,
    "width": null,
    "height": null,
    "status": "DRAFT",
    "deleted_at": null,
    "created_at": "2024-06-01T09:05:00.000Z",
    "updated_at": "2024-06-01T09:05:00.000Z"
  }
}

SKU values must be unique across all variants in the entire platform, not just within a single product. Attempting to create a variant with a duplicate SKU returns a 409 Conflict. Plan your SKU naming scheme (e.g. BRAND-MODEL-COLOR-SIZE) to avoid collisions.

Error Responses

Status	Meaning
`400`	Validation error — invalid decimal format, bad status value, or missing required field.
`401`	No active session.
`403`	Insufficient role.
`409`	A variant with this SKU already exists.

Get Variant

Fetch a single variant by its public ID within a product.

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

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

Returns the full variant object. Responds with 404 if the product or variant does not exist.

Update Variant

Partially update a variant’s fields. Only the fields you supply are changed. Pass null for any nullable optional field — barcode, color, size, cost_price, weight, length, width, height — to explicitly clear it.

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

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

Request Body

At least one field is required. All fields from the create request are accepted, plus all nullable fields can be set to null to clear them.

Example

curl -X PATCH \
  https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "status": "ACTIVE",
    "price": "89.99",
    "discount_percentage": "0.00"
  }'

await fetch(
  'https://api.example.com/api/v1/admin/products/prd_01H/variants/var_01H',
  {
    method: 'PATCH',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'x-csrf-token': csrfToken,
    },
    body: JSON.stringify({
      status: 'ACTIVE',
      price: '89.99',
      discount_percentage: '0.00',
    }),
  }
);

Delete Variant

Soft-delete a variant. The variant is immediately hidden from customer views but is retained in the database so that existing order line items continue to reference the correct SKU and price snapshots. Returns 204 No Content on success.

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

Path Parameters

string

required

The parent product’s public ID, prefixed prd_.

string

required

The variant’s public ID, prefixed var_.

Example

curl -X DELETE \
  https://api.example.com/api/v1/admin/products/prd_01H/variants/var_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',
  {
    method: 'DELETE',
    credentials: 'include',
    headers: { 'x-csrf-token': csrfToken },
  }
);

Error Responses

Status	Meaning
`401`	No active session.
`403`	Insufficient role.
`404`	Product or variant not found.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Variants API — Manage Product Variants and SKUs

Variant Status Reference

List Variants

Path Parameters

Query Parameters

Response

Create Variant

Path Parameters

Request Body

Example

201 Response

Error Responses

Get Variant

Path Parameters

Update Variant

Path Parameters

Request Body

Example

Delete Variant

Path Parameters

Example

Error Responses

​Variant Status Reference

​List Variants

​Path Parameters

​Query Parameters

​Response

​Create Variant

​Path Parameters

​Request Body

​Example

​201 Response

​Error Responses

​Get Variant

​Path Parameters

​Update Variant

​Path Parameters

​Request Body

​Example

​Delete Variant

​Path Parameters

​Example

​Error Responses

Variant Status Reference

List Variants

Path Parameters

Query Parameters

Response

Create Variant

Path Parameters

Request Body

Example

201 Response

Error Responses

Get Variant

Path Parameters

Update Variant

Path Parameters

Request Body

Example

Delete Variant

Path Parameters

Example

Error Responses