DocsDocsReference

Bulk create product variants

Creates multiple product variants in a single batch operation. Each variant can be associated with different products and includes stock levels, dimensions, and custom fields. Supports up to 50 variants per batch. Returns arrays of successful and failed creations.

POST/api/v1/{team_slug}/{app_slug}/variants/bulk
API
Management
Updated
Apr 26, 2026

management-api:POST:/api/v1/{team_slug}/{app_slug}/variants/bulk

Creates multiple product variants in a single batch operation. Each variant can be associated with different products and includes stock levels, dimensions, and custom fields. Supports up to 50 variants per batch. Returns arrays of successful and failed creations.

API ownership

  • API family: Management API
  • Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
  • Do not use from: Browser-only storefront code or public clients.
  • Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

  • Method: POST
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/variants/bulk
  • Summary: Bulk create product variants
  • Description: Creates multiple product variants in a single batch operation. Each variant can be associated with different products and includes stock levels, dimensions, and custom fields. Supports up to 50 variants per batch. Returns arrays of successful and failed creations.
  • OpenAPI contract: management-api
  • Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters2 parameters
NameInRequiredTypeDescription
team_slugpathYesstringTeam slug
app_slugpathYesstringApp slug
Request bodyDocumented body
  • Required: Yes
  • Description: Variants data to create
  • Content: application/json (object)

Bulk Create Variants Payload

PropertyTypeRequiredDetails
variantsobject[]YesmaxItems: 50

Bulk Create Variant Item

PropertyTypeRequiredDetails
custom_fieldsobjectNo-
product_idstringYes-
purchase_priceobjectNo-
statusenum("active", "draft", "inactive")YesStatus of the product
stockobject[]YesStock level of the variant
validate_stockbooleanNo-
variant_dimensionsobjectNo-
variant_group_idstringNo-
variant_namestringYesVariantName of the variant
variant_numberstringYesNumber of the variant

Purchase Price

PropertyTypeRequiredDetails
currencystringNo-
value_centsintegerNo-

Input Variant Stock

PropertyTypeRequiredDetails
inventory_datestringNoISO 8601 date format with time zone e.g. 2024-12-12T09:13:31.039Z.
quantityintegerNo-
warehouse_slugstringYes-

Dimensions

PropertyTypeRequiredDetails
capacity_milliliterintegerNomin: 0 the capacity in milliliter
depthintegerNomin: 0 The products depth in millimeter
diameterintegerNomin: 0 the products diameter in millimeter
heightintegerNomin: 0 The products height in millimeter
lengthintegerNomin: 0 The products length in millimeter
weightintegerNomin: 0 The products weight in grams
widthintegerNomin: 0 The products width in millimeter

Generated example (synthetic):

{
  "variants": [
    {
      "custom_fields": {},
      "product_id": "string",
      "purchase_price": {
        "currency": "string",
        "value_cents": 0
      },
      "status": "active",
      "stock": [
        {
          "inventory_date": null,
          "quantity": null,
          "warehouse_slug": null
        }
      ],
      "validate_stock": false,
      "variant_dimensions": {
        "capacity_milliliter": 0,
        "depth": 0,
        "diameter": 0,
        "height": 0,
        "length": 0,
        "weight": 0,
        "width": 0
      },
      "variant_group_id": "string",
      "variant_name": "string",
      "variant_number": "string"
    }
  ]
}
Responses4 statuses
StatusDescriptionContent
201Variants created successfullyapplication/json (object)
400Invalid requestapplication/json (object)
401Unauthorized accessapplication/json (object)
500Internal server errorapplication/json (object)

201 - object

Bulk Create Variants Response

