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

# Award an earning rule

> Award points to a customer for completing an earning rule.

Award points to a customer for completing an earning rule action, using the rule's configured points and any applicable VIP tier multiplier.

Only `social` and `engagement` category rules can be awarded via the API. Rules in other categories (e.g. purchase, birthday, anniversary) are managed automatically by the platform.

Each rule can only be awarded **once per customer** — duplicate requests return `409 Conflict`.

## Request body

| Field                 | Type   | Required | Description                          |
| --------------------- | ------ | -------- | ------------------------------------ |
| `customer_identifier` | string | Yes      | Shopify customer ID or email address |

```json theme={null}
{
  "customer_identifier": "6789012345"
}
```

## Validations

* Customer must exist and not be excluded from the loyalty program
* Earning rule must be active
* Earning rule category must be `social` or `engagement`
* Customer must not have already been awarded points for this rule

## Side effects

All non-blocking:

* Creates a `CustomerEarningRule` record with points awarded (or pending if `approval_time > 0`)
* Logs the activity
* Syncs customer to Klaviyo, Omnisend, and Postscript
* Syncs Shopify metafields for the customer

## Response

Returns `201 Created`:

```json theme={null}
{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}
```

<Note>
  When `approval_time > 0` is configured on the rule, `status` will be `pending`, `points_given_at` will be `null`, and `points_due_at` will reflect when the points will be approved.
</Note>

## Errors

| Status | Scenario                                                       |
| ------ | -------------------------------------------------------------- |
| `400`  | `customer_identifier` missing or invalid JSON                  |
| `403`  | Customer is excluded from the loyalty program                  |
| `404`  | Customer or earning rule not found (or rule is inactive)       |
| `409`  | Customer has already been awarded points for this earning rule |
| `422`  | Earning rule category cannot be awarded via the API            |