Workflow Hooks

The LoyaltyLion SDK provides the ability for you to hook into various workflows to further customise the user experience.


A hook is a promise-returning callback function that you provide and that the LoyaltyLion SDK will execute when certain hook-enabled events occur.

Hooks enable you to ‘hook into’ certain frontend workflows, giving you an opportunity to make calls to other services, render your own UI, and influence the behavior of the LoyaltyLion SDK.

For example, you may provide a hook for the customers.rewards.claimed hook event that calls a storefront API to automatically add a discount to the cart, or make a call to your own app to trigger fulfillment of a custom reward.

Your hook should return a promise which resolves to an object which contains an action property. The action is a string that informs what the LoyaltyLion UI should do next.

Each kind of hook has its own set of supported actions, depending on the underlying use case and workflow.

Registering hooks

Hooks are registered using the loyaltylion.registerHook method. This method accepts two arguments:

  • hookName - string, name of the hooked event to register
  • callback - the function to be called when the hooked event occurs

You may only register one hook for each hook kind. Attempting to register the same hook more than once will throw an exception.

Hooks should be registered once the LoyaltyLion SDK is ready, see below for an example.

Example usage

loyaltylion.on('ready', () => {
    async ({ claimedReward }) => {
      // do something with the claimed reward here
      if (claimedReward.redeemable.code) {
        await myCustomCartPlatform.setDiscount(claimedReward.redeemable.code)'Your discount has been applied!')

      return { action: 'hide_claim_modal' }

Hook requirements

Your hook must return a response with a valid action within 5 seconds. If it returns an invalid payload or does not resolve in time, the LoyaltyLion SDK will use the default action and proceed as if no hook was registered.

Supported hooks

We currently support the following hooks:

Customer reward claimed

This hook is called after a customer has successfully used their points to claim a reward. It will enable you to implement things like automatically applying a reward to a cart if your platform supports this capability.

Callback payload

This hook will be called with an object with a claimedReward property matching the schema of our rewards API.

  claimedReward: {...} // see claimed reward docs for detailed schema

Supported return actions

This action should be indicated by the return of your callback function, e.g.

return { action: 'hide_claim_modal' }

This hook supports two actions:

Action stringUI result
hide_claim_modalThe LoyaltyLion SDK’s claimed reward modal will be closed
show_claim_modalThe LoyaltyLion SDK will show its standard post claimed reward modal content

The show_claim_modal action will be used as the default in case of invalid return value or timeout.