Skip to main content

Product Variants

5 API calls in this section.

Create Product Variant​

Storefront & Commerce / Products & Variants / Product Variants
POST/storefront/products/:productId/variants

Creates a new variant for a product. The variant must provide values for all variant options selected on the parent product. The attributes field must contain values for each option defined in the product's variant_options array.

  • Required: Valid Bearer token with tenant admin permissions

Exactly one scenario must be provided

  • Scenario A (link existing): warehouse_item_id

  • Scenario B (create new): warehouse_id + location_id + inventory_quantity (and no warehouse_item_id)

Rules

  • Sending Scenario A and Scenario B fields together returns 400

  • If neither scenario is provided, returns 400

  • Scenario B requires permission manage:operations:tenant

Required Fields

  • name: Multi-language variant name object

  • attributes: Object containing values for each product variant option

Optional Fields

  • price: Variant-specific price. When omitted, product.price is used.

  • description: Multi-language variant description

  • is_active: Boolean to enable/disable variant (default: true)

  • is_primary: Boolean to mark as primary variant (default: false)

  • images: Array of image URLs

  • syncStock: Boolean (default: true). When true, variant stock is synced from warehouse after linking.

Variant Attributes Validation

  • Must provide values for ALL variant options defined on the product

  • If product has variant_options: ["colors", "size", "model", "ram"]

  • Then attributes must include: {"colors": "...", "size": "...", "model": "...", "ram": "..."}

  • Missing or extra attributes will cause validation errors

Automatic Aggregation

  • Variant attribute values are automatically aggregated into product's available_option_values

  • This enables filtering products by available variant options

Features

  • Multi-language support (en, ar, ku)

  • Strict validation of variant attributes

  • Primary variant designation

  • Image gallery support

Path parameters

ParameterTypeDescription
productIdRequiredstring

Dynamic path value from the request URL.

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Body parameters

ParameterTypeDescription
nameobject—
name.enstring—
name.arstring—
name.kustring—
descriptionobject—
description.enstring—
description.arstring—
description.kustring—
slugstring—
pricenumber—
skustring—
warehouse_item_idstring—
Show 11 more body fields

Additional body parameters

ParameterTypeDescription
is_activeboolean—
is_primaryboolean—
mediaarray<object>—
media.typestring—
media.urlstring—
media.sortOrdernumber—
attributesobject—
attributes.colorsstring—
attributes.sizestring—
attributes.modelstring—
attributes.ramstring—
Staging
Request
curl
1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCTID}/variants" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": {6    "en": "MacBook Pro M4 Space Gray",7    "ar": "ماك بوك برو M4 رمادي فضائي",8    "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"9  },10  "description": {11    "en": "14-inch MacBook Pro with M4 chip",12    "ar": "ماك بوك برو 14 بوصة مع معالج M4",13    "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4"14  },15  "slug": "macbook-pro-m4-space-gray",16  "price": 1999.99,17  "sku": "MBP-M4-14-SG-24GB",18  "warehouse_item_id": "warehouse-mbp-m4-space-gray",19  "is_active": true,20  "is_primary": true,21  "media": [22    {23      "type": "image",24      "url": "mbp-space-gray-1.jpg",25      "sortOrder": 026    },27    {28      "type": "video",29      "url": "mbp-space-gray-rotation.mp4",30      "sortOrder": 131    },32    {33      "type": "image",34      "url": "mbp-space-gray-2.jpg",35      "sortOrder": 236    }37  ],38  "attributes": {39    "colors": "Space Gray",40    "size": "14 inch",41    "model": "M4 14CPU 20GPU",42    "ram": "24GB"43  }44}'

Response examples

201Created
Response body
json
1{2  "success": true,3  "data": {4    "id": "variant-uuid",5    "product_id": "product-uuid",6    "warehouse_item_id": "warehouse-mbp-m4-space-gray",7    "slug": "macbook-pro-m4-space-gray",8    "name": {9      "en": "MacBook Pro M4 Space Gray",10      "ar": "ماك بوك برو M4 رمادي فضائي",11      "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"12    },13    "description": {14      "en": "14-inch MacBook Pro with M4 chip",15      "ar": "ماك بوك برو 14 بوصة مع معالج M4",16      "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4"17    },18    "price": 1999.99,19    "sku": "MBP-M4-14-SG-24GB",20    "stock_quantity": 15,21    "is_active": true,22    "is_primary": true,23    "images": [24      "mbp-space-gray-1.jpg",25      "mbp-space-gray-2.jpg"26    ],27    "media": [28      {29        "type": "image",30        "url": "mbp-space-gray-1.jpg",31        "sortOrder": 032      },33      {34        "type": "video",35        "url": "mbp-space-gray-rotation.mp4",36        "sortOrder": 137      },38      {39        "type": "image",40        "url": "mbp-space-gray-2.jpg",41        "sortOrder": 242      }43    ],44    "attributes": {45      "colors": "Space Gray",46      "size": "14 inch",47      "model": "M4 14CPU 20GPU",48      "ram": "24GB"49    },50    "created_at": "2024-07-20T10:00:00Z",51    "updated_at": "2024-07-20T10:00:00Z"52  },53  "message": "Product variant created successfully"54}

