This guide explains how to create different product types using the Create Product endpoint.

All product types are created using the same endpoint:

The request body changes depending on the product type or product_class.

Some product types can be created with a single request. Others, such as Dynamic Bundle products, require an additional API request after the product is created.

💡

Overview

Use the Create Product endpoint to create:

Standard products

Grouped products

Voucher products

Downloadable products

Crowdfunding projects

Donation items

Customizable products

Dynamic Bundle products

Each product type has different requirements, rules, and supported fields.

Authentication

The following headers may be required when creating or updating products:

Header	Required	Description
`Authorization`	Yes	Bearer JWT for scope-based authentication.
`X-Manager-Token`	Yes	Encrypted manager token.
`Store-Id`	Yes	Store UUID.
`Role`	Yes	Must be set to `Manager`.
`Content-Type`	Yes	Must be `application/json`.

Example:

Product class summary

Product Type	`product_class` Value	Use Case	Additional Step Required
Standard Product	Not required	Regular physical or digital product.	No
Grouped Product	`grouped_product`	Sell multiple existing products together as one product.	No
Voucher Product	`voucher`	Gift cards, license keys, or digital redemption products.	May require voucher setup after creation.
Downloadable Product	`downloadable`	Digital file products such as e-books or documents.	Files are managed separately after product creation.
Crowdfunding Project	`crowdfunding_project`	Fundraising product with goal tracking.	No
Donation Item	`donation_item`	Donation campaign with unit-based tracking.	No
Customizable Product	Not required	Product with custom input fields or predefined options.	No
Dynamic Bundle	`dynamic_bundle`	Bundle where customers select items from configured groups.	Yes. Selection groups must be added separately.

Common product fields

The following fields are commonly used when creating products.

Field	Type	Required	Description
`name`	object/string	Yes	Product name. Supports an i18n object such as `{ "ar": "...", "en": "..." }` or a plain string.
`description`	object/string	No	Product description. Supports an i18n object or a plain string.
`short_description`	object/string	No	Short product description.
`product_class`	string	Conditional	Defines the product type. Not required for standard or customizable products.
`sku`	string	No	Product SKU.
`barcode`	string	No	Product barcode.
`price`	number	Yes	Product price. Some product classes have specific price rules.
`sale_price`	number	No	Discounted product price. Not supported by some product classes.
`cost`	number	No	Product cost.
`quantity`	integer	Conditional	Product quantity. Some product classes calculate or manage quantity automatically.
`is_infinite`	boolean	No	Whether the product has unlimited quantity. Not supported by some product classes.
`is_taxable`	boolean	No	Whether the product is taxable.
`requires_shipping`	boolean	No	Whether the product requires shipping.
`weight`	object	Conditional	Product weight. Required when shipping is enabled.
`is_draft`	boolean	No	Whether the product is saved as draft.
`is_published`	boolean	No	Whether the product is published.
`keywords`	array	No	Product keywords.
`seo`	object	No	SEO title and description.
`badge`	object	No	Product badge details.
`meta`	object	Conditional	Product-type-specific metadata.
`stocks`	array	Conditional	Product stock by inventory location.
`group_products`	array	Conditional	Required for grouped products.
`custom_user_input_fields`	array	No	Customer free-input fields.
`custom_option_fields`	array	No	Customer predefined option fields.

Note: Categories cannot be added during product creation. To assign a product to one or more categories, use the category assignment endpoints after the product is created.

1. Create a Standard Product

Use a standard product for regular physical or digital products.

A standard product does not require a product_class value.

Request

{
  "name": {
    "ar": "منتج عادي",
    "en": "Standard Product"
  },
  "description": {
    "ar": "منتج عادي عام",
    "en": "A regular general product"
  },
  "sku": "STANDARD-001",
  "barcode": "1234567890128",
  "price": 99.99,
  "sale_price": 79.99,
  "quantity": 100,
  "is_taxable": true,
  "requires_shipping": true,
  "weight": {
    "value": 2.5,
    "unit": "kg"
  },
  "is_draft": false,
  "is_published": true,
  "keywords": [
    "product",
    "standard"
  ]
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "منتج عادي",
    "en": "Standard Product"
  },
  "description": {
    "ar": "منتج عادي عام",
    "en": "A regular general product"
  },
  "sku": "STANDARD-001",
  "barcode": "1234567890128",
  "product_class": null,
  "price": 99.99,
  "sale_price": 79.99,
  "quantity": 100,
  "is_infinite": false,
  "is_taxable": true,
  "requires_shipping": true,
  "is_draft": false,
  "is_published": true,
  "weight": {
    "value": 2.5,
    "unit": "kg"
  },
  "meta": {},
  "variants": [],
  "custom_user_input_fields": [],
  "custom_option_fields": [],
  "created_at": "2026-06-10T10:00:00Z",
  "updated_at": "2026-06-10T10:00:00Z"
}

