> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuko.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List rewards

> Retrieves a paginated list of active loyalty rewards in your reward catalogue.

Shopify POS rewards aren't included. Results are sorted by `created_at`, newest first. To fetch a single reward, use [Retrieve a reward](/developer/api/retrieve-a-reward).

<Info>Requires the `read:rewards` scope. See [Scopes](/developer/api/scopes).</Info>

## Query parameters

<ParamField query="reward_type" type="enum<string>">
  Return only rewards of this type. One of `fixed`, `percentage`, `free_shipping`, `free_product`, `store_credit`.
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  The number of results per page, from `1` to `100`. Values above `100` are treated as `100`.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  The page number to retrieve. See [Classic pagination](/developer/api/classic-pagination).
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  The rewards on this page.

  <Expandable title="reward properties">
    <ResponseField name="id" type="string<uuid>">
      Unique identifier for the reward.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the reward.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      A description of the reward shown to customers.
    </ResponseField>

    <ResponseField name="reward_type" type="enum<string>">
      The type of reward issued to the customer. One of `fixed`, `percentage`, `free_shipping`, `free_product`, `store_credit`.
    </ResponseField>

    <ResponseField name="points_cost" type="integer">
      The number of points required to redeem this reward.
    </ResponseField>

    <ResponseField name="reward_rule" type="object">
      The rule configuration for this reward. Structure varies by `reward_type`.
    </ResponseField>

    <ResponseField name="icon" type="object | null">
      The reward's storefront icon, or `null` if none is set. Contains `source` (`default` or `custom`), `slug`, `id` and `url`. See [Retrieve a reward](/developer/api/retrieve-a-reward) for details.
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Whether this reward is currently active and available for redemption.
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time>">
      When the reward was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string<date-time>">
      When the reward was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="pagination" type="object">
      Pagination details. See [Classic pagination](/developer/api/classic-pagination).

      <Expandable title="pagination properties">
        <ResponseField name="current_page" type="integer">The page returned.</ResponseField>
        <ResponseField name="per_page" type="integer">The number of records per page.</ResponseField>
        <ResponseField name="total" type="integer">The total number of records.</ResponseField>
        <ResponseField name="last_page" type="integer">The number of the last page.</ResponseField>
        <ResponseField name="has_more" type="boolean">`true` if there are more pages after this one.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | Code | When |
| :- | :- | :- |
| `401` | `missing_token`, `invalid_token` | The API key is missing, wrong or revoked. |
| `403` | `insufficient_scope` | The key doesn't have `read:rewards`. |
| `429` | | The key exceeded the [rate limit](/developer/api/rate-limits). |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.yukoapp.com/api/v1/public/rewards?reward_type=fixed" \
    --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ reward_type: "fixed" });

  const response = await fetch(
    `https://api.yukoapp.com/api/v1/public/rewards?${params}`,
    {
      method: "GET",
      headers: {
        Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      },
    }
  );

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

  ```php PHP theme={null}
  $query = http_build_query(["reward_type" => "fixed"]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/rewards?{$query}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
        "name": "$5 off your next order",
        "description": "Redeem 500 points for a $5 discount.",
        "reward_type": "fixed",
        "points_cost": 500,
        "reward_rule": {
          "points_required": 500,
          "value": 5
        },
        "icon": null,
        "is_active": true,
        "created_at": "2025-12-01T09:00:00+00:00",
        "updated_at": "2025-12-01T09:00:00+00:00"
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "10% off your next order",
        "description": "Redeem 1000 points for 10% off.",
        "reward_type": "percentage",
        "points_cost": 1000,
        "reward_rule": {
          "points_required": 1000,
          "value": 10
        },
        "icon": null,
        "is_active": true,
        "created_at": "2025-12-01T09:00:00+00:00",
        "updated_at": "2025-12-01T09:00:00+00:00"
      }
    ],
    "meta": {
      "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 2,
        "last_page": 1,
        "has_more": false
      }
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "invalid_token",
      "message": "Invalid or revoked API token"
    }
  }
  ```
</ResponseExample>


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