Order Bumps

An order bump is an add-to-your-order offer shown on a product's hosted checkout before the buyer pays. It points at another one-time variant — possibly from the same product.

Path {productId} is the owner checkout product. product_id and variant_id on the resource are the offered product and variant. The owner id is not on the object.

Product GET does not embed order bumps — they are read and written only through the endpoints below.

Order bumps are not variant upsells (same-product upgrades on a variant, no own routes) and not cross-sells (after-purchase offers on the thank-you page).

Overview

• List order bumps
• Retrieve an order bump
• Create an order bump
• Update an order bump
• Delete an order bump
• Reorder order bumps

Each write has a live form and a draft twin. Live list, create, and reorder are nested under the owner product. Live get, update, and delete use the flat /order-bumps/{id} path. Draft twins are fully nested under /products/{productId}/draft/order-bumps.

Live writes while a draft exists

When the owner product has has_draft: true, live nested and flat writes return 409 and change nothing. Edit the overlay instead (/products/{productId}/draft/order-bumps). See Live writes while a draft exists.

Draft writes require draft_version from Get Product Draft. Create, update, and reorder on the overlay also return a fresh preview_url. Overlay delete returns 204 with no body.

Amount and currency

amount is a nullable override in minor units (e.g. cents). null means inherit the offered variant's amount — it is not free. PATCH with amount: null clears an override.

currency is always the offered variant's ISO-3 code, even when amount is null. It is GET-only — sending it on create or update returns 422.

Cap and uniqueness

A product may have at most 10 order bumps, counting inactive ones. A duplicate offered product + variant pair on the same owner returns 422. The same offered product with different variants is allowed. Offering the owner product itself is allowed.

Display type

display_type is one of large_thumbnail, compact, or countdown. Omit it on create to store large_thumbnail. countdown requires validity_minutes of at least 1.

Active

active is the writable on/off toggle. Omit it on create to store true. false hides the bump at checkout but still occupies a slot in the 10-cap. Lists include inactive bumps.

Display order

The order bump object has no order field — array order of list is display order. Rewrite it with Reorder Order Bumps. Create appends at the end.

Offered variant rules

Create and update return 422 when the offered variant is recurring, when delivery is enabled on the offered product or variant, when the variant does not belong to product_id, or when the offered currency is not among the owner's published currencies. Address collection (has_shipping) is not that delivery check.

Live writes also return 422 when the owner product is not on Stripe. Draft writes are accepted either way, but publishing a draft while the product is still not on Stripe does not carry the bumps over to the live product.

Incomplete items

Every order bump this API returns has an offered product and variant. A bump still being set up in the dashboard, with either one unset, is not returned by list or get and is not counted in total. Create requires both product_id and variant_id.

Order Bump Object

Field	Type	Nullable	Description
id	string	No	Server-minted UUID.
product_id	string	No	Offered product UUID — not the owner.
variant_id	string	No	Offered one-time variant UUID.
name	string	Yes	Merchant-internal label. Checkout does not show it. Max 255.
title	string	Yes	Checkout headline. Max 255. Checkout may fall back to the offered product name at runtime.
description	string	Yes	Checkout body. Checkout may fall back to the offered product description at runtime.
amount	integer	Yes	Price override in minor units (e.g. cents). null inherits the offered variant. Minimum 1 when set.
currency	string	No	ISO-3 lowercase. Always the offered variant's currency. GET-only.
display_type	string	No	One of large_thumbnail, compact, countdown.
validity_minutes	integer	Yes	Countdown duration in minutes. Required and ≥ 1 when display_type is countdown.
active	boolean	No	Writable on/off. Inactive bumps still count toward the 10-cap.

Draft create, update, and the reorder envelope add:

Field	Type	Nullable	Description
draft_version	integer	No	New overlay version after the write. Minimum 1.
preview_url	string	No	Temporary signed checkout preview. Expires after about one hour. See Draft preview.