Multi-item coupon rewards

What's new

Coupons can now grant multiple items in a single redemption. The new free_items request field accepts a list of {item_id, quantity} entries, and responses expose both the structured free_items wrapper and an expanded items array of full item objects. The legacy single-item fields (item_id, quantity, item) remain available but are deprecated.

Impact

You can configure a coupon to grant several different items at once instead of a single item with a fixed quantity. Existing single-item coupons continue to work — the legacy fields are still populated.

Changes

Resource	Change
create_coupon	Added optional `free_items` request property; deprecated `item_id` and `quantity` request properties
update_coupon	Added optional `free_items` request property; deprecated `item_id` and `quantity` request properties
get_coupon	Added `free_items` and `items` to the response; deprecated `item`, `item_id`, and `quantity`
get_coupons	Added `free_items` and `items` to each response item; deprecated `item`, `item_id`, and `quantity`
bulk_update_coupon	Added `free_items` and `items` to each response item; deprecated `item`, `item_id`, and `quantity`
get_user_coupons	Added `free_items` and `items` to each response item; deprecated `item`, `item_id`, and `quantity`

Upgrade

On create and update, send free_items.items (a list of {item_id, quantity} objects) instead of the top-level item_id and quantity.
When reading coupons, prefer items (full item objects) or free_items.items (id/quantity pairs) over the deprecated item, item_id, and quantity fields.

Need help?
Contact our integration team at [email protected]