Loyalty Benefits Integration Overview

This document describes the integration flows between POS, Storyous API, and Benefit Providers for handling loyalty benefits.
The purpose of the integration is to allow customers to redeem loyalty offers and discounts directly at the POS, while ensuring providers are reliably notified about benefit usage.

⚠️ Disclaimer
This API is currently in the design phase.
The specification, endpoints, and data structures are subject to change, and breaking changes may occur before the stable release.
Partners integrating at this stage should treat this as an early preview and be prepared to update their implementations.

Key Actors

POS (Point of Sale)
The merchant’s system where the customer interacts, discounts are scanned, and bills are created.

Storyous API
The intermediary platform handling requests between the POS and benefit providers. It manages offer discovery, validation, and benefit usage reporting.

Benefit Provider
External loyalty service that defines the benefits (discounts, vouchers, points) and validates their application.

Process Overview

Offer Discovery

The POS scans discount codes or QR codes presented by the customer.

Using these scanned codes, the POS requests available offers from the Storyous API.

The Storyous API forwards the request to the provider, who validates the codes and responds with applicable benefit offers.

See Get benefit offer for details.

The Storyous API then returns the validated benefit offer to the POS.

Note the codes are being scanned one by one and every addition leads to additional call to the provider, to get a fresh offer with all the inputs scanned.

Optional offer configuration

In case the offer contains some controllable balance(s), the POS lets waiter parametrise the usage of balances.

Any change of such input parameters will lead to another request to provider using the Storyous API, to validate and process the inputs, possibly to reflect them as an updated benefit offer.

Offer Acceptance and Usage

Once the customer accepts an offer, the POS creates a bill and notifies Storyous API.

The benefit usage can be reported to the provider via webhook (Storyous pushes the usage) or pull (the provider fetches usage records).

Offer Validation Errors

If Storyous detects a validation issue with the offer (e.g. the offer no longer applies), a validation error is reported back to the provider and to the POS.

See Report offer validation error for details.

Configuration requirements for providers

To enable integration with Storyous, each partner must provide the following configuration details:

Webhook URLs

Receive discount codes – POST endpoint for sending discount codes and receiving benefit offer (mandatory).

Report offer validation error (optional).
If not provided, the partner will not receive validation error notifications.

Benefit usage webhook – POST endpoint for sending benefitUsage (optional).
If not provided, the partner must rely on pulling benefit usages using GET /benefitUsages.

Authorization

A static Authorization header value that Storyous will include with every request to partner endpoints.

This header will be used for authentication of all calls from Storyous to the partner.

Endpoits exposed by Storyous api are authorized by storyous access token

Store-level configuration

The above URLs and authorization header values will be configured per store in Storyous, so each store can connect to the correct partner endpoints.

Data persistence note

It is up to the partner whether to store offers. In general, we do not expect partners to persist offers, since they are the ones providing them to Storyous.

Logging offers for later validation may be useful, but the usage report should be sufficient to track benefit usage.

If needed, partners can store small amounts of additional state in the metadata field. This will be reported along with the used offer back to the partner.

Integration Flows

The following sequence diagrams describe the supported flows:

Happy flow with webhook – Provider receives benefit usage via webhook.

Happy flow without webhook (provider pull) – Provider pulls benefit usage from Storyous.

Offer validation error flow – Error reported when an offer cannot be applied.

1. Flow with webhook

2. Happy flow without webhook (provider pull)

3. Offer validation error flow

Introduction

Loyalty Benefits Integration Overview#

Key Actors#

Process Overview#

Configuration requirements for providers#

Webhook URLs#

Authorization#

Store-level configuration#

Data persistence note#

Integration Flows#

1. Flow with webhook#

#

2. Happy flow without webhook (provider pull)#

#

3. Offer validation error flow#