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

# Purchase a reward

> Redeem a reward for a customer, deducting points and generating a discount code.

Purchase a reward on behalf of a customer, deducting the required points from their balance and generating a Shopify discount code.

## 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
* Reward must be active and not deleted
* If the reward is restricted to a VIP tier, the customer must be on that tier
* Customer must have enough points to cover the reward's `points_cost`

## Side effects

All non-blocking:

* Generates a Shopify discount code
* Deducts points from the customer using FIFO logic
* Creates an activity log entry
* Fires Klaviyo, Omnisend, and Postscript reward-redeemed events
* Syncs Shopify metafields for the customer

## Response

Returns `201 Created`:

```json theme={null}
{
  "data": {
    "type": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_abc",
      "reward_name": "£5 off your next order",
      "reward_discount_type": "fixed_amount",
      "points_spent": 500,
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "is_refunded": false,
      "discount_code_redeemed_at": null,
      "redeemed_at": null,
      "expires_at": "2024-07-01T00:00:00.000Z",
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}
```

## Errors

| Status | Scenario                                                   |
| ------ | ---------------------------------------------------------- |
| `400`  | `customer_identifier` missing or invalid JSON              |
| `403`  | Customer is excluded, or not on the required VIP tier      |
| `404`  | Customer or reward not found                               |
| `422`  | Insufficient points                                        |
| `503`  | Unable to connect to Shopify to generate the discount code |

**Example 422 response:**

```json theme={null}
{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}
```