Get loyalty benefit usages

Developing

GET

https://api.storyous.com/loyaltyAdvanced/byProvider/{provider}/benefitUsages

Description

Retrieves loyalty benefit usages with cursor-based pagination.

Page size: fixed at 20 items per request.

After pulling unsynchronized benefit usage mark them as synchronized

Two ways to query:

Use a cursor for sequential iteration over all records.
On the first call, do not include any query parameters.
The server will return the initial cursor, which you can then use to iterate through subsequent pages.

Use query parameters (without cursor) for filtered retrieval.

⚠️ Important: Do not mix cursor with other query parameters.

When using a cursor:

The response includes a nextCursor value.

This guarantees that all records can be retrieved reliably by following the cursor chain

Once there is no more data to retrieve, the response contains hasNext: false.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Path Params

Query Params

Responses

🟢200OK

application/json

Successfully retrieved benefit usages

Body

🟠401Unauthorized

🟠400Bad Request

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.storyous.com/loyaltyAdvanced/byProvider//benefitUsages?cursor&fromDate&merchantId=&placeId=&status=pending,failed' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Example 1

{
    "data": [
        {
            "loyaltyOfferId": "string",
            "status": "success",
            "loyaltyProviderId": "string",
            "deviceNumber": 0,
            "benefitInputs": [
                {
                    "inputCode": "string"
                }
            ],
            "customerId": "string",
            "billId": "string",
            "paidAt": "2019-08-24T14:15:22Z",
            "currencyCode": "string",
            "keepLoyaltyBenefitsUsed": true,
            "billState": "issued",
            "paidItems": [
                {
                    "originalCheckItemId": "string",
                    "product": {
                        "productId": "string",
                        "name": "string",
                        "categories": [
                            {
                                "categoryId": "string",
                                "parentCategoryId": "string",
                                "name": "string"
                            }
                        ]
                    },
                    "amount": 0,
                    "measure": "string",
                    "vatRate": 0,
                    "totalPriceWithVat": 0,
                    "appliedBenefits": [
                        {
                            "sourceType": "balance",
                            "appliedFromBalanceId": "string",
                            "appliedFromGeneralDiscountId": "string",
                            "absoluteTotalValue": 0,
                            "applicationType": "discount",
                            "negativeCheckItemId": "string"
                        }
                    ]
                }
            ],
            "paymentsByBalances": [
                {
                    "sourceType": "balance",
                    "appliedFromBalanceId": "string",
                    "valueUsed": 0,
                    "paymentMethodCode": "string"
                }
            ],
            "usedBalances": [
                {
                    "balanceId": "string",
                    "usedControllableValue": 0,
                    "usedNonControllableValue": 0,
                    "prepaidValue": 0
                }
            ],
            "usedGeneralDiscounts": [
                {
                    "generalDiscountId": "string",
                    "usedValue": 0
                }
            ],
            "otherPaymentsValue": 0,
            "totalWithVat": 0,
            "countryCode": "string"
        }
    ],
    "nextCursor": "string",
    "hasNext": true
}

Report benefit usage

Mark benefit usages as synchronized