Store

Store Integration

The Store MCP gives you the full management surface for your listing — register your app, set pricing, publish, and run promos. This page lists each tool, then shows how your app verifies a student has paid for access at launch.

Tools

All tools require Store-admin access for the targeted app.

Tool What it does
register_app Register an already-approved Platform app in the Store catalog. You provide a Store-side slug, a reference to the Platform app (ref), and optional plan (priceCents, currency, additionalSeatCents, maxSeats) and listing metadata. Creates the catalog entry in an unpublished state — call set_app_published once the listing is ready.
update_app_plan Update the plan attached to a Store app: base priceCents, currency, optional additionalSeatCents (per-seat pricing beyond the included seats), and optional maxSeats. Existing values are preserved when fields are omitted, so you can change just one dimension at a time.
set_app_published Flip a Store app's published flag. Setting it to true makes the listing visible on store.timeback.com; false unpublishes it without deleting catalog state. Idempotent.
create_discount_code Create a discount code redeemable at checkout. Choose flat (cents off) or percent (basis points off), set an optional expiresAt, an optional redemption cap, and an optional app scope so the code only works for specific listings.
list_discount_codes List the discount codes you've created, optionally filtered by storeAppId or discount type. Returns the codes you can act on.
create_affiliate Create an affiliate with a unique referral code, a payoutShareBp (basis points of net sale paid out), and an optional app scope so the affiliate only earns on specific listings.
update_affiliate Update an existing affiliate's state (active/inactive), payoutShareBp, display name, contact email, or app scope. Idempotent.

The tools' full input schemas are served by the MCP server itself — your client fetches them on connection, so the field names and types stay in sync with whatever the server is currently running.

Check Student Access at Login

When a student launches your app, you need to confirm they have a paid, active profile for it before letting them in. This runs against the Platform's OneRoster API (not the Store) and takes two short requests.

Step 1: Mint a Platform access token

Use your clientId + clientSecret from app registration to mint a Bearer token. See Authentication for the full client-credentials flow:

curl -X POST https://platform.timeback.com/auth/1.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly"

Cache the returned access_token — it's valid for an hour.

Step 2: Resolve the student's sourcedId by email

GET /rostering/1.0/users returns one row when filtered by email. Trim the response to just the sourcedId:

curl "https://platform.timeback.com/rostering/1.0/users?filter=email='student@example.com'&fields=sourcedId" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "users": [{ "sourcedId": "11111111-2222-3333-4444-555555555555" }],
  "offset": 0,
  "limit": 10,
  "total": 1
}

If total is 0, the email isn't on TimeBack — deny access.

Step 3: Assert an active profile for your app

GET /rostering/1.0/users/{sourcedId}/profiles returns the user's profiles; filter by your applicationId and ask only for the fields you'll inspect:

curl "https://platform.timeback.com/rostering/1.0/users/11111111-2222-3333-4444-555555555555/profiles?applicationId=<YOUR_APP_ID>&userId=11111111-2222-3333-4444-555555555555&fields=profileType,status" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "userProfiles": [{ "profileType": "learning_app_profile", "status": "active" }],
  "offset": 0,
  "limit": 10,
  "total": 1
}

Treat the launch as authorized only when a profile exists and its status is active. An empty userProfiles array, a 404, or any status other than active means the student hasn't paid for your app (or their purchase was refunded) — deny the launch.

The same two requests run unchanged against sandbox.platform.timeback.com with sandbox credentials — useful when you're testing the entitlement gate before publishing.

Related Docs

Store → Introduction

What the Store provides, the publish path, and the prerequisites.

Store → MCP Setup

Connect Cursor / VS Code / Claude Code / ChatGPT to the Store MCP.

Authentication

The client-credentials flow used to mint the Bearer token for the entitlement check above.

Level 0: Register Your App

How to get the applicationId, clientId, and clientSecret referenced throughout this page.

Previous
MCP Setup