Fasttrack Rewards GraphQL API Documentation

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: <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.