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

# Get redeemable rewards

Retrieves the customer's points balance and the full reward catalogue with affordability info per reward. Intended as the primary endpoint for rendering a loyalty redemption UI.

**GET /public/customers/rewards/redeemable**

#### **Authorizations**

**Authorization**

**string**

**header**

**required**

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your REST API token.

#### **Required Scope**

**`rewards:read`**

This endpoint requires the `rewards` scope with **Read Access**. Configure token scopes in Settings → Integrations → REST API.

#### **Query Parameters**

**customer\_id**

**string**

**required**

The platform customer ID (e.g. Shopify customer ID)

Example:

`"9049402769586"`

#### **Response**

**200 - application/json**

**data**

**object**

Hide child attributes

**data.points\_balance**

**integer**

The customer's current redeemable points balance.

Example:

`650`

**data.rewards**

**object\[]**

The active reward catalogue for this organisation, enriched with affordability fields for this customer.

Hide child attributes

**data.rewards\[].id**

**string\<uuid>**

Example:

`"90424fa7-e8a9-4ef4-b43a-72c9b2028db5"`

**data.rewards\[].name**

**string**

Example:

`"$5 off your next order"`

**data.rewards\[].description**

**string | null**

Example:

`"Redeem 500 points for a $5 discount."`

**data.rewards\[].reward\_type**

**enum\<string>**

Available options:

`fixed_discount`,

`percentage_discount`,

`free_shipping`,

`free_product`,

`store_credit`

Example:

`"fixed_discount"`

**data.rewards\[].points\_cost**

**integer**

The number of points required to redeem this reward.

Example:

`500`

**data.rewards\[].reward\_rule**

**object**

The rule configuration for this reward. Structure varies by `reward_type`.

Example:

`{ "points_required": 500, "discount_value": 5 }`

**data.rewards\[].can\_redeem**

**boolean**

Whether the customer currently has enough points to redeem this reward.

Example:

`true`

**data.rewards\[].points\_needed**

**integer**

The additional points needed to redeem this reward. `0` if `can_redeem` is `true`.

Example:

`0`

**data.customer\_rewards**

**object\[]**

The customer's previously redeemed coupons and discounts, sorted by `created_at` descending.

Hide child attributes

**data.customer\_rewards\[].id**

**string\<uuid>**

Example:

`"1fd80ced-326f-4082-951b-21a38632a603"`

**data.customer\_rewards\[].reward\_type**

**string | null**

Example:

`"fixed_discount"`

**data.customer\_rewards\[].status**

**enum\<string>**

Available options:

`active`, `used`, `inactive`, `expired`, `deleted`, `revert`

Example:

`"active"`

**data.customer\_rewards\[].discount\_code**

**string | null**

Example:

`"YUKO-TVJ-BL1"`

**data.customer\_rewards\[].points\_used**

**integer**

Example:

`500`

**data.customer\_rewards\[].expires\_at**

**string\<date-time> | null**

Example:

`"2026-06-01T00:00:00+00:00"`

**data.customer\_rewards\[].used\_at**

**string\<date-time> | null**

Example:

`null`

**data.customer\_rewards\[].created\_at**

**string\<date-time>**

Example:

`"2026-02-15T08:30:00+00:00"`

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

  ```javascript JavaScript theme={null}
  const customerId = "9049402769586";

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

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

  ```php PHP theme={null}
  $customerId = "9049402769586";

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/customers/rewards/redeemable?customer_id={$customerId}");
  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": {
      "points_balance": 650,
      "rewards": [
        {
          "id": "90424fa7-e8a9-4ef4-b43a-72c9b2028db5",
          "name": "$5 off your next order",
          "description": "Redeem 500 points for a $5 discount.",
          "reward_type": "fixed_discount",
          "points_cost": 500,
          "reward_rule": {
            "points_required": 500,
            "discount_value": 5
          },
          "can_redeem": true,
          "points_needed": 0
        },
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "10% off your next order",
          "description": "Redeem 1000 points for 10% off.",
          "reward_type": "percentage_discount",
          "points_cost": 1000,
          "reward_rule": {
            "points_required": 1000,
            "discount_percentage": 10
          },
          "can_redeem": false,
          "points_needed": 350
        }
      ],
      "customer_rewards": [
        {
          "id": "1fd80ced-326f-4082-951b-21a38632a603",
          "reward_type": "fixed_discount",
          "status": "active",
          "discount_code": "YUKO-TVJ-BL1",
          "points_used": 500,
          "expires_at": "2026-06-01T00:00:00+00:00",
          "used_at": null,
          "created_at": "2026-02-15T08:30:00+00:00"
        }
      ]
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Customer not found"
    }
  }
  ```

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