> ## 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 VIP tiers

> Retrieves all VIP tiers configured for your organisation, with their benefits.

Tiers are sorted by `threshold_value` in ascending order. Each tier includes its associated benefits.

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

## Response

<ResponseField name="data" type="object[]">
  The VIP tiers, lowest threshold first.

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

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

    <ResponseField name="threshold_value" type="integer">
      The value a customer must reach to qualify for this tier, measured in the program's tier metric: amount spent (default), points earned or orders placed, as configured in your VIP settings.
    </ResponseField>

    <ResponseField name="multiplier" type="number">
      The points earning multiplier applied to customers in this tier.
    </ResponseField>

    <ResponseField name="icon" type="object | null">
      The tier icon, or `null` if none is set. Always has four keys: `source` (`default` or `custom`), `slug` (built-in icons, otherwise `null`), `id` (custom uploads, otherwise `null`) and `url` (the custom upload URL, or the hosted SVG for a built-in icon).
    </ResponseField>

    <ResponseField name="benefits" type="object[]">
      A list of benefits associated with this tier.

      <Expandable title="benefit properties">
        <ResponseField name="name" type="string">
          The display name of the benefit.
        </ResponseField>

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

        <ResponseField name="benefit_value" type="object">
          The stored value configuration for this benefit, returned as-is. Structure varies by `benefit_type`. For example, `fixed`/`percentage` benefits include `reward_type`, `method` (`automatic` or `one_time`), `discount_value`, `coupon_prefix` and `min_requirement`; `bonus_points` and `store_credit` include `method`, `reward_type` and `discount_value`; `custom` benefits may be empty.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string<date-time> | null">
      When the tier was created (ISO 8601).
    </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:tiers`. |
| `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/tiers" \
    --header "Authorization: Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.yukoapp.com/api/v1/public/tiers",
    {
      method: "GET",
      headers: {
        Authorization: "Bearer py_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      },
    }
  );

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

  ```php PHP theme={null}
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://api.yukoapp.com/api/v1/public/tiers");
  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": "7fb39c85-3a3f-4247-8333-2e05a9c8ae28",
        "name": "Silver",
        "threshold_value": 500,
        "multiplier": 1.5,
        "icon": null,
        "benefits": [
          {
            "name": "5% Discount on every order",
            "benefit_type": "percentage",
            "benefit_value": { "reward_type": "percentage", "method": "automatic", "discount_value": 5 }
          }
        ],
        "created_at": "2025-09-12T15:44:44+00:00"
      },
      {
        "id": "8ac40d96-4b4e-5358-9444-3f16bab9bf39",
        "name": "Gold",
        "threshold_value": 1000,
        "multiplier": 2.0,
        "icon": { "source": "custom", "slug": null, "id": "12", "url": "https://example.com/gold-icon.png" },
        "benefits": [
          {
            "name": "10% Discount on every order",
            "benefit_type": "percentage",
            "benefit_value": { "reward_type": "percentage", "method": "automatic", "discount_value": 10 }
          },
          {
            "name": "Free Shipping",
            "benefit_type": "free_shipping",
            "benefit_value": { "method": "automatic", "coupon_prefix": "VIPSHIP", "min_requirement": { "type": "none" } }
          }
        ],
        "created_at": "2025-09-12T15:44:44+00:00"
      }
    ]
  }
  ```

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