Report benefit usage

Testing

Webhook

POST

When a benefit usage occurs, this webhook is triggered.

The request payload contains detailed information including:

Offer and provider: loyaltyOfferId, loyaltyProviderId

Customer and bill: customerId, billId, paidAt, billState, etc.

Purchased items: amounts, applied benefits, VAT details

Payment details: balances used and other payment values

The provider is expected to process this notification and return 200 OK in response.

After receiving a successful 200 OK, the corresponding benefitUsage is marked as synchronized in Storyous.

If the provider does not respond with 200 OK, Storyous applies a retry mechanism.

Retries are attempted multiple times with increasing delayed intervals until the request succeeds or the retry limit is reached.

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

SPV voucher reportingGeneral discount code reportingReport payment by balance

curl --location --request POST 'https://your-api-server.com' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "loyaltyOfferId": "ca22a5df2e5faadffc13db6b",
    "status": "pending",
    "loyaltyProviderId": "3ac7ab362d33c8af0d5d86e4",
    "deviceNumber": 1234165,
    "benefitInputs": [
        {
            "inputCode": "happyBeer25"
        }
    ],
    "customerId": "aca27caafcfd71df701edfeb",
    "billId": "3J2025000010",
    "paidAt": "2025-09-23T12:23:24.572Z",
    "currencyCode": "CZK",
    "keepLoyaltyBenefitsUsed": true,
    "billState": "issued",
    "paidItems": [
        {
            "originalCheckItemId": "11",
            "product": {
                "productId": "kxdEWSEac",
                "name": "Svíčková",
                "categories": [
                    {
                        "categoryId": "kbGc3OW9q",
                        "parentCategoryId": "kbGc3OW9o",
                        "name": "Main dishes"
                    },
                    {
                        "categoryId": "kbGc3OW9q",
                        "parentCategoryId": "kbGc3OW9o",
                        "name": "Main dishes"
                    }
                ]
            },
            "amount": 1,
            "measure": "pcs",
            "vatRate": 12,
            "totalPriceWithVat": 150,
            "appliedBenefits": [
                {
                    "sourceType": "balance",
                    "appliedFromBalanceId": "d004ce1ab6f070998ba73698",
                    "appliedFromGeneralDiscountId": "43",
                    "absoluteTotalValue": 50,
                    "applicationType": "discounr",
                    "negativeCheckItemId": "32"
                },
                {
                    "sourceType": "balance",
                    "appliedFromBalanceId": "dd7eaad1ee4f6db4fb5c8aad",
                    "appliedFromGeneralDiscountId": "51",
                    "absoluteTotalValue": 50,
                    "applicationType": "discounr",
                    "negativeCheckItemId": "51"
                }
            ]
        },
        {
            "originalCheckItemId": "72",
            "product": {
                "productId": "kxdEWSEac",
                "name": "Svíčková",
                "categories": [
                    {
                        "categoryId": "kbGc3OW9q",
                        "parentCategoryId": "kbGc3OW9o",
                        "name": "Main dishes"
                    }
                ]
            },
            "amount": 1,
            "measure": "pcs",
            "vatRate": 12,
            "totalPriceWithVat": 150,
            "appliedBenefits": [
                {
                    "sourceType": "balance",
                    "appliedFromBalanceId": "e9b4f96f9b1cee6b11addb3c",
                    "appliedFromGeneralDiscountId": "99",
                    "absoluteTotalValue": 50,
                    "applicationType": "discounr",
                    "negativeCheckItemId": "7"
                }
            ]
        },
        {
            "originalCheckItemId": "13",
            "product": {
                "productId": "kxdEWSEac",
                "name": "Svíčková",
                "categories": [
                    {
                        "categoryId": "kbGc3OW9q",
                        "parentCategoryId": "kbGc3OW9o",
                        "name": "Main dishes"
                    },
                    {
                        "categoryId": "kbGc3OW9q",
                        "parentCategoryId": "kbGc3OW9o",
                        "name": "Main dishes"
                    }
                ]
            },
            "amount": 1,
            "measure": "pcs",
            "vatRate": 12,
            "totalPriceWithVat": 150,
            "appliedBenefits": [
                {
                    "sourceType": "balance",
                    "appliedFromBalanceId": "ebf884c515ceece43e6facdc",
                    "appliedFromGeneralDiscountId": "39",
                    "absoluteTotalValue": 50,
                    "applicationType": "discounr",
                    "negativeCheckItemId": "71"
                }
            ]
        }
    ],
    "paymentsByBalances": [
        {
            "sourceType": "balance",
            "appliedFromBalanceId": "4c46b2babea17ea0cbd5fc97",
            "valueUsed": 100,
            "paymentMethodCode": "prepaidCredit"
        },
        {
            "sourceType": "balance",
            "appliedFromBalanceId": "5d4ec5feedfebc7daaf30fec",
            "valueUsed": 100,
            "paymentMethodCode": "prepaidCredit"
        },
        {
            "sourceType": "balance",
            "appliedFromBalanceId": "8720b414b09bbdee4e3fa73e",
            "valueUsed": 100,
            "paymentMethodCode": "prepaidCredit"
        }
    ],
    "usedBalances": [
        {
            "balanceId": "creditPoints",
            "usedControllableValue": 100,
            "usedNonControllableValue": 0,
            "prepaidValue": 0
        }
    ],
    "usedGeneralDiscounts": [
        {
            "generalDiscountId": "18",
            "usedValue": 91993463
        },
        {
            "generalDiscountId": "50",
            "usedValue": -56308932
        }
    ],
    "otherPaymentsValue": 340,
    "totalWithVat": 340,
    "countryCode": "PY",
    "metadata": "laborum",
    "merchantId": "35",
    "placeId": "19"
}'

Response Example

{}

Report offer validation error

Get loyalty benefit usages