Reorder Product Draft Variants

Rewrite the display order of every variant on a product's unpublished overlay. Buyers still see the live product.

draft_version is required. The body must list every non-archived overlay variant exactly once — including overlay-only variants that are not yet published, and hidden variants. Archived overlay 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 Draft Variants returns this display order.

Request

POST /products/{productId}/draft/variants/reorder

Path Parameters

Parameter	Type	Required	Description
productId	string	Yes	Product UUID

Request Body

Parameter	Type	Required	Description
draft_version	integer	Yes	Current overlay version from Get Product Draft. Minimum 1. A mismatch returns 409.
items	array	Yes	One entry per non-archived overlay 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/draft/variants/reorder" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "draft_version": 15,
    "items": [
      { "id": "5272bfcf-4e92-458d-b513-80ca474a16e4", "order": 1 },
      { "id": "d91c65aa-b221-4aa4-b626-cf0d8a198749", "order": 2 },
      { "id": "e903c6d6-163e-4080-a99a-4ee5a1e4f17a", "order": 3 }
    ]
  }'

Response

Success Response (200)

Returns { items, draft_version, preview_url } in display order. There is no pagination object. See Draft preview.

{
  "items": [
    {
      "id": "5272bfcf-4e92-458d-b513-80ca474a16e4",
      "status": "published",
      "type": "one_time",
      "name": "100g Sample",
      "amount": 999,
      "currency": "usd",
      "checkout_url": null,
      "is_hidden": false
    },
    {
      "id": "d91c65aa-b221-4aa4-b626-cf0d8a198749",
      "status": "published",
      "type": "one_time",
      "name": "250g Package",
      "amount": 1999,
      "currency": "usd",
      "is_hidden": false
    },
    {
      "id": "e903c6d6-163e-4080-a99a-4ee5a1e4f17a",
      "status": "published",
      "type": "recurring",
      "name": "Monthly Subscription - 250g",
      "amount": 1799,
      "currency": "usd",
      "is_hidden": false
    }
  ],
  "draft_version": 16,
  "preview_url": "https://cart.easy.tools/checkout-preview/0632bef5-c308-42cd-9cba-89a7a4f722bb?expires=1749384000&signature=abc123"
}

Each entry in items has the same shape as the response of Get Product Variant; the example above is abbreviated. draft_version and preview_url sit on the envelope, not on each item.

Response Fields

Field	Type	Nullable	Description
items	array	No	Overlay variants in display order. Hidden stay. Archived omitted.
draft_version	integer	No	New overlay version after this write. Send it on the next draft write.
preview_url	string	No	Temporary signed checkout preview of the product. Always reminted. Expires after about one hour. See Draft preview.

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 — Stale Draft Version)

Returned when draft_version does not match the current overlay version. GET the draft and retry with the current draft_version.

{
  "message": "The draft was edited elsewhere. GET the draft and retry with the current draft_version."
}

Validation Error (422 Unprocessable Entity)

Returned when draft_version is missing, items is not an exact permutation of the non-archived overlay set, order is not 1 through N, or an unknown key is sent.

{
  "message": "The given data was invalid.",
  "errors": {
    "draft_version": [
      "The draft version field is required."
    ]
  }
}

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

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