Create Order Bump

Append an order bump on the owner product. The server mints id and appends at the end. product_id and variant_id are required — the offered product and one-time variant, not the owner.

Defaults when omitted: display_type=large_thumbnail, active=true, amount=null (inherit the variant). Do not send currency.

Live writes return 409 when the product has has_draft: true — see Live writes while a draft exists. Draft writes require draft_version and return it plus preview_url.

Request

Live:

• POST /products/{productId}/order-bumps

Draft:

• POST /products/{productId}/draft/order-bumps

Path Parameters

Parameter	Type	Required	Description
productId	string	Yes	Owner product UUID.

Request Body

Parameter	Type	Required	Description
product_id	string	Yes	Offered product UUID.
variant_id	string	Yes	Offered one-time variant UUID.
name	string	No	Merchant-internal label. Max 255.
title	string	No	Checkout headline. Max 255.
description	string	No	Checkout body.
amount	integer	No	Override in minor units (e.g. cents). Omit or null inherits the variant. Minimum 1 when set.
display_type	string	No	large_thumbnail, compact, or countdown. Defaults to large_thumbnail.
validity_minutes	integer	When display_type is countdown	Duration in minutes. Minimum 1.
active	boolean	No	Defaults to true.
draft_version	integer	Draft only	Current overlay version. Minimum 1. A mismatch returns 409.

Unknown keys, including currency, return 422.

Example Request

curl -X POST "https://cart.easy.tools/api/v1/products/0632bef5-c308-42cd-9cba-89a7a4f722bb/order-bumps" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "70dbd819-fac2-4dcf-b655-fb925e24410b",
    "variant_id": "5272bfcf-4e92-458d-b513-80ca474a16e4",
    "name": "Backup recording",
    "title": "Add the recording",
    "description": "Keep the session afterwards.",
    "amount": 4900,
    "display_type": "large_thumbnail",
    "active": true
  }'

Draft create adds "draft_version": 8 to the body and uses the /draft/order-bumps path.

Response

Success Response (201)

Live returns the Order Bump Object. Draft returns that object plus draft_version and preview_url.

{
  "id": "4eebbd13-ee35-4d66-bfec-a9988b63ef75",
  "product_id": "70dbd819-fac2-4dcf-b655-fb925e24410b",
  "variant_id": "5272bfcf-4e92-458d-b513-80ca474a16e4",
  "name": "Backup recording",
  "title": "Add the recording",
  "description": "Keep the session afterwards.",
  "amount": 4900,
  "currency": "usd",
  "display_type": "large_thumbnail",
  "validity_minutes": null,
  "active": true
}

Error Responses

Bad Request (400)

{
  "message": "Invalid product ID"
}

Not Found Error (404)

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

Conflict Error (409 — Unpublished Draft)

Live write while has_draft is true:

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

Conflict Error (409 — Stale Draft Version)

Draft write when draft_version does not match:

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

Validation Error (422 Unprocessable Entity)

Returned when the offered variant is recurring or delivery-enabled, the pair is a duplicate, the product already has 10 bumps, countdown is missing validity_minutes, currency is sent, the owner product is not on Stripe (live only), or another field rule fails. See Offered variant rules and Cap and uniqueness.

{
  "message": "The given data was invalid.",
  "errors": {
    "variant_id": ["Order bump price must be a one-time price, not a subscription."]
  }
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

{
  "message": "You do not have API access to the requested store."
}