Update Variant

put https://{shopdomain}.myshoplaza.com/openapi/2022-01/variants/{variant_id}

🔒
Requires write_product access scope. More access scope

📘
Important Note: When updating the same product, the updateVariant API may encounter performance issues due to locking mechanisms. If multiple updates are needed for the same product (e.g., updating variant prices), it is strongly recommended to use the updateProduct API instead.

The Update Variant API allows users to modify the details of a specific product variant. By providing a valid variant_id in the path parameter, users can update fields such as options, pricing, inventory, and more. This endpoint is essential for managing product variants efficiently, ensuring the most accurate and updated information is reflected in the system.This API is especially useful for:

Update variant-specific attributes like size, color, or SKU.
Adjust pricing or inventory details for a particular variant.

Note: The operation is scoped to a specific shop, identified by its unique domain prefix (shopdomain), ensuring all updates are applied to the correct store.

Public Request Parameters

Parameter Name	Type	Required	Parameter Location	Parameter Value	Description
Access-Token	`String`	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	Used to authenticate API requests. Obtain an access token from the Access Token Guide. Pass it in the `Authorization` header for every request.
Content-Type	`String`	Yes	Header	`application` `/json`	Indicates the media type of the request body. It tells the server how to parse the request and the client how to interpret the response. For more details, visit Content-Type.

Public Response Parameters

Parameter Name	Type	Mandatory	Parameter Location	Example Value	Description
error	String	No	Response Body	`{ "error": "store is not active" }`	Indicates an error encountered during the process. This field typically appears when the Access Token is missing or invalid. Example: `{ "error": "store is not active" }`.
errors	Array	No	Response Body	`{ "errors"["No Context"] }`	A list of errors that occurred during the request processing. Example: `{ "errors": [ "No Context" ] }`.
Request-Id	String	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	A unique identifier for each request. It helps in identifying and debugging specific requests.

Error and Errors Clarification:

Added explanation that the error and errors fields are currently dependent on the API implementation, with plans for future unification.

Request Parameters

Path Parameters

Parameter	Type	Required	Example	Description
variant_id	string	Yes	`"ABC123"`	The ID of the variant to be updated.

Body Parameters

Parameter	Type	Required	Example	Description
variant	object	No	variant object
variant.option1	string	No	`"Red"`	The first option (e.g., size, color) of the variant.
variant.option2	string	No	`"Large"`	The second option (e.g., size, color) of the variant.
variant.option3	string	No	`"Cotton"`	The third option (e.g., size, color) of the variant.
variant.image_id	string	No	`"91d032e7-bbc8-47e4-8668-9ba6fe714de6"`	The ID of the image associated with the variant.
variant.image	object	No	Image object
variant.image.src	string	No	`"https://cdn.example.com/image.jpg"`	The URL of the variant's image.
variant.image.width	integer	No	`"200"`	The width of the variant's image in pixels.
variant.image.height	integer	No	`"300"`	The height of the variant's image in pixels.
variant.image.alt	string	No	`"Red Cotton Shirt"`	The alternative text for the variant's image.
variant.compare_at_price	string	No	`"100.00"`	The original price before discount.
variant.price	string	Yes	`"80.00"`	The selling price of the variant.
variant.sku	string	No	`"SKU123"`	The stock-keeping unit for the variant.
variant.barcode	string	No	`"123456789012"`	The barcode of the variant.
variant.note	string	No	`"Special edition"`	A note about the variant.
variant.inventory_quantity	integer	No	`50`	The quantity of the variant in inventory.
variant.weight	string	No	`"1.25"`	The weight of the variant.
variant.weight_unit	string	No	`"kg"`	The unit of weight (e.g., `kg`, `lb`).
variant.cost_price	string	No	`"50.00"`	The cost price of the variant.
variant.wholesale_price	object	No	Wholesale Price Object
variant.wholesale_price[].price	string	No	`"60.00"`	The wholesale price of the variant.
variant.wholesale_price[].min_quantity	integer	No	`10`	The minimum quantity required for the wholesale price.

Response Explanation

Successful Response