2. Create a Grouped Product

Use a grouped product to sell multiple existing products together as one product.

Set:

"product_class": "grouped_product"

Grouped products use the group_products array to define which products are included and how many units of each product are part of the group.

Request

{
  "name": {
    "ar": "منتج مجمع",
    "en": "Grouped Product"
  },
  "description": {
    "ar": "منتج يحتوي على عدة منتجات مرتبطة",
    "en": "A product that includes multiple related products"
  },
  "product_class": "grouped_product",
  "sku": "GROUPED-001",
  "price": 299.99,
  "is_draft": false,
  "is_published": true,
  "requires_shipping": true,
  "stocks": [
    {
      "location": "location-uuid-here",
      "available_quantity": 50,
      "is_infinite": false
    }
  ],
  "group_products": [
    {
      "item_id": "product-uuid-1",
      "item_quantity": 2
    },
    {
      "item_id": "product-uuid-2",
      "item_quantity": 1
    },
    {
      "item_id": "product-uuid-3",
      "item_quantity": 3
    }
  ],
  "weight": {
    "value": 5,
    "unit": "kg"
  }
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "منتج مجمع",
    "en": "Grouped Product"
  },
  "product_class": "grouped_product",
  "sku": "GROUPED-001",
  "price": 299.99,
  "requires_shipping": true,
  "is_draft": false,
  "is_published": true,
  "group_products": [
    {
      "item_id": "product-uuid-1",
      "item_quantity": 2
    },
    {
      "item_id": "product-uuid-2",
      "item_quantity": 1
    },
    {
      "item_id": "product-uuid-3",
      "item_quantity": 3
    }
  ],
  "stocks": [
    {
      "location": "location-uuid-here",
      "available_quantity": 50,
      "is_infinite": false
    }
  ]
}

Grouped product rules

group_products cannot be empty for published grouped products.

All included products must exist in the store.

All included products must have stock in the same location.

Only published products can be added to a published grouped product.

Weight is calculated automatically from the included products.

Quantity is calculated based on the minimum available units relative to the selected item quantities.

3. Create a Voucher Product

Use a voucher product for gift cards, license keys, or digital redemption products.

Set:

"product_class": "voucher"

Voucher products are digital products and do not require shipping.

Request

{
  "name": {
    "ar": "بطاقة هدية",
    "en": "Gift Card"
  },
  "description": {
    "ar": "بطاقة هدية رقمية بقيمة 100 ريال",
    "en": "Digital gift card worth 100 SAR"
  },
  "product_class": "voucher",
  "sku": "VOUCHER-001",
  "price": 100,
  "is_taxable": false,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {}
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "بطاقة هدية",
    "en": "Gift Card"
  },
  "description": {
    "ar": "بطاقة هدية رقمية بقيمة 100 ريال",
    "en": "Digital gift card worth 100 SAR"
  },
  "product_class": "voucher",
  "sku": "VOUCHER-001",
  "price": 100,
  "is_taxable": false,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {}
}

Voucher product rules

Voucher products automatically set requires_shipping to false.

Voucher products cannot have infinite quantity.

Voucher products cannot have sale_price.

Quantity is handled internally.

The meta field can be used for extension data.

4. Create a Downloadable Product

Use a downloadable product for digital files such as e-books, documents, or other downloadable assets.

Set:

"product_class": "downloadable"

Downloadable files are managed separately after product creation.

Request

