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. Authentication: - 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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/storefront/products/:productId/variants" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --data '{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}'
Request body
json
1{2  "name": {3    "en": "MacBook Pro M4 Space Gray",4    "ar": "ماك بوك برو M4 رمادي فضائي",5    "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"6  },7  "description": {8    "en": "14-inch MacBook Pro with M4 chip",9    "ar": "ماك بوك برو 14 بوصة مع معالج M4",10    "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4"11  },12  "slug": "macbook-pro-m4-space-gray",13  "price": 1999.99,14  "sku": "MBP-M4-14-SG-24GB",15  "warehouse_item_id": "warehouse-mbp-m4-space-gray",16  "is_active": true,17  "is_primary": true,18  "media": [19    {20      "type": "image",21      "url": "mbp-space-gray-1.jpg",22      "sortOrder": 023    },24    {25      "type": "video",26      "url": "mbp-space-gray-rotation.mp4",27      "sortOrder": 128    },29    {30      "type": "image",31      "url": "mbp-space-gray-2.jpg",32      "sortOrder": 233    }34  ],35  "attributes": {36    "colors": "Space Gray",37    "size": "14 inch",38    "model": "M4 14CPU 20GPU",39    "ram": "24GB"40  }41}

Path parameters

productIdRequired
path string

Request body fields

nameExample
object

Example field from the request body.

name.enExample
string

Example field from the request body.

name.arExample
string

Example field from the request body.

name.kuExample
string

Example field from the request body.

descriptionExample
object

Example field from the request body.

description.enExample
string

Example field from the request body.

description.arExample
string

Example field from the request body.

description.kuExample
string

Example field from the request body.

slugExample
string

Example field from the request body.

priceExample
number

Example field from the request body.

skuExample
string

Example field from the request body.

warehouse_item_idExample
string

Example field from the request body.

is_activeExample
boolean

Example field from the request body.

is_primaryExample
boolean

Example field from the request body.

mediaExample
array<object>

Example field from the request body.

media.typeExample
string

Example field from the request body.

media.urlExample
string

Example field from the request body.

media.sortOrderExample
number

Example field from the request body.

attributesExample
object

Example field from the request body.

attributes.colorsExample
string

Example field from the request body.

attributes.sizeExample
string

Example field from the request body.

attributes.modelExample
string

Example field from the request body.