PropertyTypeRequiredDetails
dataobjectNo-
detailsstring[]NoAdditional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes
successbooleanNo-
Bulk Create Variants
PropertyTypeRequiredDetails
failedobject[]No-
successfulobject[]No-
Bulk Create Variant Failed Creation
PropertyTypeRequiredDetails
reasonstringNo-
variant_numberstringNo-
Variant
PropertyTypeRequiredDetails
attributesobject[]No-
created_atstringNo-
custom_fieldsobjectNo-
idstringNo-
imagesobject[]NoImages of the product
listingsobjectNo-
parent_product_idstringNo-
purchase_priceobjectNo-
shipping_attributesstring[]No-
source_app_idstringNo-
source_idstringNo-
statusstringNo-
store_groupobject[]NoProduct StoreGroup
tagsobject[]No-
translationsobjectNo-
updated_atstringNo-
validate_stockbooleanNo-
variant_dimensionsobjectNo-
variant_group_idstringNo-
variant_namestringNo-
variant_numberstringNo-
videosobject[]NoVideos of the product
warehouse_variant_stockobject[]No-
{
  "data": {
    "failed": [
      {
        "reason": "string",
        "variant_number": "string"
      }
    ],
    "successful": [
      {
        "attributes": [],
        "created_at": "string",
        "custom_fields": {},
        "id": "string",
        "images": [],
        "listings": {
          "smart": null,
          "static": null
        },
        "parent_product_id": "string",
        "purchase_price": {
          "currency": null,
          "value_cents": null
        },
        "shipping_attributes": [],
        "source_app_id": "string",
        "source_id": "string",
        "status": "string",
        "store_group": [],
        "tags": [],
        "translations": {
          "name": null
        },
        "updated_at": "string",
        "validate_stock": false,
        "variant_dimensions": {
          "capacity_milliliter": null,
          "depth": null,
          "diameter": null,
          "height": null,
          "length": null,
          "weight": null,
          "width": null
        },
        "variant_group_id": "string",
        "variant_name": "string",
        "variant_number": "string",
        "videos": [],
        "warehouse_variant_stock": []
      }
    ]
  },
  "details": [
    "string"
  ],
  "success": false
}

400 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

  • API family: Management API
  • Method: POST
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/variants/bulk
  • Operation ID: Not documented in the OpenAPI contract.
  • OpenAPI tag: Variants, Bulk
  • OpenAPI summary: Bulk create product variants

Bulk create product variants

# Bulk create product variants Creates multiple product variants in a single batch operation. Each variant can be associated with different products and includes stock levels, dimensions, and custom fields. Supports up to 50 variants per batch. Returns arrays of successful and failed creations.
POST /api/v1/{team_slug}/{app_slug}/variants/bulk
Purpose

Creates multiple product variants in a single batch operation.

Required inputs

team_slug path app_slug path

Primary response

201 ยท Variants created successfully

Operation key

management-api:POST:/api/v1/{team_slug}/{app_slug}/variants/bulk