{
  "name": {
    "ar": "كتاب إلكتروني",
    "en": "E-Book"
  },
  "description": {
    "ar": "كتاب الدليل الشامل",
    "en": "Complete Guide E-Book"
  },
  "product_class": "downloadable",
  "sku": "EBOOK-001",
  "price": 29.99,
  "is_taxable": false,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "download_limit": 5,
    "expiration_period": 30
  }
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "كتاب إلكتروني",
    "en": "E-Book"
  },
  "product_class": "downloadable",
  "sku": "EBOOK-001",
  "price": 29.99,
  "is_taxable": false,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "download_limit": 5,
    "expiration_period": 30
  }
}

Meta properties

Field	Type	Required	Description
`download_limit`	integer	No	Maximum number of downloads allowed.
`expiration_period`	integer	No	Number of days before the download link expires.

Downloadable product rules

Downloadable products automatically set is_infinite to true.

Quantity cannot be overridden.

Downloadable products cannot be shipped.

Files are managed separately after product creation.

5. Create a Crowdfunding Project

Use a crowdfunding project to collect funds toward a target amount.

Set:

"product_class": "crowdfunding_project"

Crowdfunding products use the meta object to define the funding goal and progress display settings.

Request

{
  "name": {
    "ar": "تمويل مشروع البئر",
    "en": "Well Drilling Project"
  },
  "description": {
    "ar": "تمويل حفر بئر مياه نظيفة في قرية نائية",
    "en": "Fundraising for drilling a clean water well"
  },
  "product_class": "crowdfunding_project",
  "sku": "CROWDFUND-001",
  "price": 1,
  "is_taxable": true,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "project_goal_amount": 5000,
    "project_external_collected_amount": 1000,
    "show_progress_bar": true,
    "show_progress_percentage": true,
    "show_collected_amount": true,
    "is_open_donation": false
  }
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "تمويل مشروع البئر",
    "en": "Well Drilling Project"
  },
  "product_class": "crowdfunding_project",
  "sku": "CROWDFUND-001",
  "price": 1,
  "is_taxable": true,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "project_goal_amount": 5000,
    "project_external_collected_amount": 1000,
    "show_progress_bar": true,
    "show_progress_percentage": true,
    "show_collected_amount": true,
    "is_open_donation": false
  }
}

Meta properties

Field	Type	Required	Description
`project_goal_amount`	integer	Yes	Total amount required to complete the project.
`project_external_collected_amount`	integer	No	Amount already collected outside Zid.
`show_progress_bar`	boolean	No	Shows or hides the progress bar.
`show_progress_percentage`	boolean	No	Shows or hides the progress percentage.
`show_collected_amount`	boolean	No	Shows or hides the collected amount.
`is_open_donation`	boolean	No	Allows donations without a fixed goal. When enabled, the goal amount is hidden.

Crowdfunding project rules

The price is fixed at 1.

Quantity represents the remaining amount needed.

Crowdfunding products cannot have sale_price.

Crowdfunding products cannot have infinite quantity.

Crowdfunding products cannot be shipped.

6. Create a Donation Item

Use a donation item for donation campaigns with unit-based progress tracking.

Set:

"product_class": "donation_item"

Donation items use the meta object to define total units, externally purchased units, and progress display settings.

Request

{
  "name": {
    "ar": "وجبة غداء للفقراء",
    "en": "Lunch Meal for the Poor"
  },
  "description": {
    "ar": "وجبة غداء صحية متكاملة",
    "en": "Complete healthy meal"
  },
  "product_class": "donation_item",
  "sku": "DONATION-001",
  "price": 25,
  "is_taxable": true,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "total_units": 200,
    "external_purchased_units": 50,
    "show_progress_bar": true,
    "show_progress_percentage": true,
    "show_purchased_units": true,
    "is_open_donation": false
  }
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "وجبة غداء للفقراء",
    "en": "Lunch Meal for the Poor"
  },
  "product_class": "donation_item",
  "sku": "DONATION-001",
  "price": 25,
  "is_taxable": true,
  "requires_shipping": false,
  "is_draft": false,
  "is_published": true,
  "meta": {
    "total_units": 200,
    "external_purchased_units": 50,
    "show_progress_bar": true,
    "show_progress_percentage": true,
    "show_purchased_units": true,
    "is_open_donation": false
  }
}

Meta properties

