DocsDocsReference

Bulk update product variants

Updates multiple product variants in a single batch operation. Supports partial updates to variant properties including name, status, stock levels, dimensions, and custom fields. Processes up to 50 variants per batch. Returns arrays of successful and failed updates.

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

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

Updates multiple product variants in a single batch operation. Supports partial updates to variant properties including name, status, stock levels, dimensions, and custom fields. Processes up to 50 variants per batch. Returns arrays of successful and failed updates.

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: PATCH
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/variants/bulk
  • Summary: Bulk update product variants
  • Description: Updates multiple product variants in a single batch operation. Supports partial updates to variant properties including name, status, stock levels, dimensions, and custom fields. Processes up to 50 variants per batch. Returns arrays of successful and failed updates.
  • 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 update
  • Content: application/json (object)

Bulk Patch Variants Payload

PropertyTypeRequiredDetails
variantsobject[]YesmaxItems: 50

Bulk Patch Variant Item

PropertyTypeRequiredDetails
custom_fieldsobjectNoCustom fields - null value removes the field, non-null merges with existing
idstringYes-
purchase_priceobjectNo-
statusenum("active", "draft", "inactive")NoStatus of the product
stockobject[]YesStock level of the variant
validate_stockbooleanNo-
variant_dimensionsobjectNo-
variant_group_idstringNo-
variant_namestringNoName 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": {},
      "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"
    }
  ]
}
Responses4 statuses
StatusDescriptionContent
200Variants updated successfullyapplication/json (object)
400Invalid requestapplication/json (object)
401Unauthorized accessapplication/json (object)
500Internal server errorapplication/json (object)

200 - object

Bulk Patch 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 Patch Variants
PropertyTypeRequiredDetails
failedobject[]No-
successfulobject[]No-
Bulk Patch Failed Update
PropertyTypeRequiredDetails
idstringNo-
reasonstringNo-
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": [
      {
        "id": "string",
        "reason": "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: PATCH
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/variants/bulk
  • Operation ID: Not documented in the OpenAPI contract.
  • OpenAPI tag: Variants, Bulk
  • OpenAPI summary: Bulk update product variants

Bulk update product variants

# Bulk update product variants Updates multiple product variants in a single batch operation. Supports partial updates to variant properties including name, status, stock levels, dimensions, and custom fields. Processes up to 50 variants per batch. Returns arrays of successful and failed updates.
PATCH /api/v1/{team_slug}/{app_slug}/variants/bulk
Purpose

Updates multiple product variants in a single batch operation.

Required inputs

team_slug path app_slug path

Primary response

200 ยท Variants updated successfully

Operation key

management-api:PATCH:/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: `PATCH` - Path: `/api/v1/{team_slug}/{app_slug}/variants/bulk` - Summary: Bulk update product variants - Description: Updates multiple product variants in a single batch operation. Supports partial updates to variant properties including name, status, stock levels, dimensions, and custom fields. Processes up to 50 variants per batch. Returns arrays of successful and failed updates. - OpenAPI contract: management-api - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PATCH:/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 update - Content: application/json (object) ### Bulk Patch Variants Payload | Property | Type | Required | Details | | --- | --- | --- | --- | | `variants` | object[] | Yes | maxItems: 50 | #### Bulk Patch Variant Item | Property | Type | Required | Details | | --- | --- | --- | --- | | `custom_fields` | object | No | Custom fields - null value removes the field, non-null merges with existing | | `id` | string | Yes | - | | `purchase_price` | object | No | - | | `status` | enum("active", "draft", "inactive") | No | 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 | No | Name 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": {}, "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" } ] } ``` ## Responses | Status | Description | Content | | --- | --- | --- | | 200 | Variants updated successfully | application/json (object) | | 400 | Invalid request | application/json (object) | | 401 | Unauthorized access | application/json (object) | | 500 | Internal server error | application/json (object) | ### 200 - object #### Bulk Patch 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 Patch Variants | Property | Type | Required | Details | | --- | --- | --- | --- | | `failed` | object[] | No | - | | `successful` | object[] | No | - | ##### Bulk Patch Failed Update | Property | Type | Required | Details | | --- | --- | --- | --- | | `id` | string | No | - | | `reason` | 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": [ { "id": "string", "reason": "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: `PATCH` - Path: `/api/v1/{team_slug}/{app_slug}/variants/bulk` - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PATCH:/api/v1/{team_slug}/{app_slug}/variants/bulk` - OpenAPI tag: Variants, Bulk - OpenAPI summary: Bulk update product variants