GraphQL API

The Rewards GraphQL API is designed to support and power the Rewards Front End JavaScript Library (SDK), which provides a ready-to-use, continuously evolving Rewards experience. All brands that use Rewards have access to the GraphQL API, ensuring flexibility for different technical needs and integration approaches.
For most use cases, we recommend using the Rewards Front End JavaScript Library (SDK). The SDK is actively maintained by the Rewards engineering team and benefits from ongoing feature development, improvements, and bug fixes. By using the SDK, brands can automatically take advantage of new functionality as it becomes available, without the need to implement or maintain these features themselves.
The GraphQL API can be used as a complement to the SDK or as a standalone solution in cases where custom functionality is required that is not currently supported by the SDK. When considering direct use of the GraphQL API, it is helpful to clearly define the intended use case, as similar or equivalent functionality may already exist or be planned within the SDK.
Choosing the SDK allows brands to focus on their core experience while relying on a dedicated Rewards team to manage the underlying Rewards front-end features. Brands that build a fully custom Rewards front end using the GraphQL API gain greater control and flexibility, but will also be responsible for implementing and maintaining new end-to-end features as they are introduced.
This document provides a complete technical reference for integrating with the Fasttrack Rewards GraphQL API. It covers authentication using JWT tokens, available queries and mutations for accessing and managing rewards, bonuses, challenges, shop items, and user data, as well as real-time subscriptions. Developers can use this guide to understand the schema, build API requests, and implement the rewards features.

🌟 Playground:

Playground: https://<brand-name>.ft-crm.com/rewards-graphql-api/

🔒 Authentication

To access the API:
  1. You must pass a JWT token with the following claims:
    1. iat (Issued At): Unix timestamp
    2. exp (Expiration): Unix timestamp
    3. user_id: String or integer
  2. The JWT must be signed with the JWT-secret provided to Fasttrack.
In the Playground:
  1. Go to the Headers section.
  2. Add:

📜 GraphQL Schema Overview

The schema provides root types for:
  1. Queries
  2. Mutations
  3. Subscriptions

🔎 Queries

QueryReturn TypeDescription
​getUserBonusesV2​
[UserBonusV2!]!
Fetch user bonuses.
​getUserCalendarByID(request: GetUserCalendarByIDRequest!​
​GetUserCalendarByIDResponse​
Get a user calendar by ID.
getMenu​
​GetMenuResponse!
Retrieve the menu structure.
GetConfiguration​
​Configuration!
Get brand configuration settings.
GetUser​
​User!
Fetch user profile information.
​GetUserChallenges(includeCompleted: Boolean = false)​
[Challenge]!
List challenges for the user.
​Reward​
​Reward​
Retrieve reward program info.
​getShopPageByID(id: Int!)
​GetShopPageByIDResponse​
Get a shop page by ID.

✍️ Mutations

MutationDescription
​ claimWheelPrize(input: ClaimWheelPrizeInput)​
Claim a prize from a wheel spin.
spinWheel(input: SpinWheelInput)​
Spin the reward wheel.
InitializeWheel​
Initialize the wheel for spinning.
consumeBonusV2(userBonusId: Int!)​
Consume a user bonus.
openCalendarDoor(calendarId: Int!, doorId: Int!)​
Open a door on a calendar.
buyShopItem(shopPageId: Int, shopItemVariationId: Int!)​
Purchase an item from the shop.

🔔 Subscriptions

Real-time updates over WebSocket:
SubscriptionReturn TypeDescription
StatusUpdate​
​StatusUpdate!
Receive live status updates.

🧹 Type Definitions

UserBonusV2

BonusV2

📆 Calendar Types

GetUserCalendarByIDRequest:

GetUserCalendarByIDResponse

UserCalendar

CalendarDoor

📋 Menu

GetMenuResponse

MenuItem

⚙️ Configuration

Configuration

🛡️ Other Important Types

Level:

VirtualCurrency:

Branding:

Reward

👤 User

User

LoyaltyBalance

UserWallet

WheelToken

🌟 Challenges

Challenge

Task

ChallengeAppearence

🛒 Shop

GetShopPageByIDResponse

ShopPage

ShopItem

🏆 Wheel & Prizes

Wheel

ClaimWheelPrizeInput

SpinWheelResponse

Prize

PrizeOption

Path

PathPrize

InitializeWheelResponse

UnclaimedPrize

📈 Status Update

StatusUpdate

✅ Notes

  1. Always use Bearer tokens correctly in authentication headers.
  2. Fields and types are strictly typed; incorrect input formats may lead to errors.