v2.0.0

Tebex Headless API v2.0.0

Overview

This release introduces a major restructure of the API's base URL, a new dynamic packages system, expanded schemas across baskets and packages, and several breaking changes to response shapes. Please review the migration notes carefully before upgrading.

---

⚠️ Breaking Changes

Base URL restructured

The store token is now embedded in the server URL rather than passed as a path segment. All account-scoped routes are now relative to https://headless.tebex.io/api/accounts/{token}. This makes all endpoint paths shorter.

This may change how you make requests using an OpenAPI client, depending on your language and its particular generator.

BasketPackage shape changed

The top-level qty field has been removed. Quantity is now nested inside an in_basket object, which also carries price, gift_username_id, and gift_username.

- basket.packages[n].qty
+ basket.packages[n].in_basket.quantity

Discount code apply endpoints return a lightweight response

POST .../creator-codes, POST .../giftcards, and POST .../coupons no longer return the full basket. They now return a simple success object:

{ "success": true, "message": "..." }

Coupon object field renamed

The coupon_code field on the Coupon schema (as returned in basket responses) has been renamed to code. Request bodies for applying/removing coupons still use coupon_code.

- basket.coupons[n].coupon_code
+ basket.coupons[n].code

---

✨ New Features

Dynamic packages

A new system for populating store categories with per-basket custom packages. Dynamic categories are created in the creator panel with the type dynamic and populated via a new endpoint in response to a basket.authenticated webhook.

New endpoint: PUT /baskets/{basketIdent}/dynamic-packages

Request body requires username, category_id, and a packages array. Each package supports name, price, slug, optional description and image_url, and arbitrary custom key-value metadata.

Fetch dynamic packages by providing basketIdent alongside includePackages=1 on the categories endpoints:

• GET /categories?includePackages=1&basketIdent={basketIdent}
• GET /categories/{categoryId}?includePackages=1&basketIdent={basketIdent}

When adding a dynamic package to a basket, set "dynamic": true in the request body of POST /{basketIdent}/packages.

Slug support for packages and categories

Package and category endpoints now accept a slug in addition to a numeric ID, giving you cleaner, human-readable URLs.

New Webstore.disabled field

The webstore object now exposes a disabled boolean indicating whether the store has been disabled.

---

🔄 Other Changes

Schema additions

Schema	New fields
Package	order, slug, user_limit, creator_meta_data, options, variables
PackageMedia	primary (boolean — whether this is the primary media item)
Category	image_url (nullable URI), dynamic (boolean)

Operation ID renames

v1.2.0	v2.0.0
getWebstoreById	getWebstore
getCMSPages	getCustomPages
getBasketById	getBasket
getAllCategories	getCategories
getAllCategoriesIncludingPackages	getCategoriesIncludePackages
getTieredCategoriesForUser	getUserTieredCategories
getCategoryById	getCategory
getCategoryIncludingPackages	getCategoryIncludePackages
getPackageById	getPackage
getAllPackagesWithBasket	getPackagesForBasket

---

Migration Checklist

• Update your base URL to use the new token-scoped server URL
• Update any reads of basket.packages[n].qty to basket.packages[n].in_basket.quantity
• Update any reads of basket.coupons[n].coupon_code to basket.coupons[n].code
• Update handlers for creator code, gift card, and coupon apply responses — they no longer return a basket
• If using the addBasketPackage endpoint with dynamic packages, add "dynamic": true to the request body
• Update any operation ID references if you are generating a client from the OpenAPI spec