## API ownership - API family: Management API - Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data. - Do not use from: Browser-only storefront code or public clients. - Guide route: [/apis/management/latest](/apis/management/latest) The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation. ## Operation - Method: `POST` - Path: `/api/v1/{team_slug}/{app_slug}/variants/bulk` - Summary: Bulk create product variants - Description: Creates multiple product variants in a single batch operation. Each variant can be associated with different products and includes stock levels, dimensions, and custom fields. Supports up to 50 variants per batch. Returns arrays of successful and failed creations. - OpenAPI contract: management-api - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:POST:/api/v1/{team_slug}/{app_slug}/variants/bulk` Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | team_slug | path | Yes | string | Team slug | | app_slug | path | Yes | string | App slug | ## Request body - Required: Yes - Description: Variants data to create - Content: application/json (object) ### Bulk Create Variants Payload | Property | Type | Required | Details | | --- | --- | --- | --- | | `variants` | object[] | Yes | maxItems: 50 | #### Bulk Create Variant Item | Property | Type | Required | Details | | --- | --- | --- | --- | | `custom_fields` | object | No | - | | `product_id` | string | Yes | - | | `purchase_price` | object | No | - | | `status` | enum("active", "draft", "inactive") | Yes | Status of the product | | `stock` | object[] | Yes | Stock level of the variant | | `validate_stock` | boolean | No | - | | `variant_dimensions` | object | No | - | | `variant_group_id` | string | No | - | | `variant_name` | string | Yes | VariantName of the variant | | `variant_number` | string | Yes | Number of the variant | #### Purchase Price | Property | Type | Required | Details | | --- | --- | --- | --- | | `currency` | string | No | - | | `value_cents` | integer | No | - | #### Input Variant Stock | Property | Type | Required | Details | | --- | --- | --- | --- | | `inventory_date` | string | No | ISO 8601 date format with time zone e.g. 2024-12-12T09:13:31.039Z. | | `quantity` | integer | No | - | | `warehouse_slug` | string | Yes | - | #### Dimensions | Property | Type | Required | Details | | --- | --- | --- | --- | | `capacity_milliliter` | integer | No | min: 0 the capacity in milliliter | | `depth` | integer | No | min: 0 The products depth in millimeter | | `diameter` | integer | No | min: 0 the products diameter in millimeter | | `height` | integer | No | min: 0 The products height in millimeter | | `length` | integer | No | min: 0 The products length in millimeter | | `weight` | integer | No | min: 0 The products weight in grams | | `width` | integer | No | min: 0 The products width in millimeter | **Generated example (synthetic):** ```json { "variants": [ { "custom_fields": {}, "product_id": "string", "purchase_price": { "currency": "string", "value_cents": 0 }, "status": "active", "stock": [ { "inventory_date": null, "quantity": null, "warehouse_slug": null } ], "validate_stock": false, "variant_dimensions": { "capacity_milliliter": 0, "depth": 0, "diameter": 0, "height": 0, "length": 0, "weight": 0, "width": 0 }, "variant_group_id": "string", "variant_name": "string", "variant_number": "string" } ] } ``` ## Responses | Status | Description | Content | | --- | --- | --- | | 201 | Variants created successfully | application/json (object) | | 400 | Invalid request | application/json (object) | | 401 | Unauthorized access | application/json (object) | | 500 | Internal server error | application/json (object) | ### 201 - object #### Bulk Create Variants Response | Property | Type | Required | Details | | --- | --- | --- | --- | | `data` | object | No | - | | `details` | string[] | No | Additional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes | | `success` | boolean | No | - | ##### Bulk Create Variants | Property | Type | Required | Details | | --- | --- | --- | --- | | `failed` | object[] | No | - | | `successful` | object[] | No | - | ##### Bulk Create Variant Failed Creation | Property | Type | Required | Details | | --- | --- | --- | --- | | `reason` | string | No | - | | `variant_number` | string | No | - | ##### Variant | Property | Type | Required | Details | | --- | --- | --- | --- | | `attributes` | object[] | No | - | | `created_at` | string | No | - | | `custom_fields` | object | No | - | | `id` | string | No | - | | `images` | object[] | No | Images of the product | | `listings` | object | No | - | | `parent_product_id` | string | No | - | | `purchase_price` | object | No | - | | `shipping_attributes` | string[] | No | - | | `source_app_id` | string | No | - | | `source_id` | string | No | - | | `status` | string | No | - | | `store_group` | object[] | No | Product StoreGroup | | `tags` | object[] | No | - | | `translations` | object | No | - | | `updated_at` | string | No | - | | `validate_stock` | boolean | No | - | | `variant_dimensions` | object | No | - | | `variant_group_id` | string | No | - | | `variant_name` | string | No | - | | `variant_number` | string | No | - | | `videos` | object[] | No | Videos of the product | | `warehouse_variant_stock` | object[] | No | - |
Generated example (synthetic) ```json { "data": { "failed": [ { "reason": "string", "variant_number": "string" } ], "successful": [ { "attributes": [], "created_at": "string", "custom_fields": {}, "id": "string", "images": [], "listings": { "smart": null, "static": null }, "parent_product_id": "string", "purchase_price": { "currency": null, "value_cents": null }, "shipping_attributes": [], "source_app_id": "string", "source_id": "string", "status": "string", "store_group": [], "tags": [], "translations": { "name": null }, "updated_at": "string", "validate_stock": false, "variant_dimensions": { "capacity_milliliter": null, "depth": null, "diameter": null, "height": null, "length": null, "weight": null, "width": null }, "variant_group_id": "string", "variant_name": "string", "variant_number": "string", "videos": [], "warehouse_variant_stock": [] } ] }, "details": [ "string" ], "success": false } ```
### 400 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 401 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 500 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ## Contract identity Use these fields to confirm you are implementing the intended endpoint contract. - API family: Management API - Method: `POST` - Path: `/api/v1/{team_slug}/{app_slug}/variants/bulk` - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:POST:/api/v1/{team_slug}/{app_slug}/variants/bulk` - OpenAPI tag: Variants, Bulk - OpenAPI summary: Bulk create product variants