> 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/checkout/promotions-and-extras/apply-or-clear-voucher-code.md).

# Apply or Clear Voucher Code

Sets or clears the voucher code on the checkout session. This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

**Required Fields**:

* `voucher_code`: The voucher code string to apply (optional, max 128 characters). Whitespace is trimmed automatically. Submit an empty value or omit the field to clear the voucher code.

**Validation**:

* If a non-empty voucher code is provided, it is validated using `OfferApplicator` in a dry-run mode (on a copy of the pre-order and basket)
* The code is considered valid only if it results in an applied and non-failed voucher
* An invalid code returns a validation error in the `errors` field

**State Changes**:

* `pre_order.voucher_code` is set to the validated code
* Submitting an empty value clears `pre_order.voucher_code` (sets it to `null`)

```json
{"openapi":"3.1.0","info":{"title":"Overview","version":"1.0.0"},"tags":[{"name":"Promotions & Extras","description":"# Checkout Promotions & Extras\n\nApply discounts and promotional offers that reduce the order total or add complimentary items.\n\n**Coupons** apply a single-use discount code to the basket.\n\n**Vouchers** apply a voucher code that may provide a fixed or percentage discount.\n\n**Campaigns** present available promotional campaigns the customer can activate.\n\n**Sample Products** let customers add a complimentary product sample to their order.\n\n## Authentication\n\nThese endpoints support both authenticated and anonymous sessions.\n\n- **Authenticated users**: Session cookie (`sessionid`) tracks checkout progress.\n- **Anonymous users**: Guest checkout is available when the `CAN_GUEST_PURCHASE` setting is enabled.\n## Request Format\n\nInclude the following header in all checkout requests:\n\n- **x-requested-with**: `XMLHttpRequest`"}],"servers":[{"description":"Akinon Checkout API","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com"}}}],"paths":{"/orders/checkout/?page=VoucherCodePage":{"post":{"tags":["Promotions & Extras"],"operationId":"submitVoucherCode","summary":"Apply or Clear Voucher Code","description":"Sets or clears the voucher code on the checkout session.\nThis is an independent step and does not determine the next checkout page.\nThe checkout flow proceeds based on the current checkout state.\n\n**Required Fields**:\n- `voucher_code`: The voucher code string to apply (optional, max 128 characters).\n  Whitespace is trimmed automatically.\n  Submit an empty value or omit the field to clear the voucher code.\n\n**Validation**:\n- If a non-empty voucher code is provided, it is validated using `OfferApplicator`\n  in a dry-run mode (on a copy of the pre-order and basket)\n- The code is considered valid only if it results in an applied and non-failed voucher\n- An invalid code returns a validation error in the `errors` field\n\n**State Changes**:\n- `pre_order.voucher_code` is set to the validated code\n- Submitting an empty value clears `pre_order.voucher_code` (sets it to `null`)","parameters":[{"$ref":"#/components/parameters/AjaxRequestHeader"},{"$ref":"#/components/parameters/SessionCookieHeader"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/VoucherCodeInput"}}}},"responses":{"200":{"description":"Voucher code processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}}}}}},"components":{"parameters":{"AjaxRequestHeader":{"name":"x-requested-with","in":"header","required":true,"description":"Required header for AJAX requests. Must be set to `XMLHttpRequest` for all checkout requests.","schema":{"type":"string","enum":["XMLHttpRequest"],"default":"XMLHttpRequest"}},"SessionCookieHeader":{"name":"Cookie","in":"header","required":false,"description":"Session cookie header (e.g. `sessionid=abc123` or `osessionid=<session_id>`)","schema":{"type":"string"}}},"schemas":{"VoucherCodeInput":{"type":"object","properties":{"voucher_code":{"type":"string","description":"Voucher code to apply to the checkout session. Leading and trailing whitespace\nis trimmed automatically. Submit an empty string or omit this field to clear\nthe currently set voucher code. Maximum 128 characters.","maxLength":128}}},"CheckoutResponse":{"type":"object","properties":{"context_list":{"type":"array","items":{"$ref":"#/components/schemas/PageContext"}},"pre_order":{"$ref":"#/components/schemas/PreOrder"},"errors":{"oneOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"},{"type":"array","items":{"type":"string"}}]},"template_name":{"type":"string"}}},"PageContext":{"type":"object","properties":{"page_name":{"type":"string","description":"Class name of the page (e.g., \"IndexPage\", \"AddressSelectionPage\")"},"page_slug":{"type":"string","description":"URL-friendly slug for the page"},"page_context":{"type":"object","description":"Page-specific context data","additionalProperties":true}}},"PreOrder":{"type":"object","description":"Pre-order state containing basket, addresses, shipping, payment information","properties":{"basket":{"$ref":"#/components/schemas/Basket"},"shipping_address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"billing_address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"shipping_option":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDetail"},{"type":"null"}]},"billing_and_shipping_same":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"payment_option":{"oneOf":[{"$ref":"#/components/schemas/PaymentOptionDetail"},{"type":"null"}]},"notifications":{"type":"array","items":{"type":"object"}},"shipping_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"total_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"unpaid_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"loyalty_money":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"currency_type_label":{"type":"string"},"installment":{"oneOf":[{"$ref":"#/components/schemas/Installment"},{"type":"null"}]},"card_info":{"oneOf":[{"type":"object","description":"Card information from BIN lookup","properties":{"bin_number":{"type":"string","description":"Card BIN (first 6-8 digits)"},"card":{"type":"object","description":"Card details from BIN database","properties":{"pk":{"type":"integer"},"name":{"type":"string","description":"Card type name (e.g., \"Visa\", \"Mastercard\")"}}}}},{"type":"null"}]},"redirect_to_three_d":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"delivery_option":{"oneOf":[{"$ref":"#/components/schemas/DeliveryOption"},{"type":"null"}]},"retail_store":{"oneOf":[{"$ref":"#/components/schemas/RetailStore"},{"type":"null"}]},"funds_transfer_bank":{"oneOf":[{"$ref":"#/components/schemas/BankAccount"},{"type":"null"}]},"number":{"oneOf":[{"type":"string","description":"Pre-order/order number"},{"type":"null"}]},"order":{"oneOf":[{"type":"object","description":"Created order (after checkout completion)","properties":{"pk":{"type":"integer"},"number":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"payment_choice":{"oneOf":[{"$ref":"#/components/schemas/PaymentChoice"},{"type":"null"}]},"user_email":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"user_phone_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"gift_box":{"oneOf":[{"type":"object","properties":{"note":{"type":"string"},"gift_video":{"type":"boolean"},"gift_video_notification_sent":{"type":"boolean"},"price":{"type":"string"}}},{"type":"null"}]},"delivery_range":{"oneOf":[{"type":"object","properties":{"lower":{"type":"string","format":"date-time"},"upper":{"type":"string","format":"date-time"}}},{"type":"null"}]},"total_amount_with_interest":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"is_guest":{"type":"boolean"},"is_post_order":{"type":"boolean"},"data_source_shipping_options":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/DataSourceShippingOptionDetail"}},{"type":"null"}]},"attribute_based_shipping_options":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/PreOrderAttributeBasedShippingOption"}},{"type":"null"}]}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer"},"total_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"Address":{"type":"object","properties":{"pk":{"type":"integer"},"email":{"type":"string"},"phone_number":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"country":{"$ref":"#/components/schemas/Country"},"city":{"$ref":"#/components/schemas/City"},"line":{"type":"string"},"title":{"type":"string"},"township":{"$ref":"#/components/schemas/Township"},"district":{"oneOf":[{"$ref":"#/components/schemas/District"},{"type":"null"}]},"postcode":{"type":"string"},"notes":{"type":"string"},"company_name":{"type":"string"},"tax_office":{"type":"string"},"tax_no":{"type":"string"},"e_bill_taxpayer":{"type":"boolean"},"is_corporate":{"type":"boolean"},"primary":{"type":"boolean"},"identity_number":{"type":"string"}}},"Country":{"type":"object","properties":{"pk":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"}}},"City":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"Township":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"District":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"ShippingOptionDetail":{"type":"object","description":"Detailed shipping option with calculated amount","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"kwargs":{"type":"object","additionalProperties":true}}},"PaymentOptionDetail":{"type":"object","description":"Detailed payment option with type information","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"payment_type":{"type":"string","enum":["credit_card","funds_transfer","bkm_express","loyalty_money","cash_register","gpay","redirection","stored_card","masterpass","masterpass_rest","credit_payment","pay_later","saved_card","confirmation","b2b","wallet","pay_on_delivery"]},"payment_type_label":{"type":"string"}}},"Installment":{"type":"object","properties":{"pk":{"type":"integer"},"installment_count":{"type":"integer"},"label":{"type":"string"},"price_with_accrued_interest":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"monthly_price_with_accrued_interest":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"DeliveryOption":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"delivery_option_type":{"type":"string","enum":["customer","retail_store","pickup_location"]},"is_active":{"type":"boolean"}}},"RetailStore":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"erp_code":{"type":"string"},"township":{"$ref":"#/components/schemas/Township"},"click_and_collect":{"type":"boolean"},"is_active":{"type":"boolean"}}},"BankAccount":{"type":"object","description":"Bank account for funds transfer payments","properties":{"pk":{"type":"integer"},"bank_name":{"type":"string","description":"Name of the bank"},"account_holder":{"type":"string","description":"Account holder name"},"iban":{"type":"string","description":"International Bank Account Number"},"currency":{"type":"string","description":"Currency code (e.g., \"USD\", \"EUR\", \"TRY\")"},"is_active":{"type":"boolean"}}},"PaymentChoice":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"price":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"DataSourceShippingOptionDetail":{"type":"object","description":"Data source shipping option for multi-vendor shipping","properties":{"pk":{"type":"integer"},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"shipping_option_name":{"type":"string"},"shipping_option_logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"data_source":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"}}},"description":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"PreOrderAttributeBasedShippingOption":{"type":"object","description":"Attribute-based shipping option selected for a product group","properties":{"pk":{"type":"integer"},"shipping_option_name":{"type":"string"},"shipping_option_logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"product_ids":{"type":"array","items":{"type":"integer"}},"attribute_value":{"type":"string"},"attribute_key":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}}}}}
```


---

# 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/checkout/promotions-and-extras/apply-or-clear-voucher-code.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.