Tebex Headless API allows integration of your store directly into your own frontend or in-game.
The Headless API works with your existing packages, coupons, sales & creator codes.
If you haven't already done so, we recommend having a read of our quick start guide before beginning integration.
You can query the Headless API to retrieve your packages/categories, build a basket for a user, and direct them to checkout - all from within your own frontend implementation (be that a website or in-game).
The Headless API can be used with Tebex.js for a fully embedded checkout experience without the user ever leaving your own website.
Below is the expected flow your application should follow when utilizing the Headless API. For a list of all endpoints, please see the page.
You can retrieve your store's listings in JSON format and display them however you wish:
In order to purchase items, a basket must be created for the customer. Create a basket and allow the customer to login with their username or other OAuth login mechanism (e.g Steam or FiveM).
You can add or remove packages programmatically to the created basket via the API as needed when the user interacts with your application.
Once all packages and quantities are selected, apply any relevant coupons, gift cards, or creator codes with these endpoints.
When the user is ready to checkout, fetch the basket and direct the user to the links.checkout URL.
To get started with your own integration of the Headless API you're able to use our example integration built upon Nuxt.js, Vue & Typescript. Take a look at the GitHub repo to begin.
The following websites are built using the Headless API - hosted via our customers own infrastructure, using frontend frameworks such as Vue or React.
Gets all categories from a webstore. This does not include package information. To include package information, add ?includePackages=1 to the URL.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbSuccessful response returns a list of category information.
Successful response returns a list of category information.
Gets all categories from a webstore including packages.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbSuccessful response returns a list of category information.
Successful response returns a list of category information.
Gets information about a category and returns the packages in that category.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe ID of the category to fetch.
127244343Successful response returns the category without package information.
Successful response returns the category without package information.
Gets information about a category and returns the packages in that category.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe ID of the category to fetch.
127244343Successful response returns the category with package information.
Gets a package from a webstore by ID.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe package's ID.
1272441812Successful response returns the package information.
Successful response returns the package information.
Gets all packages from a webstore.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbSuccessful response returns a list of package information.
Successful response returns a list of package information.
Creates a new basket for use during checkout.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbA URL the user can return to when checkout is completed.
https://example.tebex.io/thank-youA URL the user can return to when cancelling checkout.
https://tebex.io/Custom data you wish to associate with the basket. This data will be included with webhook responses and GET requests associated with the Basket.
{"foo":"bar"}True if the user should automatically be redirected to the relevant complete/cancel URL
trueSuccessful response returns the basket information.
The provided webstore ID is invalid.
Fetches a basket's auth URL.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cThe URL you would like to redirect the user to after successful basket authentication.
https://example.tebex.io/Successful response returns the basket auth information.
The provided webstore ID or basket ID is invalid.
Add a package with the given ID to the basket.
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c62763161Successful response.
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Remove the given package ID from the basket.
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c6276316Successful response returns the basket.
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cAcademy10Successful response returns the basket.
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cCreator code removed successfully.
No content
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c0127 0244 7210 1111Successful response returns the basket.
Removes a gift card from the basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c0127 0244 7210 1111Gift card removed successfully.
No content
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cAcademy10Successful response returns the basket.
Removes a coupon code from a basket
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cSuccessful response.
No content
The provided request is invalid. The error response will include detail as to which parameter failed validation.
Gets a basket associated with the provided identifier.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cbThe basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2cSuccessful response returns the basket information.
Successful response returns the basket information.
Successful response returns the category with package information.
No content
Successful response returns the basket.
No content
Successful response returns the basket.
Successful response.
No content
{
"data": [
{
"id": 2678660,
"name": "Test",
"slug": "text",
"parent": {},
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
],
"order": 1,
"display_type": "list"
}
]
}{
"data": [
{
"id": 2678660,
"name": "Test",
"slug": "text",
"parent": {},
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
],
"order": 1,
"display_type": "list"
}
]
}{
"data": [
{
"id": 2678660,
"name": "Test",
"slug": "text",
"parent": {},
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
],
"order": 1,
"display_type": "list"
}
]
}{
"data": [
{
"id": 2678660,
"name": "Test",
"slug": "text",
"parent": {},
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
],
"order": 1,
"display_type": "list"
}
]
}{
"data": {
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
}[
{
"name": "FiveM",
"url": "https://ident.tebex.io/"
}
]{
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}{
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}{
"data": {
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
}{
"data": {
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
}{
"data": {
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
}{
"data": {
"id": 244127617,
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"complete": false,
"email": "[email protected]",
"username": null,
"coupons": [
{
"coupon_code": "Academy10"
}
],
"giftcards": [
{
"card_number": "0127 0244 7210 1111"
}
],
"creator_code": "text",
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"country": "US",
"ip": "127.0.0.1",
"username_id": 127244,
"base_price": 1.27,
"sales_tax": 0.11,
"total_price": 1.38,
"currency": "USD",
"packages": [
{
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "some_wallet_reference",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
],
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
}GET /api/accounts/{token}/categories HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/categories?includePackages=1 HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/categories/{categoryId} HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/categories/{categoryId}?includePackages=1 HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/packages/{packageId} HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/packages HTTP/1.1
Host: headless.tebex.io
Accept: */*
{
"data": [
{
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
]
}POST /api/accounts/{token}/baskets HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 139
{
"complete_url": "https://example.tebex.io/thank-you",
"cancel_url": "https://tebex.io/",
"custom": {
"foo": "bar"
},
"complete_auto_redirect": true
}GET /api/accounts/{token}/baskets/{basketIdent}/auth?returnUrl={returnUrl} HTTP/1.1
Host: headless.tebex.io
Accept: */*
POST /api/baskets/{basketIdent}/packages HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 35
{
"package_id": 6276316,
"quantity": 1
}POST /api/baskets/{basketIdent}/packages/remove HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"package_id": 6276316
}POST /api/accounts/{token}/baskets/{basketIdent}/creator-codes HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"creator_code": "Academy10"
}POST /api/accounts/{token}/baskets/{basketIdent}/creator-codes/remove HTTP/1.1
Host: headless.tebex.io
Accept: */*
POST /api/accounts/{token}/baskets/{basketIdent}/giftcards HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"card_number": "0127 0244 7210 1111"
}POST /api/accounts/{token}/baskets/{basketIdent}/giftcards/remove HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"card_number": "0127 0244 7210 1111"
}POST /api/accounts/{token}/baskets/{basketIdent}/coupons HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 27
{
"coupon_code": "Academy10"
}POST /api/accounts/{token}/baskets/{basketIdent}/coupons/remove HTTP/1.1
Host: headless.tebex.io
Accept: */*
GET /api/accounts/{token}/baskets/{basketIdent} HTTP/1.1
Host: headless.tebex.io
Accept: */*
{
"data": [
{
"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",
"discount": 0,
"disable_quantity": false,
"disable_gifting": false,
"expiration_date": null,
"created_at": "2024-05-21T18:09:17+00:00",
"updated_at": "2024-05-21T18:09:17+00:00"
}
]
}