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
get
GET /v2/tier-points/{account_tenant_fanid}/ledger HTTP/1.1
Host: 
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"
    }
  ]
}
PreviousLookupNextOverride

Last updated