# List member rewards

> Returns a list of rewards earned by a specific member.

Breadcrumb: API › List member rewards
Docs index: https://docs.cevoid.com/developers/llms.txt

`GET https://api.cevoid.com/v2/members/{profile_id}/rewards`

Returns a list of rewards earned by a specific member.

## Authorizations

Bearer token in the Authorization header: `Authorization: Bearer <key>` (API key).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `profile_id` | `string` | Yes | Cevoid profile ID. Example: `prf_abc123`. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | No | Opaque cursor returned from a previous list response Example: `eyJpZCI6InBvc3RfMDEifQ`. |
| `limit` | `integer` | No | Page size between 1 and 100 Range: `1 <= x <= 100`. Example: `25`. |
| `type` | `string \| string[]` | No | Optional list of reward types to include. Example: `["DISCOUNT_CODE","PRODUCT"]`. |
| `fulfillment_status` | `string \| string[]` | No | Optional list of fulfillment statuses to include. Example: `["FULFILLED_AUTO","UNFULFILLED"]`. |

## Response

### 200: Successful response

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | Yes | Items returned for this page. |
| `data[].id` | `string` | Yes | Cevoid earned reward ID. Example: `rwd_01hzy3d4mk8w2q`. |
| `data[].title` | `string` | Yes | Reward title at the time it was awarded. Example: `10% Off Reward`. |
| `data[].description` | `string` | No | Member-facing reward description. Example: `Get 10% off your next order.`. |
| `data[].type` | `enum<string>` | Yes | Reward type. Allowed values: `BADGE`, `DISCOUNT_CODE`, `CUSTOM`, `POINTS`, `PRODUCT`. Example: `DISCOUNT_CODE`. |
| `data[].icon_url` | `string<uri>` | No | Reward icon URL. Example: `https://cdn.cevoid.com/rewards/reward-icon.png`. |
| `data[].svg_icon` | `string` | No | Inline SVG icon markup. Example: `<svg viewBox="0 0 24 24">...</svg>`. |
| `data[].fulfillment_status` | `enum<string>` | Yes | Current fulfillment state. Allowed values: `UNFULFILLED`, `IN_PROGRESS`, `RETRYING`, `FAILED_AUTO`, `FAILED_THIRD_PARTY`, `FULFILLED_MANUAL`, `FULFILLED_AUTO`, `FULFILLED_THIRD_PARTY`, `CANCELLED`, `EXPIRED`. Example: `FULFILLED_AUTO`. |
| `data[].fulfilled_at` | `string<date-time>` | No | Timestamp when fulfillment completed. Example: `2026-01-15T10:00:00.000Z`. |
| `data[].failed_reason` | `string` | No | Reason fulfillment failed. Example: `No discount codes available`. |
| `data[].awarded_at` | `string<date-time>` | No | Timestamp when the reward was awarded. Example: `2026-01-15T09:30:00.000Z`. |
| `data[].invalidated_at` | `string<date-time>` | No | Timestamp when the reward was invalidated. Example: `2026-02-01T00:00:00.000Z`. |
| `data[].badge` | `object` | No | Badge-specific reward details. |
| `data[].badge.type` | `enum<string>` | Yes | Badge presentation type. Allowed values: `DEFAULT`, `CUSTOM`. Example: `DEFAULT`. |
| `data[].badge.location` | `string` | No | Badge placement metadata. Example: `profile`. |
| `data[].badge.icon` | `string` | No | Badge icon identifier. Example: `star`. |
| `data[].badge.color` | `string` | No | Badge accent color. Example: `#ffb800`. |
| `data[].points` | `object` | No | Points-specific reward details. |
| `data[].points.amount` | `number` | Yes | Points granted by the reward. Example: `100`. |
| `data[].discount_code` | `object` | No | Discount-code reward details. |
| `data[].discount_code.code` | `string` | Yes | Discount code granted to the member. Example: `SUMMER10`. |
| `data[].discount_code.external_discount_code_id` | `string` | No | Discount code identifier in the source system, when applicable. Example: `discount-code-12345`. |
| `data[].discount_code.expires_at` | `string<date-time>` | No | Timestamp when the discount code expires. Example: `2026-12-31T23:59:59.999Z`. |
| `data[].discount_code.one_time_use_per_customer` | `boolean` | Yes | Whether the member can use the code only once. Example: `true`. |
| `data[].discount_code.value_type` | `enum<string>` | No | Discount value type. Allowed values: `FIXED_AMOUNT`, `PERCENTAGE`, `FREE_SHIPPING`. Example: `PERCENTAGE`. |
| `data[].product` | `object` | No | Product reward details. |
| `data[].product.id` | `string` | No | Cevoid product ID. Omitted when the historical product can no longer be resolved. Example: `7391056823401`. |
| `data[].product.code` | `string` | Yes | Product reward code granted to the member. Example: `FREE-MUG-001`. |
| `data[].product.product_url` | `string<uri>` | No | Resolved storefront URL for the rewarded product. Example: `https://store.example.com/products/free-mug`. |
| `data[].product.external_discount_code_id` | `string` | No | Discount code identifier in the source system, when applicable. Example: `discount-code-12345`. |
| `data[].product.expires_at` | `string<date-time>` | No | Timestamp when the product reward code expires. Example: `2026-12-31T23:59:59.999Z`. |
| `data[].product.one_time_use_per_customer` | `boolean` | Yes | Whether the member can claim the reward only once. Example: `true`. |
| `data[].usages` | `object[]` | Yes | Recorded reward usages. |
| `data[].usages[].order_id` | `string` | No | Cevoid order ID. Omitted when a historical order cannot be resolved. Example: `ord_01hzy3d4mk8w2q`. |
| `data[].usages[].order_number` | `string` | No | Human-readable Order number. Example: `#1001`. |
| `data[].usages[].domain` | `string` | No | Store domain where the reward was used. Example: `store.example.com`. |
| `data[].usages[].external_order_id` | `string` | No | Order identifier in the source system, when applicable. Example: `order-12345`. |
| `data[].usages[].used_at` | `string<date-time>` | No | Timestamp when the usage was recorded. Example: `2026-01-15T10:00:00.000Z`. |
| `has_more` | `boolean` | Yes | Whether another page of results is available. Example: `true`. |
| `next_cursor` | `string \| null` | Yes | Opaque cursor to request the next page, or null when the list is exhausted. Example: `eyJpZCI6InJlc291cmNlXzI1In0`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |

