> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/basket-offers.md). # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/admin/basket-offers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.