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

# custom_reward.redeemed

> Fired when a customer redeems a custom reward, so your system can fulfil it.

Fired when a customer redeems a [custom reward](https://help.mageloyalty.com) — a reward you fulfil yourself, such as a consultation, an event invite, or a gift sent by hand. Custom rewards do not generate a discount code, so this webhook is how your systems find out that a customer is waiting on you.

At this point the points have been deducted and the redemption is recorded. It does **not** mean the customer has received the reward yet — that is tracked separately when you mark the redemption as used in the Mage Loyalty dashboard.

## Configuring this event

<Note>
  This event cannot be subscribed to from **Settings > Webhooks** or through the [subscriptions API](/api-reference/webhooks/subscriptions/list). It is managed by the reward itself.
</Note>

To receive it, edit your custom reward in the Mage Loyalty dashboard, set **Notification method** to `Webhook` (or `Email & Webhook`) and enter your endpoint URL. Mage Loyalty creates a webhook subscription for that reward automatically and displays its signing secret once.

You can also set a **Reward identifier** — a short handle such as `surprise-gift-next-order` that is sent as `reward_identifier` so your automation can tell rewards apart without relying on the display name. Leave it blank and Mage Loyalty uses a slug of the reward name.

The subscription then behaves like any other: it appears in **Settings > Webhooks** marked *Managed by reward*, where you can send a test request and inspect delivery logs. Changing or removing the URL is done on the reward, and deleting the reward deletes the subscription.

The reward form also has a **Send test webhook** button, which delivers a payload with `test` set to `true` so you can confirm your endpoint before any customer redeems.

## Payload fields

| Field                 | Type           | Description                                                                                                                          |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `test`                | boolean        | `true` when sent by the **Send test webhook** button, `false` for a real redemption                                                  |
| `reward_identifier`   | string         | The reward identifier you set on the custom reward. If you left it blank, a slug of the reward name (e.g. `virtual-styling-session`) |
| `reward_name`         | string         | Name of the custom reward that was redeemed                                                                                          |
| `shopify_customer_id` | string \| null | The customer's Shopify customer ID                                                                                                   |
| `customer_email`      | string \| null | The customer's email address                                                                                                         |
| `customer_first_name` | string \| null | The customer's first name                                                                                                            |
| `customer_last_name`  | string \| null | The customer's last name                                                                                                             |
| `points_spent`        | integer        | Number of points spent on this redemption                                                                                            |
| `redeemed_at`         | string         | ISO 8601 timestamp of when the customer redeemed the reward                                                                          |

## Store-credit shops

Custom rewards are available on points-mode shops only, so this event never carries the `loyalty_mode`, `currency` or `credit_*` companion fields described in [Loyalty modes](/api-reference/loyalty-modes). `points_spent` is always a points value.

## Delivery and retries

Responding with any `2xx` status code marks the redemption's notification as delivered. Anything else is retried up to **5 times** with exponential backoff — more than the 3 retries used by other events, because this webhook is often the only signal that a customer is waiting.

After the final failed attempt the redemption is flagged as failed in the dashboard. The redemption itself is never reversed: the customer keeps the reward and it still appears on the reward's **Redemptions** page, which lists every customer who has redeemed regardless of webhook outcome.

## Example payload

<ResponseExample>
  ```json custom_reward.redeemed theme={null}
  {
    "event": "custom_reward.redeemed",
    "shop": "my-store",
    "timestamp": "2026-02-18T12:00:00.000Z",
    "data": {
      "test": false,
      "reward_identifier": "virtual-styling-session",
      "reward_name": "Virtual styling session",
      "shopify_customer_id": "6789012345",
      "customer_email": "jane@example.com",
      "customer_first_name": "Jane",
      "customer_last_name": "Doe",
      "points_spent": 5000,
      "redeemed_at": "2026-02-18T11:59:58.000Z"
    }
  }
  ```

  ```json custom_reward.redeemed (test delivery) theme={null}
  {
    "event": "custom_reward.redeemed",
    "shop": "my-store",
    "timestamp": "2026-02-18T12:00:00.000Z",
    "data": {
      "test": true,
      "reward_identifier": "virtual-styling-session",
      "reward_name": "Virtual styling session",
      "shopify_customer_id": "0000000000",
      "customer_email": "owner@my-store.com",
      "customer_first_name": "Test",
      "customer_last_name": "Customer",
      "points_spent": 5000,
      "redeemed_at": "2026-02-18T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Common use cases

* Trigger a Zapier or Make automation that adds the customer to a booking sheet or CRM
* Create a ticket in a helpdesk so your team can arrange the reward
* Notify a fulfilment partner that a hand-packed gift needs sending
* Post to a Slack channel so whoever is on duty can follow up