Field	Type	Required	Description
`total_units`	integer	Yes	Total number of donation units available.
`external_purchased_units`	integer	No	Units already purchased outside Zid.
`show_progress_bar`	boolean	No	Shows or hides the progress bar.
`show_progress_percentage`	boolean	No	Shows or hides the progress percentage.
`show_purchased_units`	boolean	No	Shows or hides the number of purchased units.
`is_open_donation`	boolean	No	Allows donations without a fixed unit goal.

Donation item rules

Quantity is automatically set based on total_units.

Donation items cannot have sale_price.

Donation items cannot have infinite quantity.

Donation items cannot be shipped.

7. Create a Customizable Product

Use a customizable product when customers need to provide custom input or select predefined options before adding the product to cart.

Customizable products can include:

custom_user_input_fields

custom_option_fields

Use custom_user_input_fields for free input fields such as text, number, URL, file, image, date, or time.

Use custom_option_fields for predefined options such as dropdowns or checkboxes.

A customizable product does not require a specific product_class value.

Request

{
  "name": {
    "ar": "كعكة الزفاف المخصصة",
    "en": "Custom Wedding Cake"
  },
  "description": {
    "ar": "كعكة زفاف قابلة للتخصيص مع اسم العروسين",
    "en": "Customizable wedding cake with couple names"
  },
  "sku": "CAKE-001",
  "price": 299.99,
  "is_draft": false,
  "is_published": true,
  "requires_shipping": true,
  "custom_user_input_fields": [
    {
      "type": "TEXT",
      "label": {
        "ar": "اسم العريس",
        "en": "Groom Name"
      },
      "hint": {
        "ar": "أدخل اسم العريس",
        "en": "Enter groom's name"
      },
      "is_required": true,
      "price": 0,
      "display_order": 1,
      "is_published": true
    },
    {
      "type": "TEXT",
      "label": {
        "ar": "اسم العروس",
        "en": "Bride Name"
      },
      "hint": {
        "ar": "أدخل اسم العروس",
        "en": "Enter bride's name"
      },
      "is_required": true,
      "price": 0,
      "display_order": 2,
      "is_published": true
    },
    {
      "type": "NUMBER",
      "label": {
        "ar": "عدد الأشخاص",
        "en": "Number of Guests"
      },
      "hint": {
        "ar": "أدخل عدد الأشخاص",
        "en": "Enter number of guests"
      },
      "is_required": true,
      "price": 50,
      "display_order": 3,
      "is_published": true
    }
  ],
  "custom_option_fields": [
    {
      "type": "select",
      "label": {
        "ar": "نكهة الكعكة",
        "en": "Cake Flavor"
      },
      "hint": {
        "ar": "اختر نكهة الكعكة",
        "en": "Choose cake flavor"
      },
      "is_required": true,
      "can_choose_multiple_options": false,
      "display_order": 1,
      "is_published": true,
      "choices": [
        {
          "id": "flavor-1",
          "ar": "فانيليا كلاسيكية",
          "en": "Classic Vanilla",
          "price": 0
        },
        {
          "id": "flavor-2",
          "ar": "شوكولاتة داكنة",
          "en": "Dark Chocolate",
          "price": 25
        },
        {
          "id": "flavor-3",
          "ar": "فراولة",
          "en": "Strawberry",
          "price": 20
        }
      ]
    },
    {
      "type": "select",
      "label": {
        "ar": "نوع الحشوة",
        "en": "Filling Type"
      },
      "hint": {
        "ar": "اختر نوع الحشوة",
        "en": "Choose filling type"
      },
      "is_required": true,
      "can_choose_multiple_options": false,
      "display_order": 2,
      "is_published": true,
      "choices": [
        {
          "id": "filling-1",
          "ar": "كريمة",
          "en": "Cream",
          "price": 0
        },
        {
          "id": "filling-2",
          "ar": "فاكهة",
          "en": "Fruit",
          "price": 15
        }
      ]
    }
  ]
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "كعكة الزفاف المخصصة",
    "en": "Custom Wedding Cake"
  },
  "sku": "CAKE-001",
  "product_class": null,
  "price": 299.99,
  "is_draft": false,
  "is_published": true,
  "requires_shipping": true,
  "custom_user_input_fields": [
    {
      "id": "custom-field-uuid-1",
      "type": "TEXT",
      "label": {
        "ar": "اسم العريس",
        "en": "Groom Name"
      },
      "hint": {
        "ar": "أدخل اسم العريس",
        "en": "Enter groom's name"
      },
      "is_required": true,
      "price": 0,
      "display_order": 1,
      "is_published": true
    }
  ],
  "custom_option_fields": [
    {
      "id": "option-field-uuid-1",
      "label": {
        "ar": "نكهة الكعكة",
        "en": "Cake Flavor"
      },
      "hint": {
        "ar": "اختر نكهة الكعكة",
        "en": "Choose cake flavor"
      },
      "is_required": true,
      "can_choose_multiple_options": false,
      "display_order": 1,
      "is_published": true,
      "choices": [
        {
          "id": "flavor-1",
          "ar": "فانيليا كلاسيكية",
          "en": "Classic Vanilla",
          "price": 0
        }
      ]
    }
  ]
}

