Overview
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.
Headless API Flow
Below is the expected flow your application should follow when utilizing the Headless API. For a list of all endpoints, please see the Endpoints page.
Packages & Listings
You can retrieve your store's listings in JSON format and display them however you wish:
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-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
GET /api/accounts/{token}/categories HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns a list of category information.
{
"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"
}
]
}
Gets all categories from a webstore including packages.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
GET /api/accounts/{token}/categories HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns a list of category information.
{
"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"
}
]
}
Gets information about a category and returns the packages in that category.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The ID of the category to fetch.
127244343
GET /api/accounts/{token}/categories/{categoryId} HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns the category without package information.
{
"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"
}
]
}
Gets information about a category and returns the packages in that category.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The ID of the category to fetch.
127244343
GET /api/accounts/{token}/categories/{categoryId} HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns the category with package information.
{
"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"
}
]
}
Gets a package from a webstore by ID.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The package's ID.
1272441812
GET /api/accounts/{token}/packages/{packageId} HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns the package information.
{
"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"
}
]
}
Gets all packages from a webstore.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
GET /api/accounts/{token}/packages HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns a list of package information.
{
"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"
}
]
}
Creating Baskets
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).
Creates a new basket for use during checkout.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
A URL the user can return to when checkout is completed.
https://example.tebex.io/thank-you
A 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
true
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
}
{
"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"
}
}
}
Fetches a basket's auth URL.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
The URL you would like to redirect the user to after successful basket authentication.
https://example.tebex.io/
GET /api/accounts/{token}/baskets/{basketIdent}/auth HTTP/1.1
Host: headless.tebex.io
Accept: */*
[
{
"name": "FiveM",
"url": "https://ident.tebex.io/"
}
]
Adding and Removing Packages
You can add or remove packages programmatically to the created basket via the API as needed when the user interacts with your application.
Add a package with the given ID to the basket.
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
6276316
1
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
}
{
"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"
}
}
Remove the given package ID from the basket.
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
6276316
POST /api/baskets/{basketIdent}/packages/remove HTTP/1.1
Host: headless.tebex.io
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"package_id": 6276316
}
{
"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"
}
}
Coupons, Gift Cards, and Creator Codes
Once all packages and quantities are selected, apply any relevant coupons, gift cards, or creator codes with these endpoints.
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
Academy10
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"
}
{
"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"
}
}
}
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
POST /api/accounts/{token}/baskets/{basketIdent}/creator-codes/remove HTTP/1.1
Host: headless.tebex.io
Accept: */*
No content
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
0127 0244 7210 1111
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"
}
Successful response returns the basket.
{
"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"
}
}
}
Removes a gift card from the basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
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"
}
No content
Applies a creator code to a basket.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
Academy10
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"
}
Successful response returns the basket.
{
"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"
}
}
}
Removes a coupon code from a basket
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
POST /api/accounts/{token}/baskets/{basketIdent}/coupons/remove HTTP/1.1
Host: headless.tebex.io
Accept: */*
No content
Checkout
When the user is ready to checkout, fetch the basket and direct the user to the links.checkout
URL.
Gets a basket associated with the provided identifier.
The webstore identifier.
t66x-7cd928b1e9312709e6810edac6dc1fd1eefc57cb
The basket identifier.
c00244-d2ac2e77418a55b25292a6bc7a719ad9c529ba2c
GET /api/accounts/{token}/baskets/{basketIdent} HTTP/1.1
Host: headless.tebex.io
Accept: */*
Successful response returns the basket information.
{
"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"
}
}
}
Starter Template
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 tebexio/Headless-Template GitHub repo to begin.
Examples
The following websites are built using the Headless API - hosted via our customers own infrastructure, using frontend frameworks such as Vue or React.
Last updated
Was this helpful?