```json
{
  "data": [
    {
      "id": "rwd_01hzy3d4mk8w2q",
      "title": "10% Off Reward",
      "description": "Get 10% off your next order.",
      "type": "DISCOUNT_CODE",
      "icon_url": "https://cdn.cevoid.com/rewards/reward-icon.png",
      "fulfillment_status": "FULFILLED_AUTO",
      "fulfilled_at": "2026-01-15T10:00:00.000Z",
      "awarded_at": "2026-01-15T09:30:00.000Z",
      "discount_code": {
        "code": "SUMMER10",
        "external_discount_code_id": "discount-code-12345",
        "expires_at": "2026-12-31T23:59:59.999Z",
        "one_time_use_per_customer": true,
        "value_type": "PERCENTAGE"
      },
      "usages": []
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InJ3ZF8wMWh6eTNkNG1rOHcycSJ9"
}
```

### 400: Bad request

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | No | Optional machine-readable error details. |
| `additional_data.{key}` | `any` | No |  |
| `status` | `number` | Yes | HTTP status code for the error response. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable description of the error. Example: `Route not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers: the same as 200.

```json
{
  "additional_data": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "status": 400,
  "code": "bad_request",
  "message": "Bad request",
  "request_id": "req_abc123"
}
```

### 401: Unauthorized

`application/json`

Same fields as 400.

Response headers: the same as 200.

```json
{
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "request_id": "req_abc123"
}
```

### 403: Forbidden

`application/json`

Same fields as 400.

Response headers: the same as 200.

```json
{
  "status": 403,
  "code": "forbidden",
  "message": "Forbidden",
  "request_id": "req_abc123"
}
```

### 404: Not found

`application/json`

Same fields as 400.

Response headers: the same as 200.

```json
{
  "additional_data": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "status": 404,
  "code": "not_found",
  "message": "Route not found",
  "request_id": "req_abc123"
}
```

### 422: Validation error

`application/json`

Same fields as 400.

Response headers: the same as 200.

```json
{
  "additional_data": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "status": 422,
  "code": "validation_error",
  "message": "Validation error",
  "request_id": "req_abc123"
}
```

### 429: Too many requests

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | Yes | Machine-readable rate-limit details. |
| `additional_data.retry_after_seconds` | `integer` | Yes | Range: `0 <= x`. |
| `additional_data.{key}` | `any` | No |  |
| `status` | `integer` | Yes | HTTP status code. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable error description. Example: `Resource not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |
| `Retry-After` | `integer` | Seconds to wait before retrying the request |

```json
{
  "status": 429,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "request_id": "req_abc123",
  "additional_data": {
    "retry_after_seconds": 1
  }
}
```

### 500: Internal server error

`application/json`

Same fields as 400.

Response headers: the same as 200.

```json
{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal server error",
  "request_id": "req_abc123"
}
```

## Request example

```bash
curl 'https://api.cevoid.com/v2/members/prf_abc123/rewards' \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

---

Canonical: https://docs.cevoid.com/developers/api/members/list-member-rewards