Custom user input field parameters

Field	Type	Required	Description
`type`	string	Yes	Field type. Must be uppercase.
`label`	object/string	Yes	Field label. Accepts an i18n object or plain string.
`hint`	object/string	No	Helper text shown to the customer.
`is_required`	boolean	No	Whether the customer must complete the field.
`price`	number	No	Additional price added when the field is used. Defaults to `0`.
`display_order`	integer	No	Display order of the field.
`is_published`	boolean	No	Whether the field is visible to customers.

Supported custom_user_input_fields[].type values:

Type
`TEXT`
`NUMBER`
`URL`
`FILE`
`IMAGE`
`DATE`
`TIME`

Custom option field parameters

Field	Type	Required	Description
`type`	string	No	Ignored by the API. The option type is derived from `can_choose_multiple_options`.
`label`	object/string	Yes	Field label. Accepts an i18n object or plain string.
`hint`	object/string	No	Helper text shown to the customer.
`is_required`	boolean	No	Whether the customer must select an option.
`can_choose_multiple_options`	boolean	No	Determines whether the field behaves as a dropdown or checkbox group.
`display_order`	integer	No	Display order of the field.
`is_published`	boolean	No	Whether the field is visible to customers.
`choices`	array	Yes	List of predefined choices.

Custom option choice parameters

Field	Type	Required	Description
`id`	string	No	Choice identifier. If omitted, it is generated automatically.
`ar`	string	Conditional	Arabic choice label.
`en`	string	Conditional	English choice label.
`price`	number	No	Additional price for the choice. Defaults to `0`.

Customizable product rules

custom_user_input_fields are used for free input fields.

custom_option_fields are used for predefined choices.

custom_user_input_fields[].type must be uppercase.

Lowercase values such as text will be rejected.

custom_option_fields[].type is ignored because the field type is derived from can_choose_multiple_options.

If can_choose_multiple_options is false, the option field behaves like a dropdown.

If can_choose_multiple_options is true, the option field behaves like a checkbox field.

choices[].id is optional. If omitted, it is generated automatically.

choices[].price defaults to 0 if it is not provided.

Each custom option field can have a maximum of 30 choices.

label is required for both field types.

label accepts either an i18n object or a plain string.

Custom fields can be sent inline during product creation or product update.

When updating existing fields, include id to update the field.

To remove an existing field, send is_deleted: true.

8. Create a Dynamic Bundle Product

Use a Dynamic Bundle product when customers need to select items from one or more selection groups.

Set:

"product_class": "dynamic_bundle"

Dynamic Bundle products require two API requests:

Create the Dynamic Bundle product using POST /v1/products/

Add selection groups using PATCH /v1/products/{product_id}/selection-groups/bulk-patch/

If the product is created as a draft, use this flow:

Create the product as draft using POST /v1/products/

Add selection groups using PATCH /v1/products/{product_id}/selection-groups/bulk-patch/

Publish the product using PATCH /v1/products/{id}/

Step 1: Create the Dynamic Bundle product

{
  "name": {
    "ar": "حزمة البناء المخصصة",
    "en": "Custom Build Bundle"
  },
  "description": {
    "ar": "اختر المكونات الخاصة بك لإنشاء حزمة فريدة",
    "en": "Choose your components to create a unique bundle"
  },
  "product_class": "dynamic_bundle",
  "sku": "BUNDLE-001",
  "price": 0,
  "is_draft": false,
  "is_published": false,
  "requires_shipping": true,
  "meta": {
    "location_id": "dd125776-70d1-4819-934c-a29b8ebd18ca"
  }
}

