Tiers

Tiers are for upgrading between different levels of subscription packages and automatically applying their deliverables.

This guide will detail the expected flows and endpoints for implementing tiers using Headless API.

See our Creator docs for Tiered Packages to learn how to set up tiers.

If you are using an older or custom store template, you may need to modify your template to support tiers. A tiered category view is different from a non-tiered category.

See Supporting Tiers on Custom Store Templates to learn how to set up the necessary pages.

Checkout Flow

Tiers require an authenticated user. After you create the basket, you must log the user in using the relevant basket auth links.

See Creating A Basket for further information.

The expected flow for checking out with a Tier is identical to any other package:

1. Create the basket

2. Authenticate the user via the basket's auth links

3. Add the tiered package to the basket

4. Direct the user to checkout

On successful checkout, the user will now have an active_tier when retrieving their tiered categories against their usernameId.

If the active_tier property is not present, the user does not have an active package in that tier.

API Endpoints

Tiered categories use our existing /categories endpoint.

Unlike other Headless API endpoints, you must use HTTP Basic authentication with the Username set to your project ID and Password as your secret key.

Provide a usernameId as a query parameter to check for an active_tier

All tiered categories will have the property tiered: true

Gets all categories available in the webstore.

get

Gets all categories from a webstore. This does not include package information. To include package information, add ?includePackages=1 to the URL.

Path parameters

tokenstringRequired

The webstore identifier.

Example: t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb

Responses

200

Successful response returns a list of category information.

application/json

get

/accounts/{token}/categories

HTTPcURLJavaScriptPython

GET /api/accounts/{token}/categories HTTP/1.1
Host: headless.tebex.io
Accept: */*

200

Successful response returns a list of category information.

{
  "data": [
    {
      "id": 2678660,
      "name": "Test",
      "slug": "text",
      "parent": {},
      "tiered": false,
      "active_tier": {
        "id": 40796,
        "created_at": "2025-05-14T13:48:56.000000Z",
        "username_id": "text",
        "package": {
          "id": 6276316,
          "name": "test package 101",
          "description": "<p>this is just a test. only a test. nothing more.</p>",
          "image": null,
          "type": "single",
          "category": {
            "id": 2678660,
            "name": "Packages"
          },
          "base_price": 5,
          "sales_tax": 0,
          "total_price": 5,
          "currency": "USD",
          "prorate_price": 1,
          "discount": 0,
          "disable_quantity": false,
          "disable_gifting": false,
          "expiration_date": null,
          "media": [],
          "created_at": "2024-05-21T18:09:17+00:00",
          "updated_at": "2024-05-21T18:09:17+00:00"
        },
        "active": true,
        "recurring_payment_reference": "tbx-r-757925142",
        "next_payment_date": "2025-06-14T13:48:56+00:00",
        "status": {
          "id": 2,
          "description": "Active"
        },
        "pending_downgrade_package": {
          "id": 6834820,
          "name": "Bronze"
        }
      },
      "description": "text",
      "packages": [
        {
          "id": 6276316,
          "name": "test package 101",
          "description": "<p>this is just a test. only a test. nothing more.</p>",
          "image": null,
          "type": "single",
          "category": {
            "id": 2678660,
            "name": "Packages"
          },
          "base_price": 5,
          "sales_tax": 0,
          "total_price": 5,
          "currency": "USD",
          "prorate_price": 1,
          "discount": 0,
          "disable_quantity": false,
          "disable_gifting": false,
          "expiration_date": null,
          "media": [],
          "created_at": "2024-05-21T18:09:17+00:00",
          "updated_at": "2024-05-21T18:09:17+00:00"
        }
      ],
      "order": 1,
      "display_type": "list"
    }
  ]
}

Your project must be approved to use this endpoint, please contact your Creator Success Manager to seek approval.

Updates the given tier to the provided package.

patch

Updates a tier to a new package. A recurring payment updated webhook is sent when an update is successful.

Authorizations

basicAuth

AuthorizationstringRequired

Path parameters

tokenstringRequired

The webstore identifier.

Example: some-uuid

tierIdintegerRequired

The tier identifier

Example: 6276316

Body

application/json

package_idintegerOptionalExample: 6834822

Responses

200

Successful response.

application/json

patch

/accounts/{token}/tiers/{tierId}

HTTPcURLJavaScriptPython

PATCH /api/accounts/{token}/tiers/{tierId} HTTP/1.1
Host: headless.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "package_id": 6834822
}

200

Successful response.

{
  "success": true,
  "message": "Tier successfully upgraded, please allow a few moments for your changes to take effect."
}

Gets a store's categories including all package information with them.

get

Gets all categories from the webstore, returning active tier information for the given player.

Authorizations

basicAuth

AuthorizationstringRequired

Path parameters

tokenstringRequired

The webstore identifier.

Example: t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb

usernameIdintegerRequiredExample: 76561198042467020

Responses

200

Successful response returns a list of category information.

application/json

get

/accounts/{token}/categories?usernameId={usernameId}&includePackages=1

HTTPcURLJavaScriptPython

GET /api/accounts/{token}/categories?usernameId={usernameId}&includePackages=1 HTTP/1.1
Host: headless.tebex.io
Authorization: Basic username:password
Accept: */*

200

Successful response returns a list of category information.

{
  "data": [
    {
      "id": 2678660,
      "name": "Test",
      "slug": "text",
      "parent": {},
      "tiered": false,
      "active_tier": {
        "id": 40796,
        "created_at": "2025-05-14T13:48:56.000000Z",
        "username_id": "text",
        "package": {
          "id": 6276316,
          "name": "test package 101",
          "description": "<p>this is just a test. only a test. nothing more.</p>",
          "image": null,
          "type": "single",
          "category": {
            "id": 2678660,
            "name": "Packages"
          },
          "base_price": 5,
          "sales_tax": 0,
          "total_price": 5,
          "currency": "USD",
          "prorate_price": 1,
          "discount": 0,
          "disable_quantity": false,
          "disable_gifting": false,
          "expiration_date": null,
          "media": [],
          "created_at": "2024-05-21T18:09:17+00:00",
          "updated_at": "2024-05-21T18:09:17+00:00"
        },
        "active": true,
        "recurring_payment_reference": "tbx-r-757925142",
        "next_payment_date": "2025-06-14T13:48:56+00:00",
        "status": {
          "id": 2,
          "description": "Active"
        },
        "pending_downgrade_package": {
          "id": 6834820,
          "name": "Bronze"
        }
      },
      "description": "text",
      "packages": [
        {
          "id": 6276316,
          "name": "test package 101",
          "description": "<p>this is just a test. only a test. nothing more.</p>",
          "image": null,
          "type": "single",
          "category": {
            "id": 2678660,
            "name": "Packages"
          },
          "base_price": 5,
          "sales_tax": 0,
          "total_price": 5,
          "currency": "USD",
          "prorate_price": 1,
          "discount": 0,
          "disable_quantity": false,
          "disable_gifting": false,
          "expiration_date": null,
          "media": [],
          "created_at": "2024-05-21T18:09:17+00:00",
          "updated_at": "2024-05-21T18:09:17+00:00"
        }
      ],
      "order": 1,
      "display_type": "list"
    }
  ]
}