Create Product Variants Bulk​

Storefront & Commerce / Products & Variants / Product Variants
POST/storefront/products/:productId/variants/bulk

Create multiple product variants in a single request with strict validation against the product's variant options. All variants must provide values for the exact variant options defined on the parent product.

  • Required: Valid Bearer token with tenant admin permissions

Each variant must provide exactly one scenario

  • Scenario A (link existing): warehouse_item_id

  • Scenario B (create new): warehouse_id + location_id + inventory_quantity (and no warehouse_item_id)

Rules

  • Sending Scenario A and Scenario B fields together returns 400 for that variant

  • If neither scenario is provided, returns 400 for that variant

  • Scenario B requires permission manage:operations:tenant

Validation Requirements

  • Each variant must have attributes matching ALL product variant options

  • If product has variant_options: ["colors", "size", "model", "ram"]

  • Then every variant must include: {"colors": "...", "size": "...", "model": "...", "ram": "..."}

  • Missing or extra attributes will cause individual variant failures

Response Format

  • 201: All variants created successfully

  • 207: Partial success (some variants created, some failed)

  • 400: Validation errors or invalid request format

  • 404: Product not found

Automatic Features

  • Stock synchronization from warehouse (if syncStock: true)

  • Aggregation of variant values into product's available_option_values

  • Multi-language support for names and descriptions

  • Primary variant designation

  • Image gallery support

Error Handling

  • Individual variant validation with detailed error reporting

  • Continues processing valid variants even if some fail

  • Comprehensive summary with success/failure counts

  • Specific error messages for attribute validation failures

Use Cases

  • Bulk import of product configurations

  • Setting up complete product families

  • Migrating inventory from external systems

  • Creating seasonal product variations

Path parameters

ParameterTypeDescription
productIdRequiredstring

The ID of the product to create variants for

Example: your-product-id

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
nameobject—
name.enstring—
name.arstring—
name.kustring—
descriptionobject—
description.enstring—
description.arstring—
description.kustring—
pricenumber—
skustring—
warehouse_item_idstring—
is_activeboolean—
Show 11 more body fields

Additional body parameters

