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

# List reward history

> List a customer's reward redemption history.

List a customer's redeemed reward history. The `identifier` can be a Shopify customer ID or email.

## Query parameters

| Parameter | Type | Description |
| - | - | - |
| `filter[status]` | string | Filter by status: `active`, `used`, `expired` |
| `sort` | string | Sort field. Prefix with `-` for descending. Options: `created_at`, `points_spent`. Default: `-created_at` |
| `page[number]` | integer | Page number (default: `1`) |
| `page[size]` | integer | Results per page (default: `20`, max: `100`) |

## Response

`redeemed_at` is the moment the customer redeemed (claimed) the reward and spent their points, which is also the entry's creation time. `discount_code_redeemed_at` is the separate, later moment when the customer actually used the discount code at checkout (it stays `null` until then).

`points_spent` is a minor-unit amount on store-credit shops. The `meta` object includes `loyalty_mode` and `currency` so you can read it correctly (see [Loyalty modes](https://developers.mageloyalty.com/api-reference/loyalty-modes.md)).

## Errors

| Status | Scenario |
| - | - |
| `404` | Customer not found |
| `429` | [Rate limit](https://developers.mageloyalty.com/api-reference/rate-limits.md) exceeded (6 requests/second) |

```bash cURL theme={null}
curl --request GET \
  --url https://api.mageloyalty.com/v1/customers/6789012345/reward-history \
  --header 'Authorization: <api-key>'
```

```bash cURL (filter + sort + page) theme={null}
curl --request GET \
  --url 'https://api.mageloyalty.com/v1/customers/6789012345/reward-history?filter[status]=active&sort=-created_at&page[number]=1&page[size]=20' \
  --header 'Authorization: <api-key>'
```

```javascript Node theme={null}
const params = new URLSearchParams({
  "filter[status]": "active",
  sort: "-created_at",
  "page[number]": "1",
  "page[size]": "20",
});

const response = await fetch(
  `https://api.mageloyalty.com/v1/customers/6789012345/reward-history?${params}`,
  {
    method: "GET",
    headers: { Authorization: "<api-key>" },
  }
);

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

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

response = requests.get(
    "https://api.mageloyalty.com/v1/customers/6789012345/reward-history",
    headers={"Authorization": "<api-key>"},
    params={
        "filter[status]": "active",
        "sort": "-created_at",
        "page[number]": 1,
        "page[size]": 20,
    },
)

data = response.json()
```

```php PHP theme={null}
<?php
$query = http_build_query([
    "filter[status]" => "active",
    "sort" => "-created_at",
    "page[number]" => 1,
    "page[size]" => 20,
]);
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/reward-history?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: <api-key>"],
]);
$data = json_decode(curl_exec($ch), true);
```

```json 200 OK theme={null}
{
  "data": [
    {
      "type": "reward_history_entry",
      "id": "cr_abc123",
      "attributes": {
        "reward_id": "reward_abc",
        "reward_name": "\u00a35 off your next order",
        "reward_discount_type": "fixed",
        "points_spent": 500,
        "discount_code": "MAGE-ABC123",
        "status": "active",
        "is_refunded": false,
        "discount_code_redeemed_at": null,
        "redeemed_at": "2024-06-01T12:00:00.000Z",
        "expires_at": "2024-07-01T12:00:00.000Z",
        "created_at": "2024-06-01T12:00:00.000Z",
        "updated_at": "2024-06-01T12:00:00.000Z"
      }
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "loyalty_mode": "points",
    "currency": "GBP"
  }
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.