Successful response example

{
  "id": "product-uuid",
  "name": {
    "ar": "حزمة البناء المخصصة",
    "en": "Custom Build Bundle"
  },
  "description": {
    "ar": "اختر المكونات الخاصة بك لإنشاء حزمة فريدة",
    "en": "Choose your components to create a unique bundle"
  },
  "product_class": "dynamic_bundle",
  "sku": "BUNDLE-001",
  "price": 0,
  "is_draft": false,
  "is_published": false,
  "requires_shipping": true,
  "meta": {
    "location_id": "dd125776-70d1-4819-934c-a29b8ebd18ca"
  },
  "selection_groups": []
}

Dynamic Bundle product rules

price: 0 is commonly used because the final price is calculated from the selected bundle items.

meta.location_id should match the inventory location where all bundle items have stock.

Dynamic Bundle products require selection groups before they can be published.

Use is_draft: true if you want to create the product first and add selection groups later.

All bundle items must have stock in the same location_id.

Step 2: Add selection groups

Use the bulk patch selection groups endpoint to add, update, or delete selection groups for the Dynamic Bundle product.

Request body

{
  "location_id": "dd125776-70d1-4819-934c-a29b8ebd18ca",
  "selection_groups": [
    {
      "name": {
        "ar": "اختر اللون",
        "en": "Choose Color"
      },
      "required_selection_count": 1,
      "allow_duplicate_items": false,
      "items": [
        {
          "item_id": "standalone-product-uuid"
        },
        {
          "item_id": "parent-product-uuid",
          "variant_ids": [
            "variant-child-uuid-1",
            "variant-child-uuid-2"
          ]
        }
      ]
    }
  ]
}

Successful response example

{
  "id": "product-uuid",
  "product_class": "dynamic_bundle",
  "selection_groups": [
    {
      "selection_group_id": "selection-group-uuid",
      "name": {
        "ar": "اختر اللون",
        "en": "Choose Color"
      },
      "required_selection_count": 1,
      "allow_duplicate_items": false,
      "items": [
        {
          "item_id": "standalone-product-uuid",
          "variant_ids": null
        },
        {
          "item_id": "parent-product-uuid",
          "variant_ids": [
            "variant-child-uuid-1",
            "variant-child-uuid-2"
          ]
        }
      ]
    }
  ]
}

Selection group body parameters

Field	Type	Required	Description
`location_id`	string	Yes	Inventory location UUID. All bundle items must have stock in this location.
`selection_groups`	array	Yes	List of selection groups to add, update, or delete.
`selection_groups[].selection_group_id`	string	No	Existing selection group UUID. Include only when updating or deleting an existing group.
`selection_groups[].name`	object/string	Yes	Selection group name. Accepts an i18n object or a plain string.
`selection_groups[].required_selection_count`	integer	Yes	Number of items the customer must select from this group. Must be less than or equal to the number of items in the group.
`selection_groups[].allow_duplicate_items`	boolean	No	Determines whether duplicate items are allowed. Defaults to `false`.
`selection_groups[].items`	array	Yes	List of products available for selection in the group.
`selection_groups[].items[].item_id`	string	Yes	Product UUID of the item added to the selection group.
`selection_groups[].items[].variant_ids`	array/null	Conditional	Required when `item_id` belongs to a parent product with options or variants. Omit or set to `null` for standalone products.
`selection_groups[].is_deleted`	boolean	No	Set to `true` to delete an existing selection group. Use only with `selection_group_id`.

Dynamic Bundle item rules

Standalone products

If the item is a standalone product with no variants, send only item_id.

{
  "item_id": "1be029e1-b627-48db-88ab-1c6595428915"
}

You can omit variant_ids entirely or set it to null.

Parent products with variants

If the item is a parent product that has options or variants, variant_ids is required.

{
  "item_id": "parent-product-uuid",
  "variant_ids": [
    "variant-uuid-1",
    "variant-uuid-2"
  ]
}

If a parent product is sent without variant_ids, the API returns an error because at least one child variant must be selected.

Full Dynamic Bundle selection group example

