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

# points.earned

> Fired when a customer earns points through any channel — purchases, earning rules, manual adjustments, or referrals.

Fired when a customer earns points. This covers all sources: order-based earning rules, custom earning rules, manual adjustments, and referral bonuses.

## Payload fields

| Field                 | Type           | Description                                                                                                                                    |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `shopify_customer_id` | string         | The customer's Shopify customer ID                                                                                                             |
| `email`               | string \| null | The customer's email address                                                                                                                   |
| `points_earned`       | integer        | Number of points earned in this event                                                                                                          |
| `points_balance`      | integer        | The customer's total available points after this event                                                                                         |
| `lifetime_points`     | integer        | The customer's all-time total earned points                                                                                                    |
| `source`              | string         | How the points were earned. One of `order`, `earning_rule`, `manual`, `referral`, or `approval_cron` (points released after an approval delay) |
| `earning_rule_name`   | string \| null | Name of the earning rule, if applicable                                                                                                        |
| `order_number`        | string \| null | Shopify order number, if the points were earned from a purchase                                                                                |

## Example payload

<ResponseExample>
  ```json points.earned theme={null}
  {
    "event": "points.earned",
    "shop": "my-store",
    "timestamp": "2026-02-18T12:00:00.000Z",
    "data": {
      "shopify_customer_id": "6789012345",
      "email": "jane@example.com",
      "points_earned": 150,
      "points_balance": 700,
      "lifetime_points": 1200,
      "source": "earning_rule",
      "earning_rule_name": "Purchase reward",
      "order_number": "1042"
    }
  }
  ```
</ResponseExample>

## Common use cases

* Sync points to an external CRM or data warehouse
* Trigger a personalised email or SMS when a customer hits a milestone (e.g. 1000 lifetime points)
* Display a real-time notification on your storefront
* Update a customer profile in your CRM or marketing platform