# List purchases

`GET https://api.coach-platform.com/api/public/purchases`

List customer purchases. Filter by status, traineeId or productId.

- Resource: Purchases
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/get-purchases
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number (1-based, default 1) Minimum: `1`. |
| `limit` | integer | No | Number of items to return (default 25, max 500) Minimum: `1`. Maximum: `500`. |
| `status` | string | No | Allowed values: `ACTIVE`, `EXPIRED`, `CANCELLED`, `PENDING`, `WAITING_FOR_PAYMENT`. |
| `traineeId` | string | No |   |
| `productId` | string | No |   |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object[] |   |
| `data[].id` | string |   |
| `data[].coachId` | string |   |
| `data[].traineeId` | string |   |
| `data[].productId` | string |   |
| `data[].purchaseDate` | string<date-time> |   |
| `data[].expirationDate` | string<date-time> |   |
| `data[].purchaseAmount` | number |   |
| `data[].currency` | string | Allowed values: `ILS`, `USD`, `EUR`, `GBP`. |
| `data[].status` | string | Allowed values: `ACTIVE`, `EXPIRED`, `CANCELLED`, `PENDING`, `WAITING_FOR_PAYMENT`. |
| `data[].initialCredits` | number |   |
| `data[].remainingCredits` | number |   |
| `data[].membershipStartDate` | string<date-time> |   |
| `data[].membershipEndDate` | string<date-time> |   |
| `data[].currentPeriodUsages` | number |   |
| `data[].periodResetDate` | string<date-time> |   |
| `data[].createdAt` | string<date-time> |   |
| `data[].updatedAt` | string<date-time> |   |
| `pagination` | object |   |
| `pagination.page` | number |   |
| `pagination.limit` | number |   |
| `pagination.total` | number \| null | Total number of matching items. null when the underlying source cannot report an exact count for this page; use hasMore to keep paging. |
| `pagination.hasMore` | boolean |   |
| `pagination.truncated` | boolean | Present and true when the result set exceeded the in-memory scan cap and was truncated. Narrow your filters to page through all items. |

Example:

```json
{
  "data": [
    {
      "id": "<string>",
      "coachId": "<string>",
      "traineeId": "<string>",
      "productId": "<string>",
      "purchaseDate": "<date-time>",
      "expirationDate": "<date-time>",
      "purchaseAmount": 123,
      "currency": "ILS",
      "status": "ACTIVE",
      "initialCredits": 123,
      "remainingCredits": 123,
      "membershipStartDate": "<date-time>",
      "membershipEndDate": "<date-time>",
      "currentPeriodUsages": 123,
      "periodResetDate": "<date-time>",
      "createdAt": "<date-time>",
      "updatedAt": "<date-time>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "hasMore": true,
    "truncated": true
  }
}
```

### Error responses 400, 401, 403, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request GET \
  --url 'https://api.coach-platform.com/api/public/purchases' \
  --header 'Authorization: Bearer cp_live_...'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/purchases', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer cp_live_...',
  },
});

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

## Related endpoints

- [Record a purchase](https://www.coach-platform.com/docs/api/reference/post-purchases/index.md): `POST /api/public/purchases`. Record a product purchase for a trainee.
- [Get a purchase](https://www.coach-platform.com/docs/api/reference/get-purchases-purchase-id/index.md): `GET /api/public/purchases/{purchaseId}`. Get a customer purchase by id.
- Previous: [Get a product](https://www.coach-platform.com/docs/api/reference/get-products-product-id/index.md): `GET /api/public/products/{productId}`. Get a product by id.
- Next: [Record a purchase](https://www.coach-platform.com/docs/api/reference/post-purchases/index.md): `POST /api/public/purchases`. Record a product purchase for a trainee.