# Tiers

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

See our Creator docs for[ Tiered Packages](https://docs.tebex.io/creators/tebex-control-panel/how-to-create-packages/tiered-packages) to learn how to set up tiers.

{% hint style="warning" %}
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](https://docs.tebex.io/developers/templates/guides/supporting-tiers-on-custom-store-templates) to learn how to set up the necessary pages.
{% endhint %}

## 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](https://docs.tebex.io/developers/headless-api/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.

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

```json
{"openapi":"3.1.0","info":{"title":"Tebex Headless API","version":"1.2.0"},"tags":[{"name":"Headless","description":"Endpoints which interact with a basket requiring the basket ID"}],"servers":[{"url":"https://headless.tebex.io/api"}],"paths":{"/accounts/{token}/categories":{"get":{"tags":["Headless"],"operationId":"getAllCategories","summary":"Gets all categories available in the webstore.","parameters":[{"in":"path","name":"token","schema":{"type":"string"},"required":true,"description":"The webstore identifier."}],"description":"Gets all categories from a webstore. This does not include package information. To include package information, add `?includePackages=1` to the URL.","responses":{"200":{"description":"Successful response returns a list of category information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponse"}}}}}}}},"components":{"schemas":{"CategoryResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"Category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","description":"User-friendly name of the category"},"slug":{"type":"string","description":"Short identifier slug for the category","nullable":true},"parent":{"type":"object","description":"Parent category, if applicable","format":"Category","nullable":true},"tiered":{"type":"boolean","description":"True if this is a tiered category"},"active_tier":{"description":"If this is a tiered category and the usernameId is provided, this will be the active tier information for this category.","nullable":true,"$ref":"#/components/schemas/Tier"},"description":{"type":"string","description":"HTML description of the category"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"},"nullable":true},"order":{"type":"integer","description":"The numeric order in which to display the category."},"display_type":{"type":"string","enum":["list","grid"],"description":"How the category should be displayed"}}},"Tier":{"type":"object","properties":{"id":{"type":"integer"},"created_at":{"type":"string","format":"date-time","description":"The date and time when the tier became active"},"username_id":{"type":"string","description":"The user's username ID. For Steam, this is a numeric representation of their Steam64ID"},"package":{"$ref":"#/components/schemas/Package"},"active":{"type":"boolean","description":"True if the tier is currently active."},"recurring_payment_reference":{"type":"string","description":"The ID of the recurring payment this tier is attached to."},"next_payment_date":{"type":"string","format":"date-time","description":"The date and time of the next payment for this tier."},"status":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"}}},"pending_downgrade_package":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"description":"The package this tier is downgrading to if a downgrade is pending.","nullable":true}}},"Package":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string","nullable":true},"type":{"type":"string"},"category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"base_price":{"type":"number","format":"float"},"sales_tax":{"type":"number","format":"float"},"total_price":{"type":"number","format":"float"},"currency":{"type":"string"},"prorate_price":{"type":"number","format":"float","description":"If this package is part of a tiered category, this is the difference on upgrade pricing from the current active tier.","nullable":true},"discount":{"type":"number","format":"float"},"disable_quantity":{"type":"boolean"},"disable_gifting":{"type":"boolean"},"expiration_date":{"type":"string","nullable":true,"format":"date-time"},"media":{"type":"array","items":{"$ref":"#/components/schemas/PackageMedia"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PackageMedia":{"properties":{"type":{"type":"string","enum":["video","image"]},"name":{"type":"string","description":"A file name for the media, if applicable.","nullable":true},"url":{"type":"string","description":"The URL of the package media."},"featured":{"type":"boolean","description":"True if this media should be featured more prominently than others."}}}}}}
```

{% hint style="warning" %}
Your project must be approved to use this endpoint, please contact your Creator Success Manager to seek approval.
{% endhint %}

## Updates the given tier to the provided package.

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

```json
{"openapi":"3.1.0","info":{"title":"Tebex Headless API","version":"1.2.0"},"tags":[{"name":"Headless","description":"Endpoints which interact with a basket requiring the basket ID"}],"servers":[{"url":"https://headless.tebex.io/api"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"UpdateTierResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}},"paths":{"/accounts/{token}/tiers/{tierId}":{"patch":{"tags":["Headless"],"operationId":"updateTier","summary":"Updates the given tier to the provided package.","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"},"description":"The webstore identifier."},{"in":"path","name":"tierId","required":true,"schema":{"type":"integer"},"description":"The tier identifier"}],"description":"Updates a tier to a new package. A recurring payment updated webhook is sent when an update is successful.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"package_id":{"type":"integer"}}}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTierResponse"}}}}}}}}}
```

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

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

```json
{"openapi":"3.1.0","info":{"title":"Tebex Headless API","version":"1.2.0"},"tags":[{"name":"Headless","description":"Endpoints which interact with a basket requiring the basket ID"}],"servers":[{"url":"https://headless.tebex.io/api"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"CategoryResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"Category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","description":"User-friendly name of the category"},"slug":{"type":"string","description":"Short identifier slug for the category","nullable":true},"parent":{"type":"object","description":"Parent category, if applicable","format":"Category","nullable":true},"tiered":{"type":"boolean","description":"True if this is a tiered category"},"active_tier":{"description":"If this is a tiered category and the usernameId is provided, this will be the active tier information for this category.","nullable":true,"$ref":"#/components/schemas/Tier"},"description":{"type":"string","description":"HTML description of the category"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"},"nullable":true},"order":{"type":"integer","description":"The numeric order in which to display the category."},"display_type":{"type":"string","enum":["list","grid"],"description":"How the category should be displayed"}}},"Tier":{"type":"object","properties":{"id":{"type":"integer"},"created_at":{"type":"string","format":"date-time","description":"The date and time when the tier became active"},"username_id":{"type":"string","description":"The user's username ID. For Steam, this is a numeric representation of their Steam64ID"},"package":{"$ref":"#/components/schemas/Package"},"active":{"type":"boolean","description":"True if the tier is currently active."},"recurring_payment_reference":{"type":"string","description":"The ID of the recurring payment this tier is attached to."},"next_payment_date":{"type":"string","format":"date-time","description":"The date and time of the next payment for this tier."},"status":{"type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"}}},"pending_downgrade_package":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"description":"The package this tier is downgrading to if a downgrade is pending.","nullable":true}}},"Package":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string","nullable":true},"type":{"type":"string"},"category":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"base_price":{"type":"number","format":"float"},"sales_tax":{"type":"number","format":"float"},"total_price":{"type":"number","format":"float"},"currency":{"type":"string"},"prorate_price":{"type":"number","format":"float","description":"If this package is part of a tiered category, this is the difference on upgrade pricing from the current active tier.","nullable":true},"discount":{"type":"number","format":"float"},"disable_quantity":{"type":"boolean"},"disable_gifting":{"type":"boolean"},"expiration_date":{"type":"string","nullable":true,"format":"date-time"},"media":{"type":"array","items":{"$ref":"#/components/schemas/PackageMedia"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PackageMedia":{"properties":{"type":{"type":"string","enum":["video","image"]},"name":{"type":"string","description":"A file name for the media, if applicable.","nullable":true},"url":{"type":"string","description":"The URL of the package media."},"featured":{"type":"boolean","description":"True if this media should be featured more prominently than others."}}}}},"paths":{"/accounts/{token}/categories?usernameId={usernameId}&includePackages=1":{"get":{"tags":["Headless"],"operationId":"getTieredCategoriesForUser","summary":"Gets a store's categories including all package information with them.","parameters":[{"in":"path","name":"token","schema":{"type":"string"},"required":true,"description":"The webstore identifier."},{"in":"path","name":"usernameId","schema":{"type":"integer"},"required":true}],"description":"Gets all categories from the webstore, returning active tier information for the given player.","responses":{"200":{"description":"Successful response returns a list of category information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponse"}}}}}}}}}
```