Field	Type	Example	Description
variant.id	string	`1b735278-62c7-41ad-9976-b1b63a90590d`	Unique identifier for the variant.
variant.product_id	string	`636a07da-39eb-4829-bde9-b65fae1c28b0`	Unique identifier for the associated product.
variant.image_id	string	`91d032e7-bbc8-47e4-8668-9ba6fe714de6`	Unique identifier for the associated image.
variant.created_at	string (date)	`2024-04-15T02:00:57Z`	Timestamp indicating when the variant was created.
variant.updated_at	string (date)	`2024-04-15T02:00:57Z`	Timestamp indicating when the variant was last updated.
variant.title	string	`S-red`	Title of the variant.
variant.option1	string	`S`	First option value for the variant (e.g., size).
variant.option2	string	`red`	Second option value for the variant (e.g., color).
variant.option3	string	`""`	Third option value for the variant, if applicable.
variant.image	object	Image Object
variant.image.src	string	`//cdn.shoplazza.com/efd33b921cacd5311a32dd03a9bc8740.png`	URL of the image associated with the variant.
variant.image.width	integer	`1588`	Width of the variant image in pixels.
variant.image.height	integer	`2246`	Height of the variant image in pixels.
variant.image.path	string	`efd33b921cacd5311a32dd03a9bc8740.png`	File path of the variant image.
variant.image.alt	string	`""`	Alternative text for the variant image.
variant.position	integer	`1`	Position of the variant in the product's variant list.
variant.compare_at_price	string	`100.00`	Original price of the variant before discounts.
variant.price	string	`100.00`	Current price of the variant.
variant.sku	string	`S-RED`	Stock Keeping Unit (SKU) for the variant.
variant.barcode	string	`123`	Barcode associated with the variant.
variant.note	string	`s-red`	Notes or additional information about the variant.
variant.inventory_quantity	integer	`10`	Number of items available in inventory for the variant.
variant.weight	string	`0.10`	Weight of the variant.
variant.weight_unit	string	`kg`	Unit of measurement for the weight (e.g., kg, lb).
variant.cost_price	string	`11.00`	Cost price of the variant.
variant.wholesale_price	object	wholesale price object
variant.wholesale_price.price	string	`100.00`	Wholesale price for the variant.
variant.wholesale_price.min_quantity	integer	`1`	Minimum quantity required to avail the wholesale price.
variant.extend	object	extend object	Additional details about the variant's dimensions or origin.
variant.extend.length	number	10	length
variant.extend.width	number	10	width
variant.extend.height	number	10	height
variant.extend.dimension_unit	string	"in"	dimension_unit
variant.extend.origin_country_code	string	"AS"	Country of origin code of the product.
variant.extend.hs_code	string	"6211439"	HS codes are the international standard for commodity classification, and Shoplazza can automatically generate HS codes based on commodity information.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Array	`["No variants found"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	Array	`"store is not active"`	Indicates an error encountered during the process.

Request Examples

curl --request PUT \
     --url https://{shopdomain}.myshoplazza.com/openapi/2022-01/variants/{variant_id} \
     --header 'accept: application/json' \
     --header 'access-token: {your-access-token}' \
     --header 'content-type: application/json' \
     --data '{
       "option1": "Option1 Value",
       "option2": "Option2 Value",
       "option3": "Option3 Value",
       "image_id": "image-id-value",
       "compare_at_price": 99.99,
       "price": 79.99,
       "sku": "SKU12345",
       "barcode": "123456789",
       "note": "Updated variant note",
       "inventory_quantity": 150,
       "weight": 2.5,
       "weight_unit": "kg",
       "cost_price": 60.00,
       "wholesale_price": [
         {
           "price": 70.00,
           "min_quantity": 10
         },
         {
           "price": 65.00,
           "min_quantity": 20
         }
       ],
       "image": {
         "src": "https://cdn.shoplazza.com/image-url",
         "width": 800,
         "height": 600,
         "alt": "Image description"
       }
     }'

Success Response Example

{
  "variant": {
    "id": "3fb78d27-0b56-41bc-bf9e-34e52ecd7529",
    "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
    "image_id": "",
    "created_at": "2024-12-09T23:39:00Z",
    "updated_at": "2024-12-11T06:21:42Z",
    "title": "Small-Red",
    "option1": "Small",
    "option2": "Red",
    "option3": "",
    "image": null,
    "position": 1,
    "compare_at_price": "29.99",
    "price": "19.99",
    "sku": "SS1234-RD-S",
    "barcode": "123456789012",
    "note": "Limited",
    "inventory_quantity": 100,
    "weight": "0.50",
    "weight_unit": "kg",
    "cost_price": "12.99",
    "wholesale_price": [
      {
        "price": "19.99",
        "min_quantity": 1
      }
    ],
    "extend": null
  }
}

Error Response Example

{
  "errors": [
   "No variants found"
  ]
}

{
  "error": "store is not active"
}

Error Details

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`
422	No variants found	The variant ID provided in the request does not exist.	`{ "errors": [ "No variants found"] }`
	Invalid or empty `variant_id`	missing required `variant_id` or `variant_id` with incorrect `UUID` types	`{ "errors": [ "variant_id has an invalid UUID"]}`

Update Variant

🔒
Requires `write_product` access scope. More access scope

📘
Important Note: When updating the same product, the updateVariant API may encounter performance issues due to locking mechanisms. If multiple updates are needed for the same product (e.g., updating variant prices), it is strongly recommended to use the updateProduct API instead.

Public Request Parameters

Public Response Parameters

Request Parameters

Path Parameters

Body Parameters

Response Explanation

Successful Response

Error Response

Request Examples

Success Response Example

Error Response Example

Error Details

🔒Requires write_product access scope. More access scope

📘Important Note: When updating the same product, the updateVariant API may encounter performance issues due to locking mechanisms. If multiple updates are needed for the same product (e.g., updating variant prices), it is strongly recommended to use the updateProduct API instead.

Public Request Parameters

Public Response Parameters

Request Parameters

Path Parameters

Body Parameters

Response Explanation

Successful Response

Error Response

Request Examples

Success Response Example

Error Response Example

Error Details

🔒
Requires `write_product` access scope. More access scope

📘
Important Note: When updating the same product, the updateVariant API may encounter performance issues due to locking mechanisms. If multiple updates are needed for the same product (e.g., updating variant prices), it is strongly recommended to use the updateProduct API instead.