> 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/gift-cards-gift-boxes-and-loyalty/set-loyalty-money-amount-to-apply-to-the-order.md). # Set loyalty money amount to apply to the order Specifies the amount of loyalty money the user wishes to apply to the current order. The submitted amount is stored in the checkout session and used when the payment is finalized. Two input modes are supported: 1. **Legacy mode** — submit `loyalty_amount_to_use` as a flat decimal amount. The system automatically distributes the debit across the user's accounts in label-priority order. 2. **Label-based mode** — submit `account_usages` as a JSON-encoded array specifying the exact amount to debit from each account label. When both fields are provided, `loyalty_amount_to_use` takes precedence and `account_usages` is discarded. **Required Fields**: * At least one of `loyalty_amount_to_use` or `account_usages` must be present. Submitting `null` for `loyalty_amount_to_use` sets the applied amount to zero. **Validation**: * Each entry in `account_usages` must reference a label the user owns. * The requested amount per label must not exceed the available balance for that label. * `account_usages` must be a valid JSON array; a malformed value returns a validation error. **State Update**: * The selected payment option, card details, and installment selection are cleared from the checkout session, as loyalty money usage is evaluated independently of credit card payment flows. * `loyalty_amount_to_use` and `loyalty_account_usages` are updated with the submitted values. **Backward Navigation**: * Navigating backward from this page does not alter the checkout state. **Next Pages**: * This is an independent step; the checkout flow continues to the page determined by the current checkout state. ```json {"openapi":"3.1.0","info":{"title":"Overview","version":"1.0.0"},"tags":[{"name":"Gift Cards, Gift Boxes & Loyalty","description":"# Checkout Gift Cards, Gift Boxes & Loyalty\n\nApply supplementary payment methods and gifting options that adjust the order total or add items to the order.\n\n**Gift Cards** let customers apply a pre-loaded card balance to their order. The flow supports OTP verification, multi-card application (when configured), amount adjustment, and removal.\n\n**Gift Boxes** let customers add gift packaging to their order.\n\n**Loyalty Points** let customers redeem accumulated points as a payment contribution.\n\n**Rewards** present available reward options that the customer can apply to the 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`\n\n## Dynamic Settings\n\n### GIFT_CARD_CONFIG\nConfiguration for the gift card feature:\n- `multi_card_enabled` — allows more than one gift card per order when enabled.\n- `max_amount_per_order` — maximum cumulative gift card amount per order (zero means no cap).\n- `balance_cache_ttl` — duration in seconds that a fetched card balance is cached.\n- `otp_resend_cooldown` — minimum interval in seconds between OTP resend requests.\n- `void_task_countdown` — delay in seconds before unused reservations are voided.\n\n### LOYALTY_MONEY_ENABLED\nMaster switch for the loyalty money payment feature. When disabled, the loyalty money step is not shown.\n\n### MINIMUM_ORDER_AMOUNT\nMinimum order total required after loyalty points are applied. Redemption is capped so the remaining amount does not fall below this threshold.\n\n### CUSTOMER_LOYALTY_CARD_SERVICE\nConfigures the service used to retrieve loyalty point balances and the optional minimum basket amount required before redemption is available."}],"servers":[{"description":"Akinon Checkout API","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com"}}}],"paths":{"/orders/checkout/?page=LoyaltyMoneyUsagePage":{"post":{"tags":["Gift Cards, Gift Boxes & Loyalty"],"operationId":"submitLoyaltyMoneyUsagePage","summary":"Set loyalty money amount to apply to the order","description":"Specifies the amount of loyalty money the user wishes to apply to the\ncurrent order. The submitted amount is stored in the checkout session\nand used when the payment is finalized.\n\nTwo input modes are supported:\n\n1. **Legacy mode** — submit `loyalty_amount_to_use` as a flat decimal\n amount. The system automatically distributes the debit across the\n user's accounts in label-priority order.\n2. **Label-based mode** — submit `account_usages` as a JSON-encoded\n array specifying the exact amount to debit from each account label.\n\nWhen both fields are provided, `loyalty_amount_to_use` takes precedence\nand `account_usages` is discarded.\n\n**Required Fields**:\n- At least one of `loyalty_amount_to_use` or `account_usages` must be\n present. Submitting `null` for `loyalty_amount_to_use` sets the applied\n amount to zero.\n\n**Validation**:\n- Each entry in `account_usages` must reference a label the user owns.\n- The requested amount per label must not exceed the available balance for\n that label.\n- `account_usages` must be a valid JSON array; a malformed value returns a\n validation error.\n\n**State Update**:\n- The selected payment option, card details, and installment selection are\n cleared from the checkout session, as loyalty money usage is evaluated\n independently of credit card payment flows.\n- `loyalty_amount_to_use` and `loyalty_account_usages` are updated with\n the submitted values.\n\n**Backward Navigation**:\n- Navigating backward from this page does not alter the checkout state.\n\n**Next Pages**:\n- This is an independent step; the checkout flow continues to the page\n determined by the current checkout state.","parameters":[{"$ref":"#/components/parameters/AjaxRequestHeader"},{"$ref":"#/components/parameters/SessionCookieHeader"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/LoyaltyMoneyUsagePageInput"}}}},"responses":{"200":{"description":"Loyalty money usage amount set successfully","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=`)","schema":{"type":"string"}}},"schemas":{"LoyaltyMoneyUsagePageInput":{"type":"object","properties":{"loyalty_amount_to_use":{"type":["number","null"],"format":"decimal","description":"The flat loyalty money amount to apply to the order, as a decimal value\nwith up to 12 digits and 2 decimal places (e.g., `\"50.00\"`). When\nprovided alongside `account_usages`, this field takes precedence and\n`account_usages` is ignored. Submit `0` or `null` to remove any\npreviously applied loyalty money amount."},"account_usages":{"type":["string","null"],"description":"A JSON-encoded array specifying the loyalty money amount to debit from\neach account label. Each array item must contain:\n- `label_id`: integer primary key of the account label, or `null` for\n unlabeled accounts\n- `amount`: decimal string representing the amount to debit from that\n label group\n\nThe requested amount per label must not exceed the user's available\nbalance for that label. Unlabeled accounts are referenced with\n`\"label_id\": null`. Malformed JSON returns a validation error.\n\nIgnored when `loyalty_amount_to_use` is also provided."}}},"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/gift-cards-gift-boxes-and-loyalty/set-loyalty-money-amount-to-apply-to-the-order.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.