Lookup

Retrieve the tier points balance and associated tier information for the given user.

Preconditions

• This API requires either a server-to-server or user access auth token:

• You can generate a server-to-server token using the S2S Auth API

• User access tokens are returned from the Code Exchange step of the SSO auth process.

Required Scopes

tier_points:read

Request

URL

/v2/loyalty/{{account_tenant_fanid}}/lookup

Method

GET

Headers

Name	Required	Description
Authorization	true	a user or s2s Bearer token for accessing the API

Path Parameters

Name	Required	Description
account_tenant_fanid	true	Unique FanID for the customer’s account (tenant-specific).

Response

Example

This user has a Gold status-match override and has not yet earned points towards the earn goal. Without the overide, their 202.00 points balance would mean their tier is "member+" as shown below in the "current_period_tier" response entity.

View Example JSON Response

{
    "tier_points": {
        "balance": {
            "active": "202.00",
            "current_period_earn": "202.00",
            "rollover": "0.00",
            "lifetime": "202.00"
        },
        "public_facing_tier": {
            "tier": {
                "name": "gold",
                "id": "c4fa79b5-c9b4-47ba-b933-91aa8d10556f",
                "min_threshold": "2500.00"
            },
            "next_tier": {
                "name": "platinum",
                "id": "d1683d85-ef0d-480e-861b-d7e659d5b0c2",
                "min_threshold": "10000.00"
            }
        },
        "current_period_tier": {
            "earned_tier": {
                "name": "member+",
                "id": "a9187104-01b3-4278-bf85-3ba2dba953dc",
                "min_threshold": "100.00"
            },
            "next_earn_tier": {
                "name": "gold",
                "id": "c4fa79b5-c9b4-47ba-b933-91aa8d10556f",
                "min_threshold": "2500.00"
            },
            "points_to_next_earn_tier": "2298.00"
        },
        "invite_approval_map": {
            "b10ac910-1de0-4dcc-b752-d913e1bde70b": {
                "tier": "black",
                "approved": false
            },
            "b662797e-3427-4aa8-ad89-104a4347a62b": {
                "tier": "infinite",
                "approved": false
            }
        },
        "tier_overrides": [
            {
                "active": true,
                "type": "status_match",
                "campaign": "override-1",
                "tier": {
                    "name": "gold",
                    "id": "c4fa79b5-c9b4-47ba-b933-91aa8d10556f",
                    "min_threshold": "2500.00"
                },
                "note": "TEST Note...",
                "start": "2025-05-06T19:00:01Z",
                "expiry": "2026-01-01T00:00:00Z",
                "trial": {
                    "start": "2025-05-06T19:00:01Z",
                    "expiry": "2025-08-04T19:00:01Z",
                    "target_points": "1234.56",
                    "tier_min_threshold": "0.00",
                    "start_balance": {
                        "active": "202.00",
                        "current_period_earn": "202.00",
                        "rollover": "0.00",
                        "lifetime": "202.00"
                    },
                    "points_left_to_keep_override": "1234.56"
                }
            }
        ]
    }
}

Normal Response Data Explained

Field	Type	Description
tier_points	object	High-level response hierarchy for a customer’s tier points profile.
tier_points.balance	object	Contains the customer’s tier points balance.
tier_points.balance.active	string	The customer’s current active balance of Tier Points. Sum of current_period_earn and rollover.
tier_points.balance.current_period_earn	string	Tier points earned during the current period.
tier_points.balance.rollover	string	Tier points carried over from the last reset period. Based on tier rules, not existing rollover.
tier_points.balance.lifetime	string	Total lifetime tier points earned (excluding rollover).
tier_points.public_facing_tier	object	Customer’s public-facing tier status (what should be shown to the customer).
tier_points.public_facing_tier.tier	object	Details of the customer’s current public-facing tier (calculated with balance + overrides).
tier_points.public_facing_tier.tier.name	string	Current public-facing tier name.
tier_points.public_facing_tier.tier.id	string	UUID of the current public-facing tier.
tier_points.public_facing_tier.tier.min_threshold	string	Minimum tier points required for the tier (without overrides).
tier_points.public_facing_tier.next_tier	object	Details of the next public-facing tier above the customer’s current one.
tier_points.current_period_tier	object	Customer’s actual earned tier details for the current period (without overrides).
tier_points.current_period_tier.earned_tier	object	Tier that the customer has earned based on their current points.
tier_points.current_period_tier.next_earn_tier	object	Next tier the customer can earn into.
tier_points.current_period_tier.points_to_next_earn_tier	string	Points still needed to reach the next earned tier.
tier_points.invite_approval_map	object	Map of invite-only tiers and whether the customer is approved.
tier_points.tier_overrides	array	List of overrides applied to the customer’s tier (e.g. status matches, campaigns).
tier_points.tier_overrides[].active	boolean	Whether the override is currently active.
tier_points.tier_overrides[].type	string	Type of override (e.g. status match).
tier_points.tier_overrides[].campaign	string	Identifier for the override campaign.
tier_points.tier_overrides[].tier	object	Tier granted by the override.
tier_points.tier_overrides[].note	string	Notes about the override.
tier_points.tier_overrides[].start	string (datetime)	Start date/time of the override.
tier_points.tier_overrides[].expiry	string (datetime)	Expiry date/time of the override.
tier_points.tier_overrides[].trial	object	Trial-specific override details.
tier_points.tier_overrides[].trial.start	string (datetime)	Start date/time of the trial period.
tier_points.tier_overrides[].trial.expiry	string (datetime)	Expiry date/time of the trial period.
tier_points.tier_overrides[].trial.target_points	string	Target number of points required during the trial.
tier_points.tier_overrides[].trial.tier_min_threshold	string	Minimum threshold applied to the trial tier.
tier_points.tier_overrides[].trial.start_balance	object	Customer’s starting balance when the trial began.
tier_points.tier_overrides[].trial.start_balance.active	string	Active balance at the trial start.
tier_points.tier_overrides[].trial.start_balance.current_period_earn	string	Current-period earnings at trial start.
tier_points.tier_overrides[].trial.start_balance.rollover	string	Rollover balance at trial start.
tier_points.tier_overrides[].trial.start_balance.lifetime	string	Lifetime earnings at trial start.
tier_points.tier_overrides[].trial.points_left_to_keep_override	string	Points still required to keep the override tier after trial ends.

