Create Product Variants

This endpoint allows adding or creating variants for a given product. If the specified product is a standalone product (does not have any variants), this operation will convert it into a parent product.

Steps to Create Variants:

1. Create Product Attributes: Create product attributes for the store using the add a new product attribute endpoint.

2. Define Attribute Choices: Define choices (presets) for these attributes using the Create attribute preset Endpoint.

For example, for a size attribute, choices might include 'small', 'medium', 'large', etc. Each choice is an object that accepts values in multiple languages. Currently, English and Arabic are supported. (If a choice is already created, no need to create it again).

3. Variant Generation: Send the details of variants you want to create using this endpoint. Refer to the example request payload below for the required structure.

🔑Scopes

products.read_write - Products Read & Write

Request

Path Params

Header Params

Body Params application/json

Example

{
    "variants": [
        {
            "id": "ebd067c3-6c51-4692-9cac-e43118930ec2",
            "is_deleted": false,
            "sku": "Z.6.1905460000038147819",
            "price": 144,
            "sale_price": null,
            "cost": null,
            "barcode": null,
            "attributes": [
                {
                    "slug": "اللون",
                    "value": {
                        "ar": "ابيض",
                        "en": "White"
                    }
                }
            ],
            "stocks": [
                {
                    "available_quantity": 44,
                    "is_infinite": false,
                    "location": "e2629f14-12ad-4ee4-8103-9db7290c4ccc"
                }
            ],
            "weight": {
                "unit": "kg",
                "value": null
            }
        },
        {
            "is_deleted": false,
            "sku": "Z.6.1905460000038147869",
            "price": 144,
            "sale_price": 122,
            "cost": null,
            "barcode": null,
            "attributes": [
                {
                    "slug": "اللون",
                    "value": {
                        "ar": "اسود",
                        "en": "Black"
                    }
                }
            ],
            "stocks": [
                {
                    "available_quantity": 77,
                    "is_infinite": false,
                    "location": "e2629f14-12ad-4ee4-8103-9db7290c4ccc"
                }
            ],
            "weight": {
                "unit": "kg",
                "value": null
            }
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.zid.sa/v1/products//variants/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxMTciLCJqdGkiOiJhMTg5ZTg3MmYxMzhkMWVhYjU5MjVkMDkyMGE5NmI0YjliNjg0Y2E2ZTdmM2M2MjljZWYxNmQ4NDJjMmJlYmVhMjI4YTdmMTA0ZWQ4NWE5NCIsImlhdCI6MTY3OTU3Njk5OS41NjY4NzcsIm5iZiI6MTY3OTU3Njk5OS41NjY4OCwiZXhwIjoxNzExMTk5Mzk5LjQ4NjE1Mywic3ViIjoiMTgyNDc1Iiwic2NvcGVzIjpbInRoaXJkLXBhcnRpZXMtYXBpcyJdfQ.i07ef09nVNXGZF-g-QXpNoS2vlFQK_zntAqAMS4Az2XD2EyMLhxLZZRL-QlR11zUPqMmXjMAl_4ooKa3M3zkfZQ6Ga6qStvamk8RnC_39VUx0lfN2A4k65ERZpqwrMy6-t3dE99zay3aicIdNvbgi0zeuMSE5Tn99u-2AtSRa8ffbfAcYPPXacHrhdmlYzdiZS_x_skovFEow1E-nDjdL1WHqO92XdZ7RfNLkiYFTjZlZmM_UruvioaR3q6TXJbqRK_ZrziivezL8ohIQ2SBosUp58I29rlKzvlw_R2j0rKKYZbdxYDaxAHOISmOFKAlO66k7dNevAHI3s4uGIjoGA6ZXHknccWPLLLiaAQ0r64HV8GowW5dg2rhZNurJGDTnLlBQ6F-ql42ptHzSAfzzi576CEoN3gMVpgXcbntUY3reETkFsTBPUjeSuMpANMioXAA0GRp3Ut-84fTnrWxqsCW1WVUIx33HvmfCGPXIdkaCCWoA6G6KXo04MtFbKXQmXkK9esQWI-rqdVnMD3zSR3g3yFHZSL1U-mZeNja03706Rav1ordsRNOtRwtLuoRRbk9KasbUpEwqq4Ao9lqZZwRIjdEw-pQtnUT8V53fhmuuRIefCLFO7eGEtGUnh9o6Uh_pgi6AB6uSlnN9GEMGgI1alqvMmTjxvC-HHt0V-Y' \
--header 'X-Manager-Token: eyJpdiI6Imh3L2dGbmJmRnVCOUY4WW5WQ2s3RFE9PSIsInZhbHVlIjoiZklpRnJyVGV1OWcrZUJBNk44bVp5SjZzSS92V3czcTJjbnJ2dFYvenZ3SFBtWHNSMFU3ZEMzZ0ZJNnpucVE4Ui9rNFdicUduOGpKUlg1VXdGOFFIaVUzZjZyUUZybWx3R0tNY3orUmxoUUUxQ29wSkEyVDZTVnVYb2dlUXJSVzBYVkdESjBpS0xiN05Hbndzc2wzV2N0YitGM1NEdkk4ckZZOTZsTFdEL1ZQRlJJTE5FQmttZng2elpwL1RCeXFRdUd1U3JTc0FHV1kySS80RFJaWlIyZ3gwM2FsQVRFbkt3VWtFOUQyKzdGOD0iLCJtYWMiOiJmZDQ0YzM4ODE0OWQxOWRhYWU0NDhhYmIzYzQ1MDAxMDAzODZjZGM3ZGM4NGJhMGNkMDEyYWZlM2UzYjAxMTI4IiwidGFnIjoiIn0=' \
--header 'Store-Id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "variants": [
        {
            "id": "ebd067c3-6c51-4692-9cac-e43118930ec2",
            "is_deleted": false,
            "sku": "Z.6.1905460000038147819",
            "price": 144,
            "sale_price": null,
            "cost": null,
            "barcode": null,
            "attributes": [
                {
                    "slug": "اللون",
                    "value": {
                        "ar": "ابيض",
                        "en": "White"
                    }
                }
            ],
            "stocks": [
                {
                    "available_quantity": 44,
                    "is_infinite": false,
                    "location": "e2629f14-12ad-4ee4-8103-9db7290c4ccc"
                }
            ],
            "weight": {
                "unit": "kg",
                "value": null
            }
        },
        {
            "is_deleted": false,
            "sku": "Z.6.1905460000038147869",
            "price": 144,
            "sale_price": 122,
            "cost": null,
            "barcode": null,
            "attributes": [
                {
                    "slug": "اللون",
                    "value": {
                        "ar": "اسود",
                        "en": "Black"
                    }
                }
            ],
            "stocks": [
                {
                    "available_quantity": 77,
                    "is_infinite": false,
                    "location": "e2629f14-12ad-4ee4-8103-9db7290c4ccc"
                }
            ],
            "weight": {
                "unit": "kg",
                "value": null
            }
        }
    ]
}'

Responses

🟢200Product Variants Added Successfully

application/json

Body

Example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Add or Create Product Variants Response",
  "type": "object",
  "description": "Full product object returned after successfully adding or creating variants. Includes parent product and all associated variants.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the product.",
      "example": "3c58afbb-7b07-4859-b653-b52242a33bb7"
    },
    "name": {
      "type": "object",
      "description": "Localized product name. Supports both Arabic and English.",
      "properties": {
        "ar": { "type": "string", "example": "" },
        "en": { "type": "string", "example": "" }
      }
    },
    "sku": {
      "type": "string",
      "description": "SKU (Stock Keeping Unit) identifier for the product.",
      "example": "Z.1762848292350157"
    },
    "slug": {
      "type": "string",
      "description": "Unique slug (URL-friendly identifier) for the product.",
      "example": "3c58afbb-7b07-4859-b653-b52242a33bb7"
    },
    "currency": {
      "type": "string",
      "description": "Currency code used for pricing.",
      "example": "SAR"
    },
    "currency_symbol": {
      "type": "string",
      "description": "Symbol representation of the currency.",
      "example": " SAR "
    },
    "price": {
      "type": "number",
      "description": "Base price of the product.",
      "example": 0
    },
    "sale_price": {
      "type": ["number", "null"],
      "description": "Sale or discounted price, if applicable.",
      "example": null
    },
    "formatted_price": {
      "type": "string",
      "description": "Formatted price string including currency symbol.",
      "example": " SAR 0.00"
    },
    "formatted_sale_price": {
      "type": ["string", "null"],
      "description": "Formatted sale price, if applicable.",
      "example": null
    },
    "description": {
      "type": "object",
      "description": "Localized long product description.",
      "example": {}
    },
    "short_description": {
      "type": "object",
      "description": "Localized short description.",
      "example": {}
    },
    "categories": {
      "type": "array",
      "description": "List of categories the product belongs to.",
      "items": { "type": "string" },
      "example": []
    },
    "images": {
      "type": "array",
      "description": "List of product image objects or URLs.",
      "items": { "type": "string" },
      "example": []
    },
    "videos": {
      "type": "array",
      "description": "List of product video URLs or metadata objects.",
      "example": []
    },
    "is_draft": {
      "type": "boolean",
      "description": "Indicates whether the product is in draft mode.",
      "example": true
    },
    "is_infinite": {
      "type": "boolean",
      "description": "Indicates if product has infinite stock availability.",
      "example": false
    },
    "is_taxable": {
      "type": "boolean",
      "description": "Indicates whether the product is taxable.",
      "example": true
    },
    "requires_shipping": {
      "type": "boolean",
      "description": "Whether the product requires shipping.",
      "example": true
    },
    "group_products": {
      "type": ["array", "null"],
      "description": "Array of grouped product references, if applicable.",
      "example": null
    },
    "custom_option_fields": {
      "type": "array",
      "description": "Custom option fields associated with the product.",
      "example": []
    },
    "custom_user_input_fields": {
      "type": "array",
      "description": "Custom input fields for user-provided data.",
      "example": []
    },
    "options": {
      "type": "array",
      "description": "Array of option definitions such as color, size, etc.",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "518fe604-8642-4032-b967-0be821ae235d" },
          "name": { "type": "string", "example": "Color" },
          "slug": { "type": "string", "example": "اللون" },
          "choices": {
            "type": "array",
            "description": "List of available choices for the option.",
            "items": { "type": "string" },
            "example": ["Black", "White"]
          }
        },
        "required": ["id", "name", "slug"]
      },
      "example": [
        {
          "id": "518fe604-8642-4032-b967-0be821ae235d",
          "name": "Color",
          "slug": "اللون",
          "choices": ["Black", "White"]
        }
      ]
    },
    "related_products": {
      "type": "array",
      "description": "List of related products (auto-generated or manual).",
      "example": []
    },
    "related_products_settings": {
      "type": "string",
      "description": "Defines how related products are determined (AUTO_GENERATED or MANUAL).",
      "example": "AUTO_GENERATED"
    },
    "related_products_title": {
      "type": "object",
      "description": "Localized title for related products section.",
      "example": {}
    },
    "badge": {
      "type": ["string", "null"],
      "description": "Badge label or icon associated with the product.",
      "example": null
    },
    "html_url": {
      "type": "string",
      "description": "Public product URL in the storefront.",
      "example": "https://mustafastore.localhost:8084/products/3c58afbb-7b07-4859-b653-b52242a33bb7"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the product was created.",
      "example": "2025-11-11T08:04:52.363138Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the product was last updated.",
      "example": "2025-11-11T08:05:16.595741Z"
    },
    "store_id": {
      "type": "integer",
      "description": "Unique identifier of the store to which the product belongs.",
      "example": 6
    },
    "structure": {
      "type": "string",
      "description": "Defines the product hierarchy type (e.g., parent, child).",
      "example": "parent"
    },
    "stocks": {
      "type": "array",
      "description": "Array of stock objects showing availability across locations.",
      "example": []
    },
    "variants": {
      "type": "array",
      "description": "List of variants under this product. Each variant represents a unique combination of attributes.",
      "items": {
        "type": "object",
        "description": "Variant object with similar structure to a standalone product but linked via parent_id.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the variant.",
            "example": "22a32ae6-6c6c-4904-9e2f-9c3a9373f8f1"
          },
          "parent_id": {
            "type": "string",
            "description": "Parent product ID this variant belongs to.",
            "example": "3c58afbb-7b07-4859-b653-b52242a33bb7"
          },
          "name": {
            "type": "object",
            "description": "Localized name of the variant.",
            "properties": {
              "en": { "type": "string", "example": " - Black" }
            }
          },
          "slug": {
            "type": "string",
            "description": "URL slug for the variant.",
            "example": "en-black"
          },
          "sku": {
            "type": "string",
            "description": "SKU for this variant.",
            "example": "Z.6.7228299999713898900"
          },
          "price": {
            "type": "number",
            "description": "Base price for this variant.",
            "example": 0
          },
          "sale_price": {
            "type": ["number", "null"],
            "description": "Sale or promotional price.",
            "example": null
          },
          "is_published": {
            "type": "boolean",
            "description": "Indicates whether the variant is published and visible.",
            "example": false
          },
          "is_draft": {
            "type": "boolean",
            "description": "Indicates whether the variant is in draft mode.",
            "example": true
          },
          "is_infinite": {
            "type": "boolean",
            "description": "Indicates infinite stock availability for this variant.",
            "example": false
          },
          "is_taxable": {
            "type": "boolean",
            "description": "Whether the variant is taxable.",
            "example": true
          },
          "has_fields": {
            "type": "boolean",
            "description": "Indicates if the variant has any custom option fields.",
            "example": false
          },
          "has_options": {
            "type": "boolean",
            "description": "Indicates if this variant has options.",
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2025-11-11T08:05:16.588385Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2025-11-11T08:05:16.588397Z"
          },
          "currency": {
            "type": "string",
            "example": "SAR"
          },
          "currency_symbol": {
            "type": "string",
            "example": " SAR "
          },
          "html_url": {
            "type": "string",
            "description": "Public URL for the variant in the storefront.",
            "example": "https://mustafastore.localhost:8084/products/en-black"
          },
          "structure": {
            "type": "string",
            "description": "Indicates if the variant is a 'child' product.",
            "example": "child"
          },
          "weight": {
            "type": "object",
            "description": "Weight details for the variant.",
            "example": {}
          },
          "stocks": {
            "type": "array",
            "description": "List of stock details for this variant.",
            "example": []
          }
        },
        "required": ["id", "sku", "slug", "parent_id"]
      }
    },
    "weight": {
      "type": "object",
      "description": "Product weight information.",
      "example": {}
    }
  },
  "required": ["id", "sku", "name", "variants", "structure", "price"]
}

🟠400Failed Response