custom_reward.redeemed

Fired when a customer redeems a custom reward — 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

This event cannot be subscribed to from Settings > Webhooks or through the subscriptions API. It is managed by the reward itself.

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. 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

{
  "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"
  }
}

{
  "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"
  }
}

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

REST API

API Resources

Webhook Events

Shopify Metafields

Configuring this event

Payload fields

Store-credit shops

Delivery and retries

Example payload

Common use cases

​Configuring this event

​Payload fields

​Store-credit shops

​Delivery and retries

​Example payload

​Common use cases

Configuring this event

Payload fields

Store-credit shops

Delivery and retries

Example payload

Common use cases