Get benefit offer

Purpose

Storyous calls this endpoint to obtain a benefit offer for a POS. The partner should evaluate inputs (codes, items, balances, benefit inputs) and return a structured offer indicating what can be applied.

How it’s used

POS may call “Get benefit offer” multiple times while the basket changes (codes, items, quantities, discounts).

Always echo back the loyaltyOfferId you received.

Our POS will send additional getBenefitOffer request before proceeding to payment and reporting of usage to check if the balance and finalPrice has changed. If it has changed, we will show the updated offer and if not, we will send the reportBenefitUsage request.

To prevent concurrent calls to the balance where customers can abuse the balance and move it to negative, you can lock the balance on your side based on merchantId-placeId-deviceNumber for minimum of 3 minutes and only allow reporting for this concrete deviceNumber requests. POS will check benefitOffer every time before checkout, so the block on your side will be needed for the amount of time needed from scanning the card to payment and reporting of usage. This is 99% solution cause there still might be a very minor edge-case where POS might go offline after clicking payment and before sending the usage, which will be an issue but it's a very minor case

Request highlights

benefitInputs[]: partner-specific codes or voucher numbers (e.g., "discount_10", "promo50", "10000006568304"). Inputs in this array may contain duplicates — it is up to the partner to decide whether to deduplicate or process them as-is.

balances[]: current state and POS choices (rejectedByPOS, requested controllableValueToUse).

itemsToPay[]: full basket lines with totalPriceWithVat, vatRate, etc.

pricePrecision: number of decimal places you should respect for monetary calculations.

posLang / billLang: use for localized posTitle / billTitle.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://your-api-server.com' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "checkId": "check-123", "loyaltyOfferId": "4d1dd08c4bcd1de163fbcbb8", "deviceNumber": 1, "currencyCode": "CZK", "countryCode": "CZ", "posLang": "cs", "billLang": "cs", "pricePrecision": 2, "benefitInputs": [ { "inputCode": "discount_10" }, { "inputCode": "discount_10" }, { "inputCode": "discount_10" } ], "balances": [ { "balanceId": "creditPoints", "usedControllableValue": 100, "usedNonControllableValue": 0, "prepaidValue": 0 } ], "itemsToPay": [ { "checkItemId": "37", "product": { "productId": "86", "name": "Juda Janík", "categories": [ { "categoryId": "97", "parentCategoryId": "30", "name": "Silvius Jašek" }, { "categoryId": "66", "parentCategoryId": "16", "name": "Zosim Braun" } ] }, "amount": 52.79, "measure": "commodo nulla sit ut sunt", "totalPriceWithVat": 603.39, "totalAppliedNonLoyaltyDiscounts": 41353865.624019235, "vatRate": -58645542.78854501, "vatId": 16640688.972712442 }, { "checkItemId": "43", "product": { "productId": "54", "name": "Radan Bílek", "categories": [ { "categoryId": "4", "parentCategoryId": "14", "name": "Mlad Vaněček" }, { "categoryId": "30", "parentCategoryId": "22", "name": "Pravomil Remeš" } ] }, "amount": 457.39, "measure": "reprehenderit", "totalPriceWithVat": 951.79, "totalAppliedNonLoyaltyDiscounts": 2791682.387805864, "vatRate": 23332169.45611897, "vatId": -21104467.408519387 } ], "merchantId": "59", "placeId": "91" }'

{ "customer": { "customerId": "8ea2591121e636086a4a9c0992-39056", "fullName": "John Smith", "loyaltyStatus": "Gold Member" }, "benefitInputs": [ { "applicable": true, "posTitle": "Discount 10", "inputCode": "crm_10", "reasonCode": null } ], "billMessages": [], "balances": [], "generalDiscounts": [ { "billTitle": "Sleva CRM-10", "generalDiscountId": "CRM-10", "isItemSpecific": true, "posTitle": "Sleva CRM-10", "valueToUse": 103 } ], "itemBenefitsToApply": [ { "benefits": [ { "absoluteTotalValue": 37.5, "appliedFromGeneralDiscountId": "CRM-10", "appliedFromBalanceId": null, "sourceType": "generalDiscount" }, { "absoluteTotalValue": 18.5, "appliedFromGeneralDiscountId": "CRM-10", "appliedFromBalanceId": null, "sourceType": "generalDiscount" }, { "absoluteTotalValue": 18.5, "appliedFromGeneralDiscountId": "CRM-10", "appliedFromBalanceId": null, "sourceType": "generalDiscount" }, { "absoluteTotalValue": 18.5, "appliedFromGeneralDiscountId": "CRM-10", "appliedFromBalanceId": null, "sourceType": "generalDiscount" } ], "checkItemId": "2025071121" } ], "loyaltyOfferId": "68230e36eb2894dfc71ed6d7", "posMessages": [ "Please apply discounts" ], "metadata": {} }

Request

Responses