{
  "location_id": "dd125776-70d1-4819-934c-a29b8ebd18ca",
  "selection_groups": [
    {
      "name": {
        "ar": "اختر اللون",
        "en": "Choose Color"
      },
      "required_selection_count": 1,
      "allow_duplicate_items": false,
      "items": [
        {
          "item_id": "standalone-product-uuid"
        },
        {
          "item_id": "parent-product-uuid",
          "variant_ids": [
            "variant-child-uuid-1",
            "variant-child-uuid-2"
          ]
        }
      ]
    },
    {
      "name": {
        "ar": "اختر المقاس",
        "en": "Choose Size"
      },
      "required_selection_count": 1,
      "allow_duplicate_items": false,
      "items": [
        {
          "item_id": "another-product-uuid"
        }
      ]
    }
  ]
}

Step 3: Publish the Dynamic Bundle product

If the Dynamic Bundle product was created as a draft, publish it after adding selection groups.

Example request:

{
  "is_draft": false,
  "is_published": true
}

The product must contain at least one valid selection group before it can be published.

Complete product example

The following example shows a product with multiple supported fields.

{
  "name": {
    "ar": "منتج شامل",
    "en": "Comprehensive Product"
  },
  "description": {
    "ar": "منتج يوضح جميع الميزات المتاحة",
    "en": "Product showcasing all available features"
  },
  "short_description": {
    "ar": "منتج شامل مع جميع الميزات",
    "en": "Comprehensive product with all features"
  },
  "sku": "FULL-001",
  "barcode": "1234567890128",
  "price": 199.99,
  "sale_price": 149.99,
  "cost": 80,
  "quantity": 100,
  "is_infinite": false,
  "is_draft": false,
  "is_published": true,
  "is_taxable": true,
  "requires_shipping": true,
  "weight": {
    "value": 1.5,
    "unit": "kg"
  },
  "keywords": [
    "product",
    "complete",
    "featured"
  ],
  "display_order": 1,
  "seo": {
    "title": {
      "ar": "منتج شامل - متجر متقدم",
      "en": "Comprehensive Product - Advanced Store"
    },
    "description": {
      "ar": "اكتشف منتجنا الشامل بميزات متقدمة",
      "en": "Discover our comprehensive product with advanced features"
    }
  },
  "purchase_restrictions": {
    "min_quantity_per_cart": 1,
    "max_quantity_per_cart": 5,
    "availability_period_start": "2024-01-01T00:00:00Z",
    "availability_period_end": "2024-12-31T23:59:59Z",
    "sale_price_period_start": "2024-01-01T00:00:00Z",
    "sale_price_period_end": "2024-03-31T23:59:59Z"
  },
  "badge": {
    "body": {
      "ar": "خصم {discount_percent}",
      "en": "Discount {discount_percent}"
    }
  }
}

Common error responses

The API may return validation errors when required fields are missing or unsupported fields are sent for a product class.

Invalid request example

{
  "message": "The given data was invalid.",
  "errors": {
    "price": [
      "The price field is required."
    ]
  }
}

Unauthorized request example

{
  "message": "Unauthenticated."
}

Forbidden request example

{
  "message": "This action is unauthorized."
}

Dynamic Bundle common errors

Error	Cause	How to Fix
`Bundle Product must contain at least 1 selection group`	The Dynamic Bundle product was published or updated before adding selection groups.	Add selection groups using the bulk patch endpoint before publishing the product.
`No location found with the given ID=None`	`location_id` is missing from the request body.	Add `location_id` at the top level of the request body.
`For products with options, at least one variant must be selected`	The selected `item_id` belongs to a parent product with variants.	Add `variant_ids` with at least one child variant UUID.
`A selection group must have at least 1 item`	The `items` array is empty.	Add at least one item to the selection group.
`required_selection_count must be less than or equal to items count`	The required selection count is greater than the number of available items.	Reduce `required_selection_count` or add more items to the group.
`Location ID must be specified for dynamic bundle product`	`meta.location_id` is missing from the product or `location_id` is missing from the bulk patch request.	Add the location ID in both the product metadata and the selection group request.
`All items in a dynamic bundle must have quantity in the same location`	One or more items do not have stock in the selected location.	Make sure every item has stock in the specified `location_id`.
`You can't add more than 10 selection groups`	The request includes more than 10 selection groups.	Keep the number of selection groups to 10 or fewer.
`Product [uuid] has no stock`	The selected item does not have stock in the bundle location.	Add stock for the product in the selected location.

