Offers
Create an offer
Like New offer on the Offers page. What an offer needs depends on its type:
- bundle:
product_ids(2 or more, bought together) and usually adiscount; - upsell: one product in
product_idsand its packs intiers(1 to 6); - cross_sell:
cross_sell(what arms it and what it suggests), optionally adiscounton the add-on.
A store has at most 30 offers (quota_exceeded).
Body
- typestring
Required to create; can't change after.
One of
bundle,upsell,cross_sell - namestring
1–80 characters
- statusstring
One of
active,paused - starts_atstring or null
ISO 8601 date-time, UTC
- ends_atstring or null
ISO 8601 date-time, UTC
- show_countdownboolean
Show a countdown to ends_at. Needs ends_at.
- discountDiscountValue or null
Bundles and cross-sells. Upsells set theirs per pack.
2 child fields
- typestringRequired
One of
percent,fixed - valuestringRequired
- free_shippingboolean
Bundles and cross-sells.
- product_idsarray of strings
Bundle: 2 or more. Upsell: exactly 1.
up to 20 items · at least 1 item
- variant_idsarray of strings or null
Upsell: only these variants of the product count. null: all of them.
up to 100 items
- tiersarray of OfferTiers
Upsell: the packs; at least one must have a discount.
up to 6 items · at least 1 item
6 child fields
- quantityintegerRequired
1–999
- discountDiscountValue or null
The pack's price break; null or left out for the regular price.
2 child fields
- typestringRequired
One of
percent,fixed - valuestringRequired
- free_shippingboolean
default false
- labelstring or null
Left out: "N ×".
up to 40 characters
- badgestring or null
Such as POPULAR or BEST VALUE.
up to 20 characters
- image_urlstring or null
Left out: the product's image.
up to 1000 characters
- cross_sellOfferCrossSell
8 child fields
- trigger_scopestring
What arms it: carts holding trigger_product_ids, a product of trigger_collection_ids, or every cart.
One of
products,collection,all - trigger_product_idsarray of strings
up to 100 items
- trigger_collection_idsarray of strings
up to 50 items
- suggested_product_idsarray of strings
up to 50 items
- placementsarray of strings
One of
order_button,summary,checkout_summary,cart,post_purchase
at least 1 item - priorityinteger
Higher shows first when several apply.
-1000–1000
- max_itemsinteger or null
1–8
- auto_fillboolean
Fill the suggestions with the store's best sellers when suggested_product_ids is short.
Returns
201 Created · The new offer. Offer
- idstring
starts with ofr_
- objectstring
always "offer"
- typestring
One of
bundle,upsell,cross_sell - namestring
- statusstring
One of
active,paused - statestring
Where the offer is in its schedule now.
One of
active,scheduled,expired,paused - starts_atstring or null
ISO 8601 date-time, UTC
- ends_atstring or null
ISO 8601 date-time, UTC
- show_countdownboolean
- discountDiscountValue or null
2 child fields
- typestringRequired
One of
percent,fixed - valuestringRequired
- free_shippingboolean
- product_idsarray of strings
- variant_idsarray of strings or null
- tiersarray of OfferTiers or null
6 child fields
- quantityintegerRequired
1–999
- discountDiscountValue or null
The pack's price break; null or left out for the regular price.
2 child fields
- typestringRequired
One of
percent,fixed - valuestringRequired
- free_shippingboolean
default false
- labelstring or null
Left out: "N ×".
up to 40 characters
- badgestring or null
Such as POPULAR or BEST VALUE.
up to 20 characters
- image_urlstring or null
Left out: the product's image.
up to 1000 characters
- cross_sellOfferCrossSell or null
8 child fields
- trigger_scopestring
What arms it: carts holding trigger_product_ids, a product of trigger_collection_ids, or every cart.
One of
products,collection,all - trigger_product_idsarray of strings
up to 100 items
- trigger_collection_idsarray of strings
up to 50 items
- suggested_product_idsarray of strings
up to 50 items
- placementsarray of strings
One of
order_button,summary,checkout_summary,cart,post_purchase
at least 1 item - priorityinteger
Higher shows first when several apply.
-1000–1000
- max_itemsinteger or null
1–8
- auto_fillboolean
Fill the suggestions with the store's best sellers when suggested_product_ids is short.
- created_atstring
ISO 8601 date-time, UTC
- updated_atstring
ISO 8601 date-time, UTC
- livemodeboolean
Errors
Every error has the same shape. This endpoint can answer with:
