Bulk Bonus FanCash Earn

Use this endpoint to issue FanCash to multiple users in batches.

Pre-Conditions

• You do NOT need to know the Account Tenant FanIDs for the users' accounts; although issuance by AccountTenant FanID is supported, as a convenience, the caller of this API may provide the email address for the user to receive the Bonus FanCash instead.

• This API requires either a server-to-server auth token. User auth tokens don't make since her because this API impacts multiple user accounts.

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

Required Scopes

bonus_fancash:bulk_bonus_earn

Request

URL

/v1/bonus-fancash/bulk-bonus-earn

Headers

Name	Description
Authorization	contains server-to-server Bearer token for accessing the API

Data

Bonus FanCash Request Wrapper

Property	Description
bonus_fancash_entries	array containing entries for issuing bonus FanCash

Bonus FanCash Request Wrapper -> Bonus FanCash Entries -> item

Property	Description
amount	dollar amount of FanCash written as a string NOT a number. supports fractional dollar amounts up to six decimal places
campaign_id	unique identifier for a marketing campaign in which FanCash is awarded
site_id	six-digit identifier for the website on which the FanCash is being awarded. As an integration partner, this number will have been assigned and provided to you as part of your API onboarding
currency	ISO currency code for the FanCash issuance. Only USD is supported for now. Please pass USD only.
account_tenant_fanid	unique identifier representing the user in a non-Fanatics system as a proxy for their internal fanatics id. Each vendor will have their own account_tenant_fan_id for a user. This value is a property of the ID Token returned in the SSO login process.
email	if account_tenant_fan_id is present, email is not required. Plaintext email address of the user to receive the FanCash. Our APIs handle normalization and hashing. It is NOT necessary to normalize the address by lowercasing it, removing dots before the at-sign, or removing the trailing plus sign and any tokens following it
expiry_dt	date in the future when the Bonus FanCash will expire if not used, must be no farther in the future than 1 year from the current date - Format: ISO 8601 (RFC 3339) - Timezone: Please supply only UTC formatted timestamp strings, example: 2025-08-06T18:30:00.000Z
segment_name	an identifier representing a personalization / profiling group of which the user receiving the FanCash is a member and that the Bonus FanCash award is related to their group membership
start_dt	just pass the current date and time here to save yourself some trouble - Format: ISO 8601 (RFC 3339) - Timezone: Please supply only UTC formatted timestamp strings, example: 2025-08-06T18:30:00.000Z

Response

Normal Response Data

Bonus FanCash Response Wrapper

Property	Description
data	object to contain the response data; a wrapper within a wrapper

Bonus FanCash Response Wrapper -> Data

Property	Description
bonus_fancash_response	array containing entries related to those in the request
failure_count	number of transaction entries that did not successfully complete
success_count	number of transaction entries that were completed successfully
transaction_count	total number of entries in the response; should be the same as the number of entries in the request, and this value should equal the sum of the error_count and the success_count

Bonus FanCash Response Wrapper -> Data -> Bonus FanCash Response

Property	Description
account_id	some integration partners have Fanatics generated pseudonymous identifiers for users. If this feature is enabled for your integration, this id value for the user will be returned here; if not, the value will be an empty string
campaign_id	the campaign_id from the entry in the request is echoed back in the response
email	the email address from the entry in the request is echoed back in the response.
message	additional contextual information describing the result of the requested transaction from the request entry.
status	indicates whether the requested transaction for this entry was successful or not

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 Specification

BonusFancash Bulk Bonus Earn

post

Bulk API for adding BonusFancash. Requires the bonus_fancash:bulk_bonus_earn permission.

Header parameters

AuthorizationstringRequired

User or server access Bearer token

Body

application/json

Responses

200

BonusFancash Bulk Add Response

application/json

400

Bad request

application/json

401

Forbidden

application/json

404

Not Found

application/json

429

Rate Limited

application/json

500

Internal error

application/json

post

/v1/bonus-fancash/bulk-bonus-earn

HTTPcURLJavaScriptPython

POST /v1/bonus-fancash/bulk-bonus-earn HTTP/1.1
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 313

{
  "bonus_fancash_entries": [
    {
      "account_tenant_fan_id": "56eeabe0-d6f0-11ec-b17e-d38c4cb36d49",
      "amount": "10.00",
      "campaign_id": "76eeabe0-d6f0-11ec-b17e-d38c4cb36d49",
      "currency": "USD",
      "email": "text",
      "expiry_dt": "2022-07-07T20:53:07.070Z",
      "segment_name": "test_segment",
      "site_id": 1,
      "start_dt": "2022-07-07T20:53:07.070Z"
    }
  ]
}

{
  "data": {
    "bonus_fancash_response": [
      {
        "account_id": "text",
        "campaign_id": "text",
        "email": "text",
        "message": "text",
        "status": "text"
      }
    ],
    "failure_count": 1,
    "success_count": 1,
    "transaction_count": 1
  }
}