Variant Option Types Management
5 API calls in this section.
List Variant Option Types
/storefront/variant-option-types?include_system=true&include_custom=true&tenant_id={{tenant_id}}Retrieves available variant option types including both system-wide (colors, size, volume, etc.) and tenant-specific custom options. These option types are used when creating products to define what variant attributes are required. Authentication: - Required: Valid Bearer token with tenant access Query Parameters: - include_system (optional): Include system-wide option types like colors, size, volume (default: true) - include_custom (optional): Include tenant-specific custom option types (default: true) - tenant_id (optional): Specific tenant ID for custom options (defaults to user's tenant) System Option Types: - colors: Color variations (Red, Blue, Black, etc.) - size: Size variations (S, M, L, XL, 14 inch, etc.) - volume: Volume/capacity variations (500ml, 1L, etc.) - model: Model variations (iPhone 15 Pro, MacBook Air, etc.) - weight: Weight variations (1kg, 2.5kg, etc.) - material: Material variations (Cotton, Leather, etc.) - brand: Brand variations (Nike, Adidas, etc.) Custom Option Types: - Tenant-specific options like 'ram', 'storage', 'warranty', etc. - Created by tenant admins for specific business needs - Only visible to the creating tenant Features: - Multi-language support (en, ar, ku) - System and custom option filtering - Tenant-scoped access control - Active status filtering - Alphabetical ordering Use Cases: - Product creation interface (selecting variant options) - Variant management workflows - Product catalog configuration - Custom option type discovery - Multi-language option type display
1curl --request GET "$ONDI_BASE_URL/storefront/variant-option-types?include_system=true&include_custom=true&tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}"Query parameters
include_systemOptionaltrue
Include system-wide option types (default: true)
include_customOptionaltrue
Include tenant-specific custom option types (default: true)
tenant_idOptional{{tenant_id}}
Tenant ID for custom options (optional, defaults to user's tenant)
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated requests (required)
Responses
1{2 "success": true,3 "data": [4 {5 "id": "system-colors-uuid",6 "name": "colors",7 "display_name": {8 "en": "Colors",9 "ar": "الألوان",10 "ku": "ڕەنگەکان"11 },12 "is_system": true,13 "tenant_id": null,14 "is_active": true,15 "created_at": "2024-01-01T00:00:00Z",16 "updated_at": "2024-01-01T00:00:00Z"17 },18 {19 "id": "system-size-uuid",20 "name": "size",21 "display_name": {22 "en": "Size",23 "ar": "الحجم",24 "ku": "قەبارە"25 },26 "is_system": true,27 "tenant_id": null,28 "is_active": true,29 "created_at": "2024-01-01T00:00:00Z",30 "updated_at": "2024-01-01T00:00:00Z"31 },32 {33 "id": "custom-ram-uuid",34 "name": "ram",35 "display_name": {36 "en": "RAM Memory",37 "ar": "ذاكرة الوصول العشوائي",38 "ku": "یادگەی ڕام"39 },40 "is_system": false,41 "tenant_id": "tenant-uuid",42 "is_active": true,43 "created_at": "2024-07-20T10:00:00Z",44 "updated_at": "2024-07-20T10:00:00Z"45 }46 ],47 "message": "Variant option types retrieved successfully"48}1{2 "success": true,3 "data": [4 {5 "id": "system-colors-uuid",6 "name": "colors",7 "display_name": {8 "en": "Colors",9 "ar": "الألوان",10 "ku": "ڕەنگەکان"11 },12 "is_system": true,13 "tenant_id": null,14 "is_active": true,15 "created_at": "2024-01-01T00:00:00Z",16 "updated_at": "2024-01-01T00:00:00Z"17 },18 {19 "id": "system-size-uuid",20 "name": "size",21 "display_name": {22 "en": "Size",23 "ar": "الحجم",24 "ku": "قەبارە"25 },26 "is_system": true,27 "tenant_id": null,28 "is_active": true,29 "created_at": "2024-01-01T00:00:00Z",30 "updated_at": "2024-01-01T00:00:00Z"31 }32 ],33 "message": "Variant option types retrieved successfully"34}1{2 "error": "Unauthorized"3}Create Custom Variant Option Type
/storefront/variant-option-typesCreates a new custom variant option type for the tenant. Custom option types allow businesses to define specific variant attributes beyond the standard system options. Authentication: - Required: Valid Bearer token with tenant access - Permission: Only tenant members can create custom options for their tenant Required Fields: - name: Unique identifier for the option type (lowercase, alphanumeric + underscore) - display_name: Multi-language display names object - display_name.en: English display name (required) - tenant_id: Tenant ID (optional, defaults to user's tenant) Optional Fields: - display_name.ar: Arabic display name - display_name.ku: Kurdish display name Naming Rules: - Must be lowercase - Only alphanumeric characters and underscores allowed - Must be unique within tenant and not conflict with system options - Cannot use names like: colors, size, volume, model, weight, material, brand Features: - Tenant-scoped option types - Multi-language support - Name validation and conflict checking - Automatic activation - Unique constraint enforcement Use Cases: - Electronics: 'ram', 'storage', 'processor', 'graphics_card' - Clothing: 'fabric', 'fit_type', 'collar_style', 'sleeve_length' - Food: 'flavor', 'spice_level', 'dietary_type', 'packaging' - Books: 'format', 'language', 'edition', 'binding_type' Examples: - Tech products: storage, ram, processor, warranty - Fashion: fabric, fit, collar, sleeve - Food: flavor, spice_level, organic, packaging - Books: format, language, edition
1curl --request POST "$ONDI_BASE_URL/storefront/variant-option-types" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "name": "storage",7 "display_name": {8 "en": "Storage Capacity",9 "ar": "سعة التخزين",10 "ku": "قەبارەی هەڵگرتن"11 },12 "tenant_id": "{{tenant_id}}"13}'1{2 "name": "storage",3 "display_name": {4 "en": "Storage Capacity",5 "ar": "سعة التخزين",6 "ku": "قەبارەی هەڵگرتن"7 },8 "tenant_id": "{{tenant_id}}"9}Request body fields
nameExampleExample field from the request body.
display_nameExampleExample field from the request body.
display_name.enExampleExample field from the request body.
display_name.arExampleExample field from the request body.
display_name.kuExampleExample field from the request body.
tenant_idExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated requests (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "data": {4 "id": "custom-storage-uuid",5 "name": "storage",6 "display_name": {7 "en": "Storage Capacity",8 "ar": "سعة التخزين",9 "ku": "قەبارەی هەڵگرتن"10 },11 "is_system": false,12 "tenant_id": "tenant-uuid",13 "is_active": true,14 "created_at": "2024-07-20T10:00:00Z",15 "updated_at": "2024-07-20T10:00:00Z"16 },17 "message": "Variant option type created successfully"18}1{2 "error": "Missing required fields: name, display_name.en"3}1{2 "error": "Name must be lowercase alphanumeric with underscores only"3}1{2 "error": "Option type name conflicts with system option"3}1{2 "error": "Option type name already exists for this tenant"3}1{2 "error": "Access denied. Can only create options for your own tenant."3}Get Variant Option Type
/storefront/variant-option-types/{{option_type_id}}Retrieves a specific variant option type by its ID. Returns both system and custom option types if the user has access. Authentication: - Required: Valid Bearer token with tenant access Path Parameters: - option_type_id: UUID of the variant option type to retrieve Access Control: - System option types: Accessible by all authenticated users - Custom option types: Only accessible by the creating tenant's members Response Data: - Complete option type details - Multi-language display names - System/custom classification - Tenant association (for custom types) - Active status and timestamps Use Cases: - Option type detail views - Edit form pre-population - Validation of option type existence - Display name localization - Permission checking workflows
1curl --request GET "$ONDI_BASE_URL/storefront/variant-option-types/{{option_type_id}}" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
option_type_idRequiredVariable used inside the request path.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated requests (required)
Responses
1{2 "success": true,3 "data": {4 "id": "system-colors-uuid",5 "name": "colors",6 "display_name": {7 "en": "Colors",8 "ar": "الألوان",9 "ku": "ڕەنگەکان"10 },11 "is_system": true,12 "tenant_id": null,13 "is_active": true,14 "created_at": "2024-01-01T00:00:00Z",15 "updated_at": "2024-01-01T00:00:00Z"16 },17 "message": "Variant option type retrieved successfully"18}1{2 "success": true,3 "data": {4 "id": "custom-storage-uuid",5 "name": "storage",6 "display_name": {7 "en": "Storage Capacity",8 "ar": "سعة التخزين",9 "ku": "قەبارەی هەڵگرتن"10 },11 "is_system": false,12 "tenant_id": "tenant-uuid",13 "is_active": true,14 "created_at": "2024-07-20T10:00:00Z",15 "updated_at": "2024-07-20T10:00:00Z"16 },17 "message": "Variant option type retrieved successfully"18}1{2 "error": "Variant option type not found"3}Update Variant Option Type
/storefront/variant-option-types/{{option_type_id}}Updates an existing custom variant option type. Only display names and active status can be modified. System option types cannot be updated. Authentication: - Required: Valid Bearer token with tenant access - Permission: Only tenant members can update their own custom options Path Parameters: - option_type_id: UUID of the variant option type to update Updatable Fields (all optional): - display_name: Multi-language display names object - display_name.en: English display name - display_name.ar: Arabic display name - display_name.ku: Kurdish display name - is_active: Boolean to enable/disable the option type Restrictions: - Cannot update system option types (colors, size, volume, etc.) - Cannot change the name field (immutable after creation) - Can only update option types owned by your tenant - Partial updates supported (only send fields to change) Features: - Partial update support - Multi-language display name updates - Active status control - Ownership validation - System option protection Use Cases: - Updating display names for localization - Enabling/disabling custom option types - Correcting display name typos - Seasonal option type management - Workflow status control
1curl --request PUT "$ONDI_BASE_URL/storefront/variant-option-types/{{option_type_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "display_name": {7 "en": "Storage Memory",8 "ar": "ذاكرة التخزين",9 "ku": "یادگەی هەڵگرتن"10 },11 "is_active": true12}'1{2 "display_name": {3 "en": "Storage Memory",4 "ar": "ذاكرة التخزين",5 "ku": "یادگەی هەڵگرتن"6 },7 "is_active": true8}Path parameters
option_type_idRequiredVariable used inside the request path.
Request body fields
display_nameExampleExample field from the request body.
display_name.enExampleExample field from the request body.
display_name.arExampleExample field from the request body.
display_name.kuExampleExample field from the request body.
is_activeExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated requests (required)
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "data": {4 "id": "custom-storage-uuid",5 "name": "storage",6 "display_name": {7 "en": "Storage Memory",8 "ar": "ذاكرة التخزين",9 "ku": "یادگەی هەڵگرتن"10 },11 "is_system": false,12 "tenant_id": "tenant-uuid",13 "is_active": true,14 "created_at": "2024-07-20T10:00:00Z",15 "updated_at": "2024-07-20T11:00:00Z"16 },17 "message": "Variant option type updated successfully"18}1{2 "error": "Cannot modify system option types"3}1{2 "error": "Access denied. Can only modify options for your own tenant."3}1{2 "error": "Variant option type not found"3}Delete Variant Option Type
/storefront/variant-option-types/{{option_type_id}}Deletes a custom variant option type. This is a soft delete that sets the option type as inactive. System option types cannot be deleted. Includes safety checks to prevent data loss. Authentication: - Required: Valid Bearer token with tenant access - Permission: Only tenant members can delete their own custom options Path Parameters: - option_type_id: UUID of the variant option type to delete Safety Features: - Cannot delete system option types (colors, size, volume, etc.) - Cannot delete option types being used by products - Soft delete (sets is_active to false instead of permanent deletion) - Usage validation before deletion - Ownership verification Deletion Rules: 1. Option type must exist and belong to the user's tenant 2. Option type must not be a system option 3. Option type must not be in use by any products 4. If any rule fails, deletion is prevented with explanation Important Notes: - This is a soft delete (option type becomes inactive) - Products using this option type will prevent deletion - Remove option type from all products before deletion - Consider deactivating instead of deleting for data retention Use Cases: - Cleanup of unused custom option types - Removal of incorrectly created options - Business model changes - Option type consolidation - Tenant cleanup workflows
1curl --request DELETE "$ONDI_BASE_URL/storefront/variant-option-types/{{option_type_id}}" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
option_type_idRequiredVariable used inside the request path.
Headers
AuthorizationOptionalBearer {{access_token}}
JWT token for authenticated requests (required)
Responses
1{2 "success": true,3 "message": "Variant option type deleted successfully"4}1{2 "error": "Cannot delete system option types"3}1{2 "error": "Cannot delete option type that is being used by products"3}1{2 "error": "Access denied. Can only delete options for your own tenant."3}1{2 "error": "Variant option type not found"3}