# Create Variants ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/products/{product_id}/variants/: post: summary: Create Variants deprecated: false description: >- 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](https://docs.zid.sa/add-a-new-product-attribute)** endpoint. **2. **Define Attribute Choices**:** Define choices (presets) for these attributes using the **[Create attribute preset](https://docs.zid.sa/create-attribute-preset )** Endpoint. :::note[] 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. `products.read_write` - Products Read & Write operationId: add-product-variants tags: - Default module/Apps/Merchant APIs/Products/Product Variants - Product Customizations parameters: - name: product_id in: path description: '' required: true example: e0ad7a76-ba42-4c59-94c9-0da600117fbf schema: type: string examples: - 107c2ff5-5c70-4749-b9bd-56dc1793013b - name: Authorization in: header description: >- The Authorization token is a unique key given to the third-party application (Partner) by Zid. It is used to authenticate the API requests made by the Partner application. The token verifies the partner's identity and ensures they have permission to access Zid's API but does not provide any specific user or store information. It should be included in the header of API requests when the partner application needs to access Zid's API. required: true example: '{{Autherization}}' schema: type: string - name: Access-Token in: header description: >- This token is used to authenticate and access information related to the store. It is obtained through an OAuth mechanism and is required to perform operations on the store's data. The `X-Manager-Token` should be included in the header of API requests that require store-related information. required: true example: '{{Access-Token}}' schema: type: string - name: Store-Id in: header description: '' required: true example: '{{StoreId}}' schema: type: number examples: - 37213 requestBody: content: application/json: schema: $ref: '#/components/schemas/ProductVariantCreateTest' example: variants: - id: ebd067c3-6c51-4692-9cac-e43118930ec2 is_deleted: false sku: Z.1.111111 price: 144 sale_price: null cost: null barcode: Z.1.111111 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.2.1111 price: 144 sale_price: 122 cost: null barcode: Z.2.1111 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: '200': description: '' content: application/json: 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. examples: - 3c58afbb-7b07-4859-b653-b52242a33bb7 name: type: object description: Localized product name. Supports both Arabic and English. properties: ar: type: string examples: - '' en: type: string examples: - '' x-apidog-orders: - ar - en x-apidog-ignore-properties: [] sku: type: string description: SKU (Stock Keeping Unit) identifier for the product. examples: - Z.1762848292350157 slug: type: string description: Unique slug (URL-friendly identifier) for the product. examples: - 3c58afbb-7b07-4859-b653-b52242a33bb7 currency: type: string description: Currency code used for pricing. examples: - SAR currency_symbol: type: string description: Symbol representation of the currency. examples: - ' SAR ' price: type: number description: Base price of the product. examples: - 0 sale_price: type: number description: Sale or discounted price, if applicable. examples: - null nullable: true formatted_price: type: string description: Formatted price string including currency symbol. examples: - ' SAR 0.00' formatted_sale_price: type: string description: Formatted sale price, if applicable. examples: - null nullable: true description: type: object description: Localized long product description. properties: {} x-apidog-orders: [] examples: - {} x-apidog-ignore-properties: [] short_description: type: object description: Localized short description. properties: {} x-apidog-orders: [] examples: - {} x-apidog-ignore-properties: [] categories: type: array description: List of categories the product belongs to. items: type: string examples: - [] images: type: array description: List of product image objects or URLs. items: type: string examples: - [] videos: type: array description: List of product video URLs or metadata objects. items: type: string examples: - [] is_draft: type: boolean description: Indicates whether the product is in draft mode. examples: - true is_infinite: type: boolean description: Indicates if product has infinite stock availability. examples: - false is_taxable: type: boolean description: Indicates whether the product is taxable. examples: - true requires_shipping: type: boolean description: Whether the product requires shipping. examples: - true group_products: type: array description: Array of grouped product references, if applicable. examples: - null nullable: true custom_option_fields: type: array description: Custom option fields associated with the product. items: type: string examples: - [] custom_user_input_fields: type: array description: Custom input fields for user-provided data. items: type: string examples: - [] options: type: array description: Array of option definitions such as color, size, etc. items: type: object properties: id: type: string examples: - 518fe604-8642-4032-b967-0be821ae235d name: type: string examples: - Color slug: type: string examples: - ุงู„ู„ูˆู† choices: type: array description: List of available choices for the option. items: type: string examples: - - Black - White required: - id - name - slug x-apidog-orders: - id - name - slug - choices x-apidog-ignore-properties: [] examples: - - 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). items: type: string examples: - [] related_products_settings: type: string description: >- Defines how related products are determined (AUTO_GENERATED or MANUAL). examples: - AUTO_GENERATED related_products_title: type: object description: Localized title for related products section. properties: {} x-apidog-orders: [] examples: - {} x-apidog-ignore-properties: [] badge: type: string description: Badge label or icon associated with the product. examples: - null nullable: true html_url: type: string description: Public product URL in the storefront. examples: - >- https://mustafastore.localhost:8084/products/3c58afbb-7b07-4859-b653-b52242a33bb7 created_at: type: string format: date-time description: Timestamp when the product was created. examples: - '2025-11-11T08:04:52.363138Z' updated_at: type: string format: date-time description: Timestamp when the product was last updated. examples: - '2025-11-11T08:05:16.595741Z' store_id: type: integer description: >- Unique identifier of the store to which the product belongs. examples: - 6 structure: type: string description: Defines the product hierarchy type (e.g., parent, child). examples: - parent stocks: type: array description: >- Array of stock objects showing availability across locations. items: type: string examples: - [] 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. examples: - 22a32ae6-6c6c-4904-9e2f-9c3a9373f8f1 parent_id: type: string description: Parent product ID this variant belongs to. examples: - 3c58afbb-7b07-4859-b653-b52242a33bb7 name: type: object description: Localized name of the variant. properties: en: type: string examples: - ' - Black' x-apidog-orders: - en x-apidog-ignore-properties: [] slug: type: string description: URL slug for the variant. examples: - en-black sku: type: string description: SKU for this variant. examples: - Z.6.7228299999713898900 price: type: number description: Base price for this variant. examples: - 0 sale_price: type: number description: Sale or promotional price. examples: - null nullable: true is_published: type: boolean description: >- Indicates whether the variant is published and visible. examples: - false is_draft: type: boolean description: Indicates whether the variant is in draft mode. examples: - true is_infinite: type: boolean description: >- Indicates infinite stock availability for this variant. examples: - false is_taxable: type: boolean description: Whether the variant is taxable. examples: - true has_fields: type: boolean description: >- Indicates if the variant has any custom option fields. examples: - false has_options: type: boolean description: Indicates if this variant has options. examples: - false created_at: type: string format: date-time examples: - '2025-11-11T08:05:16.588385Z' updated_at: type: string format: date-time examples: - '2025-11-11T08:05:16.588397Z' currency: type: string examples: - SAR currency_symbol: type: string examples: - ' SAR ' html_url: type: string description: Public URL for the variant in the storefront. examples: - >- https://mustafastore.localhost:8084/products/en-black structure: type: string description: Indicates if the variant is a 'child' product. examples: - child weight: type: object description: Weight details for the variant. properties: {} x-apidog-orders: [] examples: - {} x-apidog-ignore-properties: [] stocks: type: array description: List of stock details for this variant. items: type: string examples: - [] required: - id - parent_id - slug - sku x-apidog-orders: - id - parent_id - name - slug - sku - price - sale_price - is_published - is_draft - is_infinite - is_taxable - has_fields - has_options - created_at - updated_at - currency - currency_symbol - html_url - structure - weight - stocks x-apidog-ignore-properties: [] weight: type: object description: Product weight information. properties: {} x-apidog-orders: [] examples: - {} x-apidog-ignore-properties: [] required: - id - name - sku - price - structure - variants x-apidog-orders: - id - name - sku - slug - currency - currency_symbol - price - sale_price - formatted_price - formatted_sale_price - description - short_description - categories - images - videos - is_draft - is_infinite - is_taxable - requires_shipping - group_products - custom_option_fields - custom_user_input_fields - options - related_products - related_products_settings - related_products_title - badge - html_url - created_at - updated_at - store_id - structure - stocks - variants - weight x-apidog-ignore-properties: [] headers: {} x-apidog-name: Product Variants Added Successfully '400': description: '' content: application/json: schema: response: Partially Saved with errors validation_errors: - Error: - 'Attribute slug does not exist: stest' type: string examples: '1': summary: Example 1 value: - barcode: - This field may not be null. - barcode: - This field may not be null. '2': summary: Example 2 value: non_field_errors: - >- You cannot add variants for this product as it has associated vouchers please remove the vouchers or create a new product to add variants. headers: {} x-apidog-name: Failed Response '401': description: '' content: application/json: schema: type: object description: >- Response returned when the request cannot be authenticated because the required credentials are missing, invalid, or expired. properties: status: type: string description: Indicates the overall status of the API response. examples: - error message: type: object description: >- Contains structured details explaining why the request could not be authenticated. properties: type: type: string description: Indicates the category of the response message. examples: - error code: type: string description: >- A machine-readable code identifying the authentication error. Returns null when no specific code is available. examples: - UNAUTHORIZED nullable: true name: type: string description: >- A short, human-readable title describing the authentication error. Returns null when no title is available. examples: - Unauthorized nullable: true description: type: string description: >- A human-readable explanation of why the request could not be authenticated. Returns null when no detailed explanation is available. examples: - >- Authentication credentials are missing, invalid, or expired. nullable: true required: - type - code - name - description x-apidog-orders: - type - code - name - description x-apidog-ignore-properties: [] required: - status - message x-apidog-orders: - status - message examples: - status: error message: type: error code: UNAUTHORIZED name: Unauthorized description: >- Authentication credentials are missing, invalid, or expired. x-apidog-ignore-properties: [] examples: '5': summary: Example 1 value: status: error message: type: error code: ERROR_SESSION_MISSING name: Sorry description: Please login first. '6': summary: Example 2 value: status: error message: type: error code: ERROR_SESSION_INVALID name: Sorry description: Login session expired. Please login again. '7': summary: Example 3 value: status: error message: type: error code: ERROR_SESSION_INVALID name: Sorry description: Invalid authentication headers: {} x-apidog-name: Unauthorized '500': description: '' content: application/json: schema: type: object properties: status: type: string description: Status of the error. message: $ref: '#/components/schemas/ResponseEnvelopMessage' required: - status - message x-apidog-orders: - status - message x-apidog-ignore-properties: [] example: status: error message: type: error code: MSG_HIDDEN name: Error description: Internal Server Error headers: {} x-apidog-name: Internal Server error x-400:Bad Request: description: '' content: application/json: schema: type: object properties: response: type: string validation_errors: type: array items: type: object properties: detail: type: array items: type: string Error: type: array items: type: string x-apidog-orders: - detail - Error x-apidog-ignore-properties: [] required: - response - validation_errors x-apidog-orders: - response - validation_errors x-apidog-ignore-properties: [] examples: '3': summary: Exception value: response: Partially Saved with errors validation_errors: - detail: - Child Product Not found. - Error: - >- The combination of options already exists for another variant. '4': summary: Exception value: - {} - non_field_errors: - A product with this barcode already exists. headers: {} x-apidog-name: Bad Request security: [] x-apidog-folder: Default module/Apps/Merchant APIs/Products/Product Variants x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/613905/apis/api-9148583-run components: schemas: ProductVariantCreateTest: title: Add or Create Product Variants Request type: object description: Schema for adding or creating one or more variants for a given product. properties: variants: type: array description: >- List of variant objects to create or update under the specified product. items: type: object properties: id: type: string description: >- Unique identifier of an existing variant. If provided, the variant will be updated instead of created. examples: - ebd067c3-6c51-4692-9cac-e43118930ec2 nullable: true is_deleted: type: boolean description: Marks whether this variant is deleted. Default is false. examples: - false sku: type: string description: >- Stock Keeping Unit identifier for the variant. If omitted, an auto-generated SKU will be assigned. examples: - Z.6.1905460000038147819 nullable: true price: type: number description: Standard selling price of the variant. examples: - 144 nullable: true sale_price: type: number description: >- Discounted or promotional price for the variant. Can be null if not applicable. examples: - 122 nullable: true cost: type: number description: >- Cost of the variant. Used for internal reporting or margin calculations. examples: - null nullable: true barcode: type: string description: Barcode assigned to this variant (if any). examples: - null nullable: true attributes: type: array description: >- List of product attributes that define the variant. Required if creating a new variant. items: type: object properties: slug: type: string description: >- Slug (unique identifier) of the attribute. The attribute with this slug must already exist. examples: - ุงู„ู„ูˆู† value: type: object description: >- Object defining the value of the attribute in multiple languages. At least one language is required. properties: ar: type: string description: Attribute choice in Arabic. examples: - ุงุจูŠุถ nullable: true en: type: string description: Attribute choice in English. examples: - White nullable: true x-apidog-orders: - ar - en x-apidog-ignore-properties: [] required: - slug - value x-apidog-orders: - slug - value x-apidog-ignore-properties: [] examples: - - slug: ุงู„ู„ูˆู† value: ar: ุงุจูŠุถ en: White stocks: type: array description: >- List of stock information for the variant, defining quantities and locations. items: type: object properties: available_quantity: type: integer description: >- Available quantity of the product at the specified inventory location. examples: - 44 nullable: true is_infinite: type: boolean description: >- Flag indicating if this product has infinite stock availability. Default is false. examples: - false nullable: true location: type: string description: >- Unique ID of the inventory location where this stock is stored. examples: - e2629f14-12ad-4ee4-8103-9db7290c4ccc required: - location x-apidog-orders: - available_quantity - is_infinite - location x-apidog-ignore-properties: [] examples: - - available_quantity: 44 is_infinite: false location: e2629f14-12ad-4ee4-8103-9db7290c4ccc weight: type: object description: >- Defines the weight of the variant including unit type and value. properties: unit: type: string description: >- Unit of measurement for the weight (e.g., 'kg', 'g', 'lb'). examples: - kg value: type: number description: >- Numeric value of the variantโ€™s weight. Can be null if unspecified. examples: - null nullable: true required: - unit x-apidog-orders: - unit - value x-apidog-ignore-properties: [] required: - attributes x-apidog-orders: - id - is_deleted - sku - price - sale_price - cost - barcode - attributes - stocks - weight x-apidog-ignore-properties: [] examples: - - 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 required: - variants x-apidog-orders: - variants x-apidog-ignore-properties: [] x-apidog-folder: '' ResponseEnvelopMessage: type: object properties: type: type: string description: Type of response message returned by the API. examples: - success code: type: string description: Response code returned by the API, if available. examples: - MSG_POPUP_OK nullable: true name: type: string description: Name or title of the response message, if available. examples: - Coupons nullable: true description: type: string description: Detailed description of the response message, if available. examples: - Coupons created successfully nullable: true required: - type - code - name - description description: Additional response metadata. x-apidog-orders: - type - code - name - description x-apidog-ignore-properties: [] x-apidog-folder: '' securitySchemes: {} servers: - url: https://api.zid.sa/ description: Prod Env security: [] ```