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

# Membership Object

> Fields returned for a customer's loyalty membership summary by the Yuko REST API.

The membership object summarizes a customer's standing in your loyalty program: points balance, current VIP tier, next tier and progress toward it. It's returned by [Get customer membership](/developer/api/list-memberships) (`GET /public/customers/memberships`, requires the `read:customers` scope).

<Note>
  This object describes loyalty program membership. Paid membership plans (Membership → Plans) aren't available through the REST API.
</Note>

## Properties

<ResponseField name="status" type="string">
  The customer's membership status. Always `active` for a customer returned by this endpoint.
</ResponseField>

<ResponseField name="member_since" type="string<date-time>">
  When the customer was added to Yuko (ISO 8601).
</ResponseField>

<ResponseField name="points" type="object">
  The customer's points summary.

  <Expandable title="points properties">
    <ResponseField name="balance" type="integer">
      The customer's spendable points balance. Always `0` for a customer who is banned or excluded from the loyalty program by a customer tag.
    </ResponseField>

    <ResponseField name="earned" type="integer">
      Total points the customer has earned.
    </ResponseField>

    <ResponseField name="redeemed" type="integer">
      Total points the customer has redeemed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_tier" type="object | null">
  The customer's current VIP tier, or `null` if VIP tiers are turned off or the customer hasn't reached a tier.

  <Expandable title="tier properties">
    <ResponseField name="id" type="string<uuid>">
      The tier's unique identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      The tier's name.
    </ResponseField>

    <ResponseField name="threshold_value" type="integer">
      The value needed to reach the tier.
    </ResponseField>

    <ResponseField name="multiplier" type="number">
      The tier's points multiplier, `1` when none is set.
    </ResponseField>

    <ResponseField name="icon" type="object | null">
      The tier's icon.
    </ResponseField>

    <ResponseField name="benefits" type="object[]">
      The tier's benefits.

      <Expandable title="benefit properties">
        <ResponseField name="name" type="string">
          The benefit's name.
        </ResponseField>

        <ResponseField name="benefit_type" type="enum<string>">
          One of `fixed`, `percentage`, `free_product`, `free_shipping`, `bonus_points`, `store_credit`, `custom`.
        </ResponseField>

        <ResponseField name="benefit_value" type="object">
          The benefit's value configuration. Its structure depends on `benefit_type`; see [List VIP tiers](/developer/api/list-vip-tiers).
        </ResponseField>
      </Expandable>
    </ResponseField>

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

<ResponseField name="next_tier" type="object | null">
  The next VIP tier the customer can reach, with the same fields as `current_tier`. `null` if VIP tiers are turned off, the customer hasn't been evaluated for tiers yet, or the customer is already at the highest tier.
</ResponseField>

<ResponseField name="progress_to_next_tier" type="object | null">
  The customer's progress toward `next_tier`, or `null` if VIP tiers are turned off or there's no next tier.

  <Expandable title="progress properties">
    <ResponseField name="current_value" type="integer">
      The customer's current qualifying value, rounded down.
    </ResponseField>

    <ResponseField name="required_value" type="integer">
      The value needed for the next tier.
    </ResponseField>

    <ResponseField name="remaining_value" type="integer">
      How much more is needed.
    </ResponseField>

    <ResponseField name="progress_percentage" type="number">
      Progress as a percentage, rounded to 2 decimal places.
    </ResponseField>

    <ResponseField name="threshold_type" type="string | null">
      The metric used for tier progression (`total_earned_points`, `total_amount_spents` or `total_orders`). Can be `null` even when VIP tiers are set up.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json The Membership object theme={null}
  {
    "status": "active",
    "member_since": "2025-11-02T10:15:00+00:00",
    "points": {
      "balance": 650,
      "earned": 1200,
      "redeemed": 550
    },
    "current_tier": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Silver",
      "threshold_value": 500,
      "multiplier": 1,
      "icon": null,
      "benefits": [],
      "created_at": "2025-01-10T09:00:00+00:00"
    },
    "next_tier": {
      "id": "7fb39c85-3a3f-4247-8333-2e05a9c8ae28",
      "name": "Gold",
      "threshold_value": 2000,
      "multiplier": 1.5,
      "icon": null,
      "benefits": [],
      "created_at": "2025-01-10T09:00:00+00:00"
    },
    "progress_to_next_tier": {
      "current_value": 1200,
      "required_value": 2000,
      "remaining_value": 800,
      "progress_percentage": 60,
      "threshold_type": "total_earned_points"
    }
  }
  ```
</ResponseExample>


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