> ## Documentation Index
> Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow hooks

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

A `hook` is a promise-returning callback function that you provide and that the
LoyaltyLion SDK executes 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.

## Hooks registration

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

<Warning>
  You may only register **one** hook for each hook kind. Attempting to register
  the same hook more than once throws an exception.
</Warning>

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

#### Example usage

```javascript theme={null}
loyaltylion.on('ready', () => {
  loyaltylion.registerHook(
    'customers.rewards.claimed',
    async ({ claimedReward }) => {
      // do something with the claimed reward here
      if (claimedReward.redeemable.code) {
        await myCustomCartPlatform.setDiscount(claimedReward.redeemable.code)

        myCustomModal.open('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 doesn't resolve in time, the LoyaltyLion SDK
uses the default action and proceed as if no hook was registered.

## Supported hooks

We currently support the following hooks:

* [`customers.rewards.claimed`](#customer-reward-claimed)

***

## Customer reward claimed

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

#### Callback payload

This hook is called with an object with a `claimedReward` property matching
the schema of our [rewards API](/api-reference/v2/resources/customers/rewards/redeem-reward).

```javascript theme={null}
{
  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.

```javascript theme={null}
return { action: 'hide_claim_modal' }
```

This hook supports two actions:

| Action string      | UI result                                                                |
| ------------------ | ------------------------------------------------------------------------ |
| `hide_claim_modal` | The LoyaltyLion SDK's claimed reward modal is closed                     |
| `show_claim_modal` | The LoyaltyLion SDK shows its standard post claimed reward modal content |

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