Dynamic Bundle validation error example

{
  "message": "For products with options, at least one variant must be selected",
  "errors": {
    "selection_groups.0.items.1.variant_ids": [
      "For products with options, at least one variant must be selected"
    ]
  }
}

Method	Endpoint	Purpose
`POST`	`/v1/products/`	Create a product.
`PATCH`	`/v1/products/{id}/`	Update product fields or publish a product.
`PATCH`	`/v1/products/{product_id}/selection-groups/bulk-patch/`	Add, update, or delete Dynamic Bundle selection groups.
`GET`	`/v1/products/{id}/`	Retrieve product details.
`GET`	`/v1/products/`	List products.

Best practices

Use the correct product_class value for the product type.

Do not send product_class for standard products unless required by your implementation.

Do not add categories during product creation. Assign categories after the product is created.

For Dynamic Bundle products, always add selection groups before publishing.

For Dynamic Bundle items with variants, include at least one valid child variant UUID in variant_ids.

Make sure all Dynamic Bundle items have stock in the same location_id.

Keep Dynamic Bundle selection groups to 10 or fewer.

Use is_draft: true when you need to create a product first and complete its configuration later.

Use actual product UUIDs, variant UUIDs, and location UUIDs from the store when testing requests.

Use the API response from your testing environment as the final source of truth for exact field names and response structure.

Create Product Types

Overview#

Authentication#

Product class summary#

Common product fields#

1. Create a Standard Product#

Request#

Successful response example#

2. Create a Grouped Product#

Request#

Successful response example#

Grouped product rules#

3. Create a Voucher Product#

Request#

Successful response example#

Voucher product rules#

4. Create a Downloadable Product#

Request#

Successful response example#

Meta properties#

Downloadable product rules#

5. Create a Crowdfunding Project#

Request#

Successful response example#

Meta properties#

Crowdfunding project rules#

6. Create a Donation Item#

Request#

Successful response example#

Meta properties#

Donation item rules#

7. Create a Customizable Product#

Request#

Successful response example#

Custom user input field parameters#

Custom option field parameters#

Custom option choice parameters#

Customizable product rules#

8. Create a Dynamic Bundle Product#

Step 1: Create the Dynamic Bundle product#

Successful response example#

Dynamic Bundle product rules#

Step 2: Add selection groups#

Request body#

Successful response example#

Selection group body parameters#

Dynamic Bundle item rules#

Standalone products#

Parent products with variants#

Full Dynamic Bundle selection group example#

Step 3: Publish the Dynamic Bundle product#

Complete product example#

Common error responses#

Invalid request example#

Unauthorized request example#

Forbidden request example#

Dynamic Bundle common errors#

Dynamic Bundle validation error example#

Related endpoints#

Best practices#

Overview

Authentication

Product class summary

Common product fields

1. Create a Standard Product

Request

Successful response example

2. Create a Grouped Product

Request

Successful response example

Grouped product rules

3. Create a Voucher Product

Request

Successful response example

Voucher product rules

4. Create a Downloadable Product

Request

Successful response example

Meta properties

Downloadable product rules

5. Create a Crowdfunding Project

Request

Successful response example

Meta properties

Crowdfunding project rules

6. Create a Donation Item

Request

Successful response example

Meta properties

Donation item rules

7. Create a Customizable Product

Request

Successful response example

Custom user input field parameters

Custom option field parameters

Custom option choice parameters

Customizable product rules

8. Create a Dynamic Bundle Product

Step 1: Create the Dynamic Bundle product

Successful response example

Dynamic Bundle product rules

Step 2: Add selection groups

Request body

Successful response example

Selection group body parameters

Dynamic Bundle item rules

Standalone products

Parent products with variants

Full Dynamic Bundle selection group example

Step 3: Publish the Dynamic Bundle product

Complete product example

Common error responses

Invalid request example

Unauthorized request example

Forbidden request example

Dynamic Bundle common errors

Dynamic Bundle validation error example

Related endpoints

Best practices