ParameterTypeDescription
is_primaryboolean—
mediaarray<object>—
media.typestring—
media.urlstring—
media.sortOrdernumber—
attributesobject—
attributes.colorsstring—
attributes.sizestring—
attributes.modelstring—
attributes.ramstring—
syncStockboolean—
Staging
Request
curl
1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCTID}/variants/bulk" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '[5  {6    "name": {7      "en": "MacBook Pro M4 Space Gray",8      "ar": "ماك بوك برو M4 رمادي فضائي",9      "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"10    },11    "description": {12      "en": "14-inch MacBook Pro with M4 chip and 24GB RAM",13      "ar": "ماك بوك برو 14 بوصة مع معالج M4 وذاكرة 24 جيجابايت",14      "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4 و یادگەی 24 گیگابایت"15    },16    "price": 1999.99,17    "sku": "MBP-M4-14-SG-24GB",18    "warehouse_item_id": "warehouse-mbp-m4-space-gray-24gb",19    "is_active": true,20    "is_primary": true,21    "media": [22      {23        "type": "image",24        "url": "mbp-space-gray-1.jpg",25        "sortOrder": 026      },27      {28        "type": "video",29        "url": "mbp-space-gray-spin.mp4",30        "sortOrder": 131      },32      {33        "type": "image",34        "url": "mbp-space-gray-2.jpg",35        "sortOrder": 236      }37    ],38    "attributes": {39      "colors": "Space Gray",40      "size": "14 inch",41      "model": "M4 14CPU 20GPU",42      "ram": "24GB"43    },44    "syncStock": true45  },46  {47    "name": {48      "en": "MacBook Pro M4 Silver",49      "ar": "ماك بوك برو M4 فضي",50      "ku": "ماک بوک پرۆ M4 زیوەیی"51    },52    "description": {53      "en": "16-inch MacBook Pro with M4 chip and 32GB RAM",54      "ar": "ماك بوك برو 16 بوصة مع معالج M4 وذاكرة 32 جيجابايت",55      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 و یادگەی 32 گیگابایت"56    },57    "price": 2499.99,58    "sku": "MBP-M4-16-SL-32GB",59    "warehouse_item_id": "warehouse-mbp-m4-silver-32gb",60    "is_active": true,61    "is_primary": false,62    "media": [63      {64        "type": "image",65        "url": "mbp-silver-1.jpg",66        "sortOrder": 067      },68      {69        "type": "image",70        "url": "mbp-silver-2.jpg",71        "sortOrder": 172      }73    ],74    "attributes": {75      "colors": "Silver",76      "size": "16 inch",77      "model": "M4 Pro 12CPU 18GPU",78      "ram": "32GB"79    },80    "syncStock": true81  },82  {83    "name": {84      "en": "MacBook Pro M4 Space Black",85      "ar": "ماك بوك برو M4 أسود فضائي",86      "ku": "ماک بوک پرۆ M4 ڕەنگی ڕەشی ئاسمانی"87    },88    "description": {89      "en": "16-inch MacBook Pro with M4 Max chip and 64GB RAM",90      "ar": "ماك بوك برو 16 بوصة مع معالج M4 Max وذاكرة 64 جيجابايت",91      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 Max و یادگەی 64 گیگابایت"92    },93    "price": 3999.99,94    "sku": "MBP-M4MAX-16-SB-64GB",95    "warehouse_item_id": "warehouse-mbp-m4max-space-black-64gb",96    "is_active": true,97    "is_primary": false,98    "media": [99      {100        "type": "image",101        "url": "mbp-space-black-1.jpg",102        "sortOrder": 0103      },104      {105        "type": "image",106        "url": "mbp-space-black-2.jpg",107        "sortOrder": 1108      }109    ],110    "attributes": {111      "colors": "Space Black",112      "size": "16 inch",113      "model": "M4 Max 14CPU 32GPU",114      "ram": "64GB"115    },116    "syncStock": false117  }118]'

Response examples

201Created
Response body
json
1{2  "success": true,3  "message": "All variants created successfully",4  "created_variants": [5    {6      "id": "variant-id-1",7      "product_id": "product-id",8      "warehouse_item_id": "warehouse-item-red-l",9      "name": {10        "en": "Red T-Shirt Large",11        "ar": "تيشيرت أحمر كبير"12      },13      "price": 25.99,14      "sku": "TSHIRT-RED-L",15      "stock_quantity": 50,16      "is_active": true,17      "is_primary": true,18      "created_at": "2024-01-01T00:00:00Z"19    }20  ],21  "summary": {22    "total_requested": 3,23    "successful": 3,24    "failed": 025  }26}

Get Product Variants​

Storefront & Commerce / Products & Variants / Product Variants
GET/storefront/products/:productId/variants

Retrieves variants for a specific product with search and filtering capabilities.

Features

  • Multi-language search across variant names, descriptions, and SKUs

  • Active/inactive status filtering

  • Pagination support with limit and offset

  • Market-scoped results

Search & Filter Features

  • Multi-language Search: Searches across English, Arabic, and Kurdish variant names and descriptions, plus SKU field

  • Status Filtering: Filter by active/inactive variants

  • Pagination: Use limit and offset for result pagination

Authentication Required

Tenant-level access

Path parameters

ParameterTypeDescription
productIdRequiredstring

The ID of the product to get variants for

Example: your-product-id

Query parameters

ParameterTypeDescription
searchOptionalstring

Search variants by name, description, or SKU in any language (en/ar/ku) Search term to find variants by name, description, or SKU in any language

Example: red

is_activeOptionalstring

Filter by active status (true/false). If not provided, returns all variants.

Example: true

limitOptionalstring

Number of variants to return (default: 20)

Example: 20

offsetOptionalstring

Number of variants to skip for pagination (default: 0)

Example: 0

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCTID}/variants?search=red&is_active=true&limit=20&offset=0" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

No saved response example. Use Try it to inspect a staging response.

Update Product Variant​

Storefront & Commerce / Products & Variants / Product Variants
PUT/storefront/products/:productId/variants/:variantId

Change the price or media of one storefront product variant.

Path parameters

ParameterTypeDescription
productIdRequiredstring

Dynamic path value from the request URL.

variantIdRequiredstring

Dynamic path value from the request URL.

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Body parameters

ParameterTypeDescription
pricenumber—
mediaarray<object>—
media.typestring—
media.urlstring—
media.sortOrdernumber—
Staging
Request
curl
1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCTID}/variants/${VARIANTID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "price": 27.99,6  "media": [7    {8      "type": "image",9      "url": "https://cdn.example.com/variants/red-shirt-front-updated.jpg",10      "sortOrder": 011    },12    {13      "type": "video",14      "url": "https://cdn.example.com/variants/red-shirt-updated-spin.mp4",15      "sortOrder": 116    }17  ]18}'

Response examples

No saved response example. Use Try it to inspect a staging response.

Delete Product Variant​

Storefront & Commerce / Products & Variants / Product Variants
DELETE/storefront/products/:productId/variants/:variantId

Remove a variant from its storefront product.

Path parameters

ParameterTypeDescription
productIdRequiredstring

Dynamic path value from the request URL.

variantIdRequiredstring

Dynamic path value from the request URL.

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/products/${PRODUCTID}/variants/${VARIANTID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

No saved response example. Use Try it to inspect a staging response.