Reorder Product Variants

Rewrite the display order of every published variant of a product.

The body must list every published variant exactly once. Hidden variants (is_hidden: true) are included. Archived variants are excluded. order is 1-based and must be a permutation of 1 through N. Array position is ignored — order is what counts.

The variant object has no order field. When sort is omitted, Get Product Variants returns this display order.

A product with no published variants accepts { "items": [] }.

When the product has has_draft: true, the call returns 409 and nothing is changed. Reorder on the overlay with Reorder Product Draft Variants, or discard the draft first. See Live writes while a draft exists.

Request

POST /products/{productId}/variants/reorder

Path Parameters

Parameter	Type	Required	Description
productId	string	Yes	Product UUID

Request Body

Parameter	Type	Required	Description
items	array	Yes	One entry per published variant. Extra, missing, or duplicate ids return 422.

Items Object

Parameter	Type	Required	Description
id	string	Yes	Product variant UUID
order	integer	Yes	1-based display position. Must be a permutation of 1 through N.

Unknown keys on the body or on an item return 422.

Example Request

curl -X POST "https://cart.easy.tools/api/v1/products/0632bef5-c308-42cd-9cba-89a7a4f722bb/variants/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "e903c6d6-163e-4080-a99a-4ee5a1e4f17a", "order": 1 },
      { "id": "d91c65aa-b221-4aa4-b626-cf0d8a198749", "order": 2 }
    ]
  }'

Response

Success Response (200)

Returns { "items": [ … ] } in display order. There is no pagination object.

{
  "items": [
    {
      "id": "e903c6d6-163e-4080-a99a-4ee5a1e4f17a",
      "status": "published",
      "type": "recurring",
      "name": "Monthly Subscription - 250g",
      "amount": 1799,
      "currency": "usd",
      "is_hidden": false
    },
    {
      "id": "d91c65aa-b221-4aa4-b626-cf0d8a198749",
      "status": "published",
      "type": "one_time",
      "name": "250g Package",
      "amount": 1999,
      "currency": "usd",
      "is_hidden": false
    }
  ]
}

Each entry in items has the same shape as the response of Get Product Variant; the example above is abbreviated.

Error Responses

Bad Request (400)

{
  "message": "Invalid product ID"
}

Product Not Found (404)

{
  "message": "Product with ID 0632bef5-c308-42cd-9cba-89a7a4f722bb not found"
}

Conflict Error (409 — Unpublished Draft)

Returned when an unpublished overlay exists. Nothing is changed. Reorder on the overlay, or discard the draft first.

{
  "message": "This product has an unpublished draft. Publish, unpublish, or delete the draft before making live changes."
}

Validation Error (422 Unprocessable Entity)

Returned when items is not an exact permutation of the published set, order is not 1 through N, or an unknown key is sent.

{
  "message": "The given data was invalid.",
  "errors": {
    "items": [
      "The items list must include every published variant of this product exactly once."
    ]
  }
}

{
  "message": "The given data was invalid.",
  "errors": {
    "items": [
      "The order values must be a permutation of 1 through 2."
    ]
  }
}

{
  "message": "The foo field is not allowed.",
  "errors": {
    "foo": [
      "The foo field is not allowed."
    ]
  }
}