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

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

## Response

Returns `201 Created`.

| Field                       | Type            | Description                                                         |
| --------------------------- | --------------- | ------------------------------------------------------------------- |
| `earning_rule_id`           | string \| null  | The earning rule that was awarded                                   |
| `action`                    | string \| null  | The rule's action type                                              |
| `points`                    | integer         | Final points awarded after the multiplier                           |
| `base_points`               | integer \| null | Points before any multiplier                                        |
| `points_multiplier`         | number \| null  | The applied VIP tier multiplier (`null` when no tier boost applied) |
| `bonus_campaign_id`         | string \| null  | The active bonus campaign applied, or `null`                        |
| `bonus_campaign_multiplier` | number \| null  | The bonus campaign multiplier applied, or `null`                    |
| `status`                    | string          | `approved` or `pending`                                             |
| `points_given_at`           | string \| null  | When points were awarded, or `null` while pending                   |
| `points_due_at`             | string \| null  | When pending points will be approved                                |
| `points_expiry_at`          | string \| null  | When the points expire, or `null`                                   |
| `created_at`                | string          | ISO 8601 timestamp                                                  |
| `updated_at`                | string          | ISO 8601 timestamp                                                  |

<Note>
  When the rule has an approval delay configured, `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                   |
| `429`  | [Rate limit](/api-reference/rate-limits) exceeded (6 requests/second) |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mageloyalty.com/v1/earning-rules/rule_abc/award \
    --header 'Authorization: <api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
    "customer_identifier": "6789012345"
  }'
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
    {
      method: "POST",
      headers: {
        Authorization: "<api-key>",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customer_identifier: "6789012345",
      }),
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
      headers={"Authorization": "<api-key>"},
      json={
          "customer_identifier": "6789012345",
      },
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.mageloyalty.com/v1/earning-rules/rule_abc/award");
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: <api-key>",
          "Content-Type: application/json",
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "customer_identifier" => "6789012345",
      ]),
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created 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,
        "bonus_campaign_id": null,
        "bonus_campaign_multiplier": null,
        "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"
      }
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "errors": [
      {
        "status": "403",
        "title": "Forbidden",
        "detail": "Customer is excluded from the loyalty program"
      }
    ]
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "errors": [
      {
        "status": "404",
        "title": "Not Found",
        "detail": "Customer '6789012345' not found"
      }
    ]
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "errors": [
      {
        "status": "409",
        "title": "Conflict",
        "detail": "Customer has already been awarded points for this earning rule"
      }
    ]
  }
  ```

  ```json 422 Unprocessable theme={null}
  {
    "errors": [
      {
        "status": "422",
        "title": "Unprocessable",
        "detail": "Earning rule category 'purchase' cannot be awarded via the API. Only 'social' and 'engagement' rules are supported."
      }
    ]
  }
  ```
</ResponseExample>