Ledger

Retrieve the tier points transaction history 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/tier-points/{{account_tenant_fanid}}/ledger

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

Query Parameters

Name	Required	Description
from	false	Transactions pre-dating this parameter will be excluded. RFC3339 format.
to	false	Transactions after this parameter will be excluded. RFC3339 format.
page_id	false	Page id for pagination. You may read history as far as page 12 only.

Response

There will be at most 200 transactions per page in the ledger response.

Example

View Example JSON Response

{
    "txns": [
        {
            "txn_id": "7877ef01-3942-4f6e-aa95-f1839fe25b7c",
            "tenant_id": 100002,
            "txn_status": "ADD",
            "creation_time": "2025-05-02T19:22:46Z",
            "multiplier": 1,
            "multiplier_type": "fancash",
            "amount": "101.0",
            "test_txn": true,
            "external_id": "eddeb2bf-d0ef-499d-ad79-74febfdf5eee",
            "ref_id": "f9177af0-1d8e-4aa3-981b-847049f235e5",
            "ref_id_type": "fancash_id",
            "notes": "test data seeding",
            "initiated_by": "FBG",
            "extra_data": {
                "badge_value": "1x",
                "external_id_type": "SPORTS_BOOK_BETTING"
            }
        },
        {
            "txn_id": "e6e7b93e-3e80-4df8-9fd0-8a0044a1f36e",
            "tenant_id": 100002,
            "txn_status": "ADD",
            "creation_time": "2025-05-02T19:22:43Z",
            "multiplier": 1,
            "multiplier_type": "fancash",
            "amount": "101.0",
            "test_txn": true,
            "external_id": "4dcfae53-659e-40b4-b7c7-33a11f79e791",
            "ref_id": "f551da4b-59c7-4275-804c-fc2fcecdd854",
            "ref_id_type": "fancash_id",
            "notes": "test data seeding",
            "initiated_by": "FBG",
            "extra_data": {
                "badge_value": "1x",
                "external_id_type": "SPORTS_BOOK_BETTING"
            }
        }
    ]
}

Normal Response Data Explained

Field	Type	Description
txns	array	List of transaction records returned by the endpoint.
txns[].txn_id	string (UUID)	Backend-generated unique transaction identifier.
txns[].tenant_id	integer	Numeric identifier of the tenant associated with the transaction.
txns[].txn_status	string	Transaction status code (e.g., ADD).
txns[].creation_time	string (datetime)	ISO 8601 (RFC 3339) timestamp (UTC/Z) when the transaction was created.
txns[].multiplier	number	Multiplier value associated with the transaction. Informational.
txns[].multiplier_type	string	Type/category of the multiplier (e.g., fancash).
txns[].amount	string	Amount applied for this transaction, as a stringified number.
txns[].test_txn	boolean	Indicates whether the transaction was created in test mode.
txns[].external_id	string (UUID)	Caller-supplied external transaction identifier.
txns[].ref_id	string (UUID)	Reference identifier linking to an external record.
txns[].ref_id_type	string	Type/category of the reference ID (e.g., fancash_id, order_id).
txns[].notes	string	Free-form notes stored with the transaction.
txns[].initiated_by	string	Identifier for the source system or agent that initiated the transaction. This is not used to filter transactions based on OpCo / business function origin.
txns[].extra_data	object	Additional metadata saved with the transaction.

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 tier points ledger

get

get tier points ledger. Requires the tier_points:read permission.

Path parameters

account_tenant_fanidstring · uuidRequired

Account Tenant Fan ID

Query parameters

page_idstringOptional

Page ID for pagination

fromstringOptional

From date in RFC3339 format

tostringOptional

To date in RFC3339 format

Header parameters

AuthorizationstringRequired

User or server 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/tier-points/{account_tenant_fanid}/ledger

HTTPcURLJavaScriptPython

GET /v2/tier-points/{account_tenant_fanid}/ledger HTTP/1.1
Authorization: text
Accept: */*

{
  "txns": [
    {
      "amount": "text",
      "creation_time": "text",
      "external_id": "text",
      "extra_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "initiated_by": "text",
      "multiplier": 1,
      "multiplier_type": "text",
      "notes": "text",
      "ref_id": "text",
      "ref_id_type": "fancash_id",
      "tenant_id": 1,
      "test_txn": true,
      "txn_id": "text",
      "txn_status": "text"
    }
  ]
}