attributes.ramExample
string

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success - Variant Created201Created
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}
Error - Attribute Validation Failed400Bad Request
Response body
json
1{2  "success": false,3  "message": "This product does not support variant option 'storage'. Add 'storage' to the product's variant options first, or use only: colors, size, model, ram."4}
Error - Missing Required Fields400Bad Request
Response body
json
1{2  "success": false,3  "message": "Validation failed",4  "errors": [5    {6      "field": "name",7      "message": "Name is required"8    },9    {10      "field": "price",11      "message": "Price must be a positive number"12    },13    {14      "field": "sku",15      "message": "SKU is required"16    }17  ]18}

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. Authentication: - 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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/storefront/products/:productId/variants/bulk" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '[6  {7    "name": {8      "en": "MacBook Pro M4 Space Gray",9      "ar": "ماك بوك برو M4 رمادي فضائي",10      "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"11    },12    "description": {13      "en": "14-inch MacBook Pro with M4 chip and 24GB RAM",14      "ar": "ماك بوك برو 14 بوصة مع معالج M4 وذاكرة 24 جيجابايت",15      "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4 و یادگەی 24 گیگابایت"16    },17    "price": 1999.99,18    "sku": "MBP-M4-14-SG-24GB",19    "warehouse_item_id": "warehouse-mbp-m4-space-gray-24gb",20    "is_active": true,21    "is_primary": true,22    "media": [23      {24        "type": "image",25        "url": "mbp-space-gray-1.jpg",26        "sortOrder": 027      },28      {29        "type": "video",30        "url": "mbp-space-gray-spin.mp4",31        "sortOrder": 132      },33      {34        "type": "image",35        "url": "mbp-space-gray-2.jpg",36        "sortOrder": 237      }38    ],39    "attributes": {40      "colors": "Space Gray",41      "size": "14 inch",42      "model": "M4 14CPU 20GPU",43      "ram": "24GB"44    },45    "syncStock": true46  },47  {48    "name": {49      "en": "MacBook Pro M4 Silver",50      "ar": "ماك بوك برو M4 فضي",51      "ku": "ماک بوک پرۆ M4 زیوەیی"52    },53    "description": {54      "en": "16-inch MacBook Pro with M4 chip and 32GB RAM",55      "ar": "ماك بوك برو 16 بوصة مع معالج M4 وذاكرة 32 جيجابايت",56      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 و یادگەی 32 گیگابایت"57    },58    "price": 2499.99,59    "sku": "MBP-M4-16-SL-32GB",60    "warehouse_item_id": "warehouse-mbp-m4-silver-32gb",61    "is_active": true,62    "is_primary": false,63    "media": [64      {65        "type": "image",66        "url": "mbp-silver-1.jpg",67        "sortOrder": 068      },69      {70        "type": "image",71        "url": "mbp-silver-2.jpg",72        "sortOrder": 173      }74    ],75    "attributes": {76      "colors": "Silver",77      "size": "16 inch",78      "model": "M4 Pro 12CPU 18GPU",79      "ram": "32GB"80    },81    "syncStock": true82  },83  {84    "name": {85      "en": "MacBook Pro M4 Space Black",86      "ar": "ماك بوك برو M4 أسود فضائي",87      "ku": "ماک بوک پرۆ M4 ڕەنگی ڕەشی ئاسمانی"88    },89    "description": {90      "en": "16-inch MacBook Pro with M4 Max chip and 64GB RAM",91      "ar": "ماك بوك برو 16 بوصة مع معالج M4 Max وذاكرة 64 جيجابايت",92      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 Max و یادگەی 64 گیگابایت"93    },94    "price": 3999.99,95    "sku": "MBP-M4MAX-16-SB-64GB",96    "warehouse_item_id": "warehouse-mbp-m4max-space-black-64gb",97    "is_active": true,98    "is_primary": false,99    "media": [100      {101        "type": "image",102        "url": "mbp-space-black-1.jpg",103        "sortOrder": 0104      },105      {106        "type": "image",107        "url": "mbp-space-black-2.jpg",108        "sortOrder": 1109      }110    ],111    "attributes": {112      "colors": "Space Black",113      "size": "16 inch",114      "model": "M4 Max 14CPU 32GPU",115      "ram": "64GB"116    },117    "syncStock": false118  }119]'
Request body
json
1[2  {3    "name": {4      "en": "MacBook Pro M4 Space Gray",5      "ar": "ماك بوك برو M4 رمادي فضائي",6      "ku": "ماک بوک پرۆ M4 ڕەنگی گریی ئاسمانی"7    },8    "description": {9      "en": "14-inch MacBook Pro with M4 chip and 24GB RAM",10      "ar": "ماك بوك برو 14 بوصة مع معالج M4 وذاكرة 24 جيجابايت",11      "ku": "ماک بوک پرۆی 14 ئینچی لەگەڵ چیپی M4 و یادگەی 24 گیگابایت"12    },13    "price": 1999.99,14    "sku": "MBP-M4-14-SG-24GB",15    "warehouse_item_id": "warehouse-mbp-m4-space-gray-24gb",16    "is_active": true,17    "is_primary": true,18    "media": [19      {20        "type": "image",21        "url": "mbp-space-gray-1.jpg",22        "sortOrder": 023      },24      {25        "type": "video",26        "url": "mbp-space-gray-spin.mp4",27        "sortOrder": 128      },29      {30        "type": "image",31        "url": "mbp-space-gray-2.jpg",32        "sortOrder": 233      }34    ],35    "attributes": {36      "colors": "Space Gray",37      "size": "14 inch",38      "model": "M4 14CPU 20GPU",39      "ram": "24GB"40    },41    "syncStock": true42  },43  {44    "name": {45      "en": "MacBook Pro M4 Silver",46      "ar": "ماك بوك برو M4 فضي",47      "ku": "ماک بوک پرۆ M4 زیوەیی"48    },49    "description": {50      "en": "16-inch MacBook Pro with M4 chip and 32GB RAM",51      "ar": "ماك بوك برو 16 بوصة مع معالج M4 وذاكرة 32 جيجابايت",52      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 و یادگەی 32 گیگابایت"53    },54    "price": 2499.99,55    "sku": "MBP-M4-16-SL-32GB",56    "warehouse_item_id": "warehouse-mbp-m4-silver-32gb",57    "is_active": true,58    "is_primary": false,59    "media": [60      {61        "type": "image",62        "url": "mbp-silver-1.jpg",63        "sortOrder": 064      },65      {66        "type": "image",67        "url": "mbp-silver-2.jpg",68        "sortOrder": 169      }70    ],71    "attributes": {72      "colors": "Silver",73      "size": "16 inch",74      "model": "M4 Pro 12CPU 18GPU",75      "ram": "32GB"76    },77    "syncStock": true78  },79  {80    "name": {81      "en": "MacBook Pro M4 Space Black",82      "ar": "ماك بوك برو M4 أسود فضائي",83      "ku": "ماک بوک پرۆ M4 ڕەنگی ڕەشی ئاسمانی"84    },85    "description": {86      "en": "16-inch MacBook Pro with M4 Max chip and 64GB RAM",87      "ar": "ماك بوك برو 16 بوصة مع معالج M4 Max وذاكرة 64 جيجابايت",88      "ku": "ماک بوک پرۆی 16 ئینچی لەگەڵ چیپی M4 Max و یادگەی 64 گیگابایت"89    },90    "price": 3999.99,91    "sku": "MBP-M4MAX-16-SB-64GB",92    "warehouse_item_id": "warehouse-mbp-m4max-space-black-64gb",93    "is_active": true,94    "is_primary": false,95    "media": [96      {97        "type": "image",98        "url": "mbp-space-black-1.jpg",99        "sortOrder": 0100      },101      {102        "type": "image",103        "url": "mbp-space-black-2.jpg",104        "sortOrder": 1105      }106    ],107    "attributes": {108      "colors": "Space Black",109      "size": "16 inch",110      "model": "M4 Max 14CPU 32GPU",111      "ram": "64GB"112    },113    "syncStock": false114  }115]

Path parameters

productIdRequired
path string

your-product-id

The ID of the product to create variants for

Request body fields

nameExample
object

Example field from the request body.

name.enExample
string

Example field from the request body.

name.arExample
string

Example field from the request body.

name.kuExample
string

Example field from the request body.

descriptionExample
object

Example field from the request body.

description.enExample
string

Example field from the request body.

description.arExample
string

Example field from the request body.

description.kuExample
string

Example field from the request body.

priceExample
number

Example field from the request body.

skuExample
string

Example field from the request body.

warehouse_item_idExample
string

Example field from the request body.

is_activeExample
boolean

Example field from the request body.

is_primaryExample
boolean

Example field from the request body.

mediaExample
array<object>

Example field from the request body.

media.typeExample
string

Example field from the request body.

media.urlExample
string

Example field from the request body.

media.sortOrderExample
number

Example field from the request body.

attributesExample
object

Example field from the request body.

attributes.colorsExample
string

Example field from the request body.

attributes.sizeExample
string

Example field from the request body.

attributes.modelExample
string

Example field from the request body.

attributes.ramExample
string

Example field from the request body.

syncStockExample
boolean

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response201Created
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}
Partial Success Response207Multi-Status
Response body
json
1{2  "success": false,3  "message": "2 of 3 variants created successfully",4  "created_variants": [5    {6      "id": "variant-id-1",7      "product_id": "product-id",8      "name": {9        "en": "Red T-Shirt Large"10      },11      "price": 25.9912    }13  ],14  "errors": [15    {16      "index": 2,17      "error": "Warehouse item not found"18    }19  ],20  "summary": {21    "total_requested": 3,22    "successful": 2,23    "failed": 124  }25}
Validation Error Response400Bad Request
Response body
json
1{2  "success": false,3  "message": "Validation errors found",4  "errors": [5    {6      "index": 0,7      "errors": [8        {9          "field": "price",10          "message": "Price is required"11        }12      ]13    }14  ]15}

Get Product Variants​

Storefront & Commerce / Products & Variants / Product Variants
GET/storefront/products/:productId/variants?search=red&is_active=true&limit=20&offset=0

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 Query Parameters: - search (optional): Search term to find variants by name, description, or SKU in any language - is_active (optional): Filter by active status (true/false). If not provided, returns all variants - limit (optional): Number of variants to return (default: 20) - offset (optional): Number of variants to skip for pagination (default: 0) Authentication Required: Tenant-level access

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/storefront/products/:productId/variants?search=red&is_active=true&limit=20&offset=0" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

productIdRequired
path string

your-product-id

The ID of the product to get variants for

Query parameters

searchOptional
query string

red

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

is_activeOptional
query string

true

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

limitOptional
query string

20

Number of variants to return (default: 20)

offsetOptional
query string

0

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

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

No response example is available for this endpoint yet.

Update Product Variant​

Storefront & Commerce / Products & Variants / Product Variants
PUT/storefront/products/:productId/variants/:variantId
Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request PUT "$ONDI_BASE_URL/storefront/products/:productId/variants/:variantId" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --data '{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}'
Request body
json
1{2  "price": 27.99,3  "media": [4    {5      "type": "image",6      "url": "https://cdn.example.com/variants/red-shirt-front-updated.jpg",7      "sortOrder": 08    },9    {10      "type": "video",11      "url": "https://cdn.example.com/variants/red-shirt-updated-spin.mp4",12      "sortOrder": 113    }14  ]15}

Path parameters

productIdRequired
path string
variantIdRequired
path string

Request body fields

priceExample
number

Example field from the request body.

mediaExample
array<object>

Example field from the request body.

media.typeExample
string

Example field from the request body.

media.urlExample
string

Example field from the request body.

media.sortOrderExample
number

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

No response example is available for this endpoint yet.

Delete Product Variant​

Storefront & Commerce / Products & Variants / Product Variants
DELETE/storefront/products/:productId/variants/:variantId
Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request DELETE "$ONDI_BASE_URL/storefront/products/:productId/variants/:variantId" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

productIdRequired
path string
variantIdRequired
path string

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

No response example is available for this endpoint yet.