Create Product Draft Variant

Append an unpublished variant to a product's overlay. Buyers still see the live product. The variant is only reachable under /products/{productId}/draft/variants — it does not appear on Get Product Variant.

draft_version is required. The rest of the body matches Create Product Variant. Repeating the request creates another unpublished variant.

Request

POST /products/{productId}/draft/variants

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.

All other fields match Create Product Variant. type and amount are required; recurring_options is required when type is recurring. upsells is not accepted on create — see Upsells.

Example Request

curl -X POST "https://cart.easy.tools/api/v1/products/0632bef5-c308-42cd-9cba-89a7a4f722bb/draft/variants" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "draft_version": 8,
    "type": "one_time",
    "amount": 999,
    "name": "100g Sample"
  }'

Response

Success Response (201)

Returns the created overlay variant plus the new draft_version and a fresh product preview_url. checkout_url is null. The id is a new UUID. See Draft preview.

{
  "id": "5272bfcf-4e92-458d-b513-80ca474a16e4",
  "status": "published",
  "type": "one_time",
  "recurring_options": null,
  "name": "100g Sample",
  "amount": 999,
  "currency": "usd",
  "checkout_url": null,
  "draft_version": 9,
  "preview_url": "https://cart.easy.tools/checkout-preview/0632bef5-c308-42cd-9cba-89a7a4f722bb?expires=1749384000&signature=abc123"
}

The response contains the full variant plus draft_version and preview_url. See Get Product Variant for the complete list of variant fields; the example above is abbreviated.

Response Fields

Shared variant fields are listed on Get Product Variant. This write adds:

Field	Type	Nullable	Description
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 or the body fails the same field rules as Create Product Variant.

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