> 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/set-the-status-of-a-basket-offer.md).

# Set the status of a basket offer

Changes the status of a single basket offer.

An offer whose current status is `used` cannot be changed; the request is rejected with a validation error.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Basket Offers","description":"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.\n\n## Core Capabilities\n\n**1. Basket Offer Listing & Filtering**\n* Retrieve a paginated list of basket offers, ordered so that offers ending soonest appear first.\n* Filter by status, offer type, voucher code, campaign dates, assigned user, label, and nested promotion / condition / benefit fields.\n\n**2. Basket Offer Lifecycle Management**\n* Create a basket offer together with its nested promotion, condition, and benefit in a single request.\n* Fully or partially update an existing basket offer.\n* Change the status of a single offer, or activate / deactivate many offers in one bulk request.\n\n**3. Campaign Composition**\n* 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).\n* 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.\n\n## Offer Types\n\nThe `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`.\n\n| Value | Description |\n|-------|-------------|\n| `sitewide` | Applies to every basket; no user and no voucher code may be set. |\n| `coupon` | Personal offer bound to a single user; no voucher code. |\n| `coupon_code` | Personal offer bound to a single user **and** redeemed with a voucher code. |\n| `voucher_code` | Public offer redeemed with a voucher code; no user binding. |\n| `bulk_voucher_code` | Offer redeemed through individually generated codes managed with the **Bulk Voucher Codes** endpoints (`/bulk_voucher_codes/`). |\n| `bulk_coupon` | Personal coupons distributed to a list of users uploaded as a file (`bulk_coupon_file`). |\n\n## Offer Statuses\n\n| Value | Description |\n|-------|-------------|\n| `active` | The offer is eligible for application on the storefront. |\n| `passive` | The offer is disabled. Expired offers are automatically moved to this status by a scheduled job. |\n| `used` | A single-use offer (e.g. a coupon) that has been consumed. A used offer's status cannot be changed again. |\n| `revoked` | The offer has been withdrawn. |\n\n## Dynamic Settings & Environment Variables\n\nThe 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.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `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. |\n| `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. |\n\nTwo 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.\n\n**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."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"parameters":{"basketOfferId":{"name":"id","in":"path","required":true,"description":"The unique identifier of the basket offer.","schema":{"type":"integer"}}},"schemas":{"BasketOfferSetStatusRequest":{"type":"object","required":["status"],"properties":{"status":{"allOf":[{"$ref":"#/components/schemas/BasketOfferStatus"}],"description":"The new status. An offer whose current status is `used` cannot be changed."}}},"BasketOfferStatus":{"type":"string","description":"The lifecycle status of a basket offer.\n* `active` — eligible for application on the storefront\n* `passive` — disabled (expired offers are moved here automatically)\n* `used` — single-use offer that has been consumed; cannot be changed again\n* `revoked` — withdrawn","enum":["active","passive","used","revoked"]},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BasketOfferNotFound":{"description":"The requested basket offer does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/basket_offers/{id}/set_status/":{"patch":{"tags":["Basket Offers"],"operationId":"setBasketOfferStatus","summary":"Set the status of a basket offer","description":"Changes the status of a single basket offer.\n\nAn offer whose current status is `used` cannot be changed; the request is rejected with a validation error.","parameters":[{"$ref":"#/components/parameters/basketOfferId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketOfferSetStatusRequest"}}}},"responses":{"200":{"description":"The status was changed. The response body is an empty object.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/BasketOfferNotFound"}}}}}}
```


---

# 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/set-the-status-of-a-basket-offer.md?ask=<question>&goal=<endgoal>
```

`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.