Error Response Data

Error Response Wrapper

Property	Description
errors	array containing error response entries
rc	randomly generated identifier allowing call tracing within Fanatics. When reporting repeated errors or coordinating issue resolution with Fanatics, this value will assist in diagnosing any issues.
timestamp	processing timestamp in Zulu time of Fanatics API server using ISO 8601 format (https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). Useful for issue resolution with Fanatics as log data is partitioned by date and time.

Error Response Wrapper -> Errors -> item

Property	Description
code	Fanatics error code for the specific error; this is generally not an http status code. Code values are generally stable for the API.
message	additional textual information describing the error. This is useful in debugging, but should not be checked programmatically

Full Spec

Get the loyalty tier status and balance for a user.

get

Get the loyalty tier status and balance for a user. Requires the tier_points:read permission.

Path parameters

account_tenant_fanidstring · uuidRequired

Account Tenant Fan ID

Header parameters

AuthorizationstringRequired

User or server access Bearer Token

Responses

200

OK

application/json

400

[FAIL] Bad request

application/json

401

[FAIL] Unauthorized

application/json

429

[FAIL] Rate Limited

application/json

500

[FAIL] Internal error

application/json

get

/v2/loyalty/{account_tenant_fanid}/lookup

HTTPcURLJavaScriptPython

GET /v2/loyalty/{account_tenant_fanid}/lookup HTTP/1.1
Host: 
Authorization: text
Accept: */*

{
  "fancash": {
    "balance": "text",
    "expiration_breakdown": [
      {
        "amount": "text",
        "expiration": "text",
        "type": "text"
      }
    ]
  },
  "tier_points": {
    "balance": {
      "active": "text",
      "current_period_earn": "text",
      "lifetime": "text",
      "rollover": "text"
    },
    "current_period_tier": {
      "earned_tier": {
        "id": "text",
        "min_threshold": "text",
        "name": "text"
      },
      "next_earn_tier": {
        "id": "text",
        "min_threshold": "text",
        "name": "text"
      },
      "points_to_next_earn_tier": "text"
    },
    "invite_approval_map": {
      "ANY_ADDITIONAL_PROPERTY": {
        "approved": true,
        "tier": "text"
      }
    },
    "public_facing_tier": {
      "next_tier": {
        "id": "text",
        "min_threshold": "text",
        "name": "text"
      },
      "tier": {
        "id": "text",
        "min_threshold": "text",
        "name": "text"
      }
    },
    "tier_overrides": [
      {
        "active": true,
        "campaign": "text",
        "expiry": "2022-07-07T20:53:07.070Z",
        "extra_data": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "note": "text",
        "start": "2022-07-07T20:53:07.070Z",
        "tier": {
          "id": "text",
          "min_threshold": "text",
          "name": "text"
        },
        "trial": {
          "expiry": "text",
          "points_left_to_keep_override": "text",
          "start": "text",
          "start_balance": {
            "active": "text",
            "current_period_earn": "text",
            "lifetime": "text",
            "rollover": "text"
          },
          "target_points": "text",
          "tier_min_threshold": "text"
        },
        "type": "text"
      }
    ]
  }
}