Add

Crediting an amount of tier points for a customer or bulk set of customers' balances.

Please note: This is an asynchronous endpoint

Preconditions

• This API requires a server-to-server auth token:

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

• Please do not submit any Personally Identifiable Information (e.g: email, phone number, customer name, address, ...) in any of the provided payload fields

Required Scopes

tier_points:update

Request

URL

/v2/tier-points/add

Method

POST

Headers

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

Request Object

• You may submit a maximum of 200 transactions in the payload

Field	Type	Required	Description
txns	array	true	List of transaction objects to be processed in the bulk request.
txns[].account_tenant_fanid	string (UUID)	true	Unique FanID for the customer’s account (tenant-specific).
txns[].amount	string	true	Amount of Tier Points to credit for this transaction. Supports two decimal precision.
txns[].external_id	string (UUID)	true	External transaction identifier, Please ensure uniqueness when submitting a value for this field. Duplicate transactions will be accepted but not processed.
txns[].extra_data	object	false	Additional metadata about the transaction. This entire object is converted and stored as text downstream. Size limitation: Long Text Area(1024) 1kb
txns[].initiated_by	string	false	Custom field to record which agent initiated the transaction. This is not used to filter transactions based on OpCo / business function origin.
txns[].multiplier	number	false	Numeric multiplier applied to the transaction amount. This is for record-keeping and does not modify amount submitted. It is expected that the amount supplied is the final calculated value.
txns[].multiplier_type	string	false	Type of multiplier being applied (e.g., fancash).
txns[].notes	string	false	Free-form notes associated with the transaction. Size limitation: Long Text Area(1024) 1kb
txns[].ref_id	string (UUID)	false	Reference identifier linking this transaction to an external system record.
txns[].ref_id_type	string	false	Type/category of the reference ID (e.g., fancash_id, order_id).
txns[].test_txn	boolean	false	Indicates whether this is a test transaction (true) or a live transaction (false).

Example

View Example JSON Payload

{
  "txns": [
    {
      "account_tenant_fanid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "amount": "0.51",
      "external_id": "fca432a9-447b-4d41-a058-bc934c14364e",
      "extra_data": {
        "badge_value": "1x",
        "external_id_type": "SPORTS_BOOK_BETTING"
      },
      "initiated_by": "FBG",
      "multiplier": 1,
      "multiplier_type": "fancash",
      "notes": "test data seeding",
      "ref_id": "5ed8209a-a505-4f36-a9ef-a2b22e98045b",
      "ref_id_type": "fancash_id",
      "test_txn": true
    },
    ...
  ]
}

Response

Please note: in most cases this endpoint will return 201 Status Created, but there may be issues with individual transactions. Please inspect the response body for an "ok" or "nok" for each transaction's status.

Response Object

Field	Type	Description
txns	array	List of transaction response objects returned by the bulk request.
txns[].account_tenant_fanid	string (UUID)	Unique FanID for the customer’s account (tenant-specific).
txns[].details	string	Additional information about the transaction result (may be empty if successful).
txns[].external_id	string (UUID)	External transaction identifier that was passed in the request.
txns[].result	string	Outcome of the transaction (e.g., "ok", "nok").
txns[].txn_id	string (UUID)	Backend-generated unique transaction identifier for tracking.

Examples

View Example Normal JSON Response

{
  "txns": [
    {
      "account_tenant_fanid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "details": "",
      "external_id": "fca432a9-447b-4d41-a058-bc934c14364e",
      "result": "ok",
      "txn_id": "abcd1234-abcd-abcd-abcd-abcdef123456" 
    }
  ]
}

View Example JSON Response With Transaction-level Issue ("nok")

{
  "txns": [
    {
      "account_tenant_fanid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "details": "Invalid account_tenant_fanid",
      "external_id": "fca432a9-447b-4d41-a058-bc934c14364e",
      "result": "nok"
    }
  ]
}

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

Add tier points

post

Add tier points. Requires the tier_points:update permission.

Header parameters

AuthorizationstringRequired

Server Bearer Token

Body

application/json

Responses

201

Created

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

post

/v2/tier-points/add

HTTPcURLJavaScriptPython

POST /v2/tier-points/add HTTP/1.1
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "txns": [
    {
      "account_tenant_fanid": "text",
      "amount": "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",
      "test_txn": true
    }
  ]
}

{
  "txns": [
    {
      "account_tenant_fanid": "text",
      "details": "text",
      "external_id": "text",
      "result": "ok/nok",
      "txn_id": "text"
    }
  ]
}