Basket Offers

Administrative endpoints for basket offers — the promotion campaigns (discounts, coupons, voucher codes, free shipping, loyalty points, and similar benefits) that are evaluated against customer baskets on the storefront.

Core Capabilities

1. Basket Offer Listing & Filtering

• Retrieve a paginated list of basket offers, ordered so that offers ending soonest appear first.

• Filter by status, offer type, voucher code, campaign dates, assigned user, label, and nested promotion / condition / benefit fields.

2. Basket Offer Lifecycle Management

• Create a basket offer together with its nested promotion, condition, and benefit in a single request.

• Fully or partially update an existing basket offer.

• Change the status of a single offer, or activate / deactivate many offers in one bulk request.

3. Campaign Composition

• A basket offer combines a promotion (identity), a condition (when the offer applies — quantity, amount, distinct-product, or free-form query rules), and a benefit (what the customer receives — percentage or fixed discount, multibuy pricing, free shipping, coupon or voucher generation, sample products, or loyalty points).

• Offers can be restricted to a single user, a voucher code, both, or opened site-wide; bulk variants distribute coupons or voucher codes to many users.

Offer Types

The offer_type field determines how the offer is matched to a customer. When omitted on create, the server derives it from the presence of user and voucher_code.

Value	Description
sitewide	Applies to every basket; no user and no voucher code may be set.
coupon	Personal offer bound to a single user; no voucher code.
coupon_code	Personal offer bound to a single user and redeemed with a voucher code.
voucher_code	Public offer redeemed with a voucher code; no user binding.
bulk_voucher_code	Offer redeemed through individually generated codes managed with the Bulk Voucher Codes endpoints (/bulk_voucher_codes/).
bulk_coupon	Personal coupons distributed to a list of users uploaded as a file (bulk_coupon_file).

Offer Statuses

Value	Description
active	The offer is eligible for application on the storefront.
passive	The offer is disabled. Expired offers are automatically moved to this status by a scheduled job.
used	A single-use offer (e.g. a coupon) that has been consumed. A used offer's status cannot be changed again.
revoked	The offer has been withdrawn.

Dynamic Settings & Environment Variables

The behavior of these endpoints is influenced by the following dynamic settings, configured in the management panel. Each is referenced again in the description of the operations it affects.

Key	Type	Default	Effect
DEFAULT_CURRENCY	string (a lowercase ISO 4217 currency code; must be one of the currencies configured in AVAILABLE_CURRENCIES)	the server configuration value DEFAULT_CURRENCY_TYPE	The shop's default currency. Affects create (POST /basket_offers/): when the currencies field is omitted from the request, the offer is created with currencies defaulting to a single-element list containing this currency.
BASKET_OFFER_IS_CONSUME_GROUP_ENABLED	boolean	false	Controls whether consume-group settings are shown on the basket offer page of the management panel. This is a panel display toggle only — it does not change the validation or behavior of the API endpoints themselves.

Two further dynamic settings of the promotions module — AUTO_USE_COUPONS and PROMOTION_GATEWAY_ACTIVE — govern how the offers created here are applied to baskets on the storefront; they have no effect on the administrative endpoints in this document.

Environment variables: No environment variables are read directly by these endpoints. The only related server configuration value is DEFAULT_CURRENCY_TYPE, which serves as the fallback default of the DEFAULT_CURRENCY dynamic setting described above.