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

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
Responses
201

Created

application/json
post
POST /v2/tier-points/add HTTP/1.1
Host: 
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"
    }
  ]
}
PreviousTier PointsNextVoid

Last updated