Get benefit offer

Testing

Webhook

POST

getBenefitOffer

Purpose

Storyous calls this endpoint to obtain a benefit offer for a POS. The partner should evaluate inputs (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 (items, quantities, discounts).

Always echo back the loyaltyOfferId you received.

Request highlights

benefitInputs[]: partner-specific flags/codes (e.g., “discount_10”, "promo50”).

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.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Body Params application/json

Examples

Responses

🟢200Success

application/json

Body

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://your-api-server.com' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "checkId": "7689202504",
    "deviceNumber": 1,
    "currencyCode": "CZK",
    "countryCode": "CZ",
    "posLang": "cs",
    "billLang": "cs",
    "pricePrecision": 2,
    "benefitInputs": [
        {
            "inputCode": "dicount_10"
        },
        {
            "inputCode": "promo30"
        },
        {
            "inputCode": "7866567221"
        }
    ],
    "balances": [
        {
            "balanceId": "benefitPoints",
            "rejectedByPOS": false,
            "controllableValueToUse": 0,
            "valueToPrepay": 0
        },
        {
            "balanceId": "credit",
            "rejectedByPOS": false,
            "controllableValueToUse": 100,
            "valueToPrepay": 0
        },
        {
            "balanceId": "voucher",
            "rejectedByPOS": true,
            "controllableValueToUse": 0,
            "valueToPrepay": 0
        }
    ],
    "itemsToPay": [
        {
            "checkItemId": "2025071121",
            "product": {
                "productId": "prod-svickova-001",
                "name": "Svíčková",
                "categories": [
                    {
                        "categoryId": "main-dishes",
                        "parentCategoryId": "food",
                        "name": "Main Dishes"
                    }
                ]
            },
            "amount": 3.5,
            "measure": "pcs",
            "totalPriceWithVat": 3500,
            "totalAppliedNonLoyaltyDiscounts": 0,
            "vatRate": 1,
            "vatId": 1
        }
    ]
}'

Response Example

General discount

{
    "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": ""
}

Introduction

Report offer validation error