Get loyalty benefit usages

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.

Rate Limiting
To protect the API and ensure fair usage, this endpoint is rate-limited.

Limit: 6 requests per minute

Applied per:

clientId (application) -> Different clients do not share the same rate-limit pool

loyaltyProviderId

merchantId (optional)

placeId (optional)

If the limit is exceeded, the API responds with:

HTTP/1.1 429 Too Many Requests
{
  "error": "Too many requests",
  "message": "Rate limit exceeded (6 requests per minute)."
}

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://api.storyous.com/loyaltyProgrammesAdvanced/advanced/byProvider//benefitUsages?cursor=undefined&fromDate=undefined&merchantId=&placeId=&status=pending%2Cfailed' \ --header 'Authorization: Bearer <token>'

Request

Responses