Registration

During certification, you will be required to provide a registration webhook. When a merchant selects a generic integration as their loyalty provider, we will call this webhook in order to retrieve all the remaining configuration.

Webhook	Method	Purpose
Register Loyalty Provider 🔗	POST	This webhook is called when the merchant registers a your integration as a loyalty provider in Deliverect

Customer Management Webhooks

The following webhooks are called by our system to enable loyalty providers to manage customer data.

Webhook	Method	Purpose
Create Customer 🔗	POST	This webhook is triggered to create or update a customer profile.
Get Customer 🔗	GET	This webhook is triggered to retrieve a customer's profile details. Your system will receive this request when our system needs to fetch a customer's information, including their unique loyalty customer ID and other relevant profile data.

Tier System Webhook

The tier system allows loyalty providers to define and manage customer loyalty tiers. Your system will receive a webhook to provide a list of these tiers.

Webhook	Method	Purpose
Get Loyalty Tiers 🔗	GET	This webhook is triggered when our system needs to retrieve a list of all available loyalty tiers. Your system should respond with details about each tier, such as its name, a description, and the point requirements to achieve it. This information is used by our channel partners to build a user interface that shows a customer's progress and the benefits of reaching higher tiers.

Wallet Application Lifecycle

The lifecycle of applying a loyalty wallet as a discount to an order follows a clear tree-step process, with your system receiving webhooks at each stage.

Webhook	Method	Purpose
Get Customer Wallet 🔗	GET	This webhook is triggered to retrieve a customer's wallet balance. Your system should respond with the customer's available funds in the form of cash and/or loyalty points. This data is essential for our system to display the customer's current balance, allowing them to make informed decisions about using their rewards.
Validate Wallet Application 🔗	POST	This webhook is initiated by our system to validate a customer's request to use cash or points from their loyalty wallet as a discount on a current order. Your system, as the loyalty provider, is responsible for performing the necessary business rule checks and returning the discount amount and type.
Create Order 🔗	POST	This webhook is called when an end customer places an order. Here the loyalty provider can redeem the applied discounts created from the wallet.
Cancel Order 🔗	POST	This webhook is called an order is cancelled. Here the loyalty provider can revert any redemptions or transactions done when the order was created

Program Application Lifecycle

The lifecycle of applying a loyalty program to an order follows a clear three-step process, with your system receiving webhooks at each stage.

Webhook	Method	Purpose
Retrieve Loyalty Programs 🔗	POST	This webhook is called to get a list of all loyalty programs a customer is eligible for. Your system should respond with a list of programs, which our channel partners will use to populate a list of available rewards in their user interfaces.
Validate Loyalty Program application 🔗	POST	This webhook is called to validate that selected programs are applicable to the current basket. Your system should respond with the specific discounts that should be applied to the order.
Create Order 🔗	POST	This webhook is triggered when an order is finalized and placed or when an order is cancelled. When an order is created, your system should handle the automatic redemption of all applied loyalty programs in the basket. This includes deducting loyalty points, marking coupons as used, or processing any other redemption logic.
Cancel Order 🔗	POST	This webhook is triggered when an order is is cancelled. For order cancelation, your system should revert any transactions or redemptions that were performed for that order, ensuring that loyalty points are returned and any program usage is undone.

Authentication via SSO

A customer has the possibility to start the experience from a dedicated app and then use an external ordering channel to place an order. To simplify the process and remove friction we offer a Single Sign On (SSO) feature, that allows the customer to login in his loyalty app remaining connected when he moves to the ordering platform.

Webhook	Method	Purpose
SSO: Oauth token exchange 🔗	POST	This endpoint performs the last step of a classic OAuth2.0 authentication, exchanging an authorization code for an access token. For more information, see SSO documentation

Channel requirements for SSO

Generic channels needs to support the following webhook in order to support SSO flows for loyalty providers

Webhook	Method	Purpose
Channel SSO: Authorization 🔗	POST	This webhook will be called when when a customer attempts to authenticate to their service when bering redirected from a 3rd party application. For more information, see SSO documentation

Partner Loyalty workflow

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'mainBkg': '#ffffff'}}}%%

sequenceDiagram
    participant M as Merchant
    participant DR as Deliverect
    participant LP as Loyalty Partner (Webhook Receiver)
    participant Ch as Ordering Channel

    Note over M,LP: Registration (during certification)
    M->>DR: Selects generic integration as loyalty provider
    DR->>LP: POST Register Loyalty Provider
    LP-->>DR: Remaining configuration

    Note over DR,LP: Optional SSO Authentication
    DR->>LP: POST SSO: OAuth token exchange (auth code)
    LP-->>DR: Access token
    DR->>Ch: POST Channel SSO: Authorization
    Ch-->>DR: Authentication result

    Note over DR,LP: Customer Management
    DR->>LP: POST Create Customer (create/update profile)
    LP-->>DR: Customer profile
    DR->>LP: GET Get Customer
    LP-->>DR: Profile + loyalty customer ID

    Note over DR,LP: Tier System
    DR->>LP: GET Get Loyalty Tiers
    LP-->>DR: List of tiers (name, description, point requirements)

    Note over DR,LP: Wallet Application Lifecycle
    DR->>LP: GET Get Customer Wallet
    LP-->>DR: Wallet balance (cash / points)
    DR->>LP: POST Validate Wallet Application
    LP-->>DR: Discount amount & type (after business-rule checks)

    Note over DR,LP: Program Application Lifecycle
    DR->>LP: POST Retrieve Loyalty Programs
    LP-->>DR: List of eligible programs
    DR->>LP: POST Validate Loyalty Program application
    LP-->>DR: Discounts to apply to basket

    Note over DR,LP: Order Completion
    alt Order placed
        DR->>LP: POST Create Order
        LP-->>DR: Redeem discounts / deduct points / mark coupons used
    else Order cancelled
        DR->>LP: POST Cancel Order
        LP-->>DR: Revert redemptions / return points
    end