Variant Option Types Management

5 API calls in this section.

List Variant Option Types

Storefront & Commerce / Variant Option Types Management

GET/storefront/variant-option-types

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.

• Required: Valid Bearer token with tenant access

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

Query parameters

Parameter	Type	Description
include_systemOptional	string	Include system-wide option types (default: true) Include system-wide option types like colors, size, volume (default: true) Include system-wide option types (default: true) Include system-wide option types like colors, size, volume (default: true) Example: true
include_customOptional	string	Include tenant-specific custom option types (default: true) Include tenant-specific custom option types (default: true) Example: true
tenant_idOptional	string	Tenant ID for custom options (optional, defaults to user's tenant) Specific tenant ID for custom options (defaults to user's tenant) Tenant ID for custom options (optional, defaults to user's tenant) Specific tenant ID for custom options (defaults to user's tenant) Example: {{tenant_id}}

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated requests (required) JWT token for authenticated requests (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/variant-option-types?include_system=true&include_custom=true&tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Mixed Option Types200 · Success - System Options Only401 · Error - Unauthorized

200OK

Response body

json

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}

Create Custom Variant Option Type

Storefront & Commerce / Variant Option Types Management

POST/storefront/variant-option-types

Creates a new custom variant option type for the tenant. Custom option types allow businesses to define specific variant attributes beyond the standard system options.

• 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

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated requests (required) JWT token for authenticated requests (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
name	string	—
display_name	object	—
display_name.en	string	—
display_name.ar	string	—
display_name.ku	string	—
tenant_id	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/variant-option-types" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": "storage",6  "display_name": {7    "en": "Storage Capacity",8    "ar": "سعة التخزين",9    "ku": "قەبارەی هەڵگرتن"10  },11  "tenant_id": "{{tenant_id}}"12}'

Replace {{placeholders}} with your own values before sending.

Response examples

201 · Success - Custom Option Created400 · Error - Validation Failed400 · Error - Invalid Name Format409 · Error - Name Conflicts with System Option409 · Error - Name Already Exists403 · Error - Access Denied

201Created

Response body

json

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}

Get Variant Option Type

Storefront & Commerce / Variant Option Types Management

GET/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.

• Required: Valid Bearer token with tenant access

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

Path parameters

Parameter	Type	Description
option_type_idRequired	string	UUID of the variant option type to retrieve UUID of the variant option type to retrieve

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated requests (required) JWT token for authenticated requests (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/variant-option-types/${OPTION_TYPE_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - System Option Type200 · Success - Custom Option Type404 · Error - Option Type Not Found

200OK

Response body

json

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}

Update Variant Option Type

Storefront & Commerce / Variant Option Types Management

PUT/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.

• Required: Valid Bearer token with tenant access

• Permission: Only tenant members can update their own custom options

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

Path parameters

Parameter	Type	Description
option_type_idRequired	string	UUID of the variant option type to update UUID of the variant option type to update

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated requests (required) JWT token for authenticated requests (required) Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
display_name	object	—
display_name.en	string	—
display_name.ar	string	—
display_name.ku	string	—
is_active	boolean	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/variant-option-types/${OPTION_TYPE_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "display_name": {6    "en": "Storage Memory",7    "ar": "ذاكرة التخزين",8    "ku": "یادگەی هەڵگرتن"9  },10  "is_active": true11}'

Response examples

200 · Success - Option Type Updated403 · Error - Cannot Modify System Options403 · Error - Access Denied404 · Error - Option Type Not Found

200OK

Response body

json

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}

Delete Variant Option Type

Storefront & Commerce / Variant Option Types Management

DELETE/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.

• Required: Valid Bearer token with tenant access

• Permission: Only tenant members can delete their own custom options

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

Path parameters

Parameter	Type	Description
option_type_idRequired	string	UUID of the variant option type to delete UUID of the variant option type to delete

Headers

Parameter	Type	Description
AuthorizationRequired	string	JWT token for authenticated requests (required) JWT token for authenticated requests (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/variant-option-types/${OPTION_TYPE_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Option Type Deleted403 · Error - Cannot Delete System Options409 · Error - Option Type In Use403 · Error - Access Denied404 · Error - Option Type Not Found

200OK

Response body

json

1{2  "success": true,3  "message": "Variant option type deleted successfully"4}