Billing for integrators
Tahlib sells products, not plans. Tahlib Core is free. Everything else is a product that a restaurant group (an organization) adds per location or once for the whole organization, billed monthly or annually. Some products are suites: several products sold together as one.
Two rules matter if you show prices:
- The catalog has list prices. Use it to display what is on sale.
- Only the quote says what an organization pays. Locations, multi-location discounts, suites, trials, promotions and tax all change the amount, and the quote is the only place they are applied. Don't add up catalog prices yourself.
The catalog: GET /v1/catalog
Public, no authentication.
curl "https://api.tahlib.com/v1/catalog?countryCode=AE"countryCode defaults to AE. INTL returns the international price list
in USD. A country with no price list configured returns 404.
{
"countryCode": "AE",
"currencyCode": "AED",
"products": [ … ],
"locationTiers": [
{ "fromLocations": 1, "toLocations": 1, "discountBps": 0, "isCustomQuote": false },
{ "fromLocations": 2, "toLocations": 3, "discountBps": 1000, "isCustomQuote": false }
],
"tax": { "label": "VAT", "rateBps": 500, "collected": false }
}locationTiers is the multi-location discount for products whose
locationDiscountEligible is true. discountBps is in basis points: 1000 is
10%. A tier with isCustomQuote: true is sold by quote only. The example
values come from a development database; read them from the response.
Each product includes:
| Field | Meaning |
|---|---|
key | Stable product key, used in quotes and activation |
name, nameAr, tagline, description | Display copy (English and Arabic) |
kind | core, module or suite |
suiteMemberKeys | For a suite, the products it contains |
moduleKeys | The API modules the product unlocks, the keys behind 402 responses |
billingUnit | How quantity is counted: per_location, per_organization, base_plus_location, … |
prices | One entry per billing cycle on sale (see below) |
annualSaving | { amountMinor, bps }: what a year costs less than twelve months, or null |
trialEnabled, trialDays | Whether a free trial is offered, and for how long |
availability | available, coming_soon or hidden in this country |
dependencies | Products this one needs |
Each entry in prices:
{
"cycle": "monthly",
"currencyCode": "AED",
"unitAmountMinor": 12900,
"additionalLocationAmountMinor": null,
"version": 3,
"taxBehavior": "exclusive",
"needsPricing": false,
"isCustomQuote": false,
"status": "published"
}Amounts are integers in the currency's minor unit (12900 is AED 129.00). For
base_plus_location products, unitAmountMinor is the first location and
additionalLocationAmountMinor is each one after it. An annual price is the
amount charged per year. A published price is never edited: a change
publishes a new version.
Don't rely on product keys or amounts from these examples: read them from the catalog. The response is cached for up to 5 minutes.
The quote: POST /v1/billing/quote
Prices a selection for the signed-in user's organization. It is read-only and changes nothing.
- Auth: session bearer token,
billing.viewpermission. - Restaurant: resolved as usual (
X-Restaurant-Id). Without one the API returns 400.
{
"items": [
{ "productKey": "pos", "locationIds": ["<restaurant id>"] }
],
"cycle": "monthly",
"additive": true,
"compareCycles": true
}| Field | Meaning |
|---|---|
items | Up to 60 { productKey, locationIds, requestTrial? }. locationIds is empty for per_organization products. |
cycle | monthly (default) or annual |
promoCode | Optional promotion code |
additive | true: price adding these items to what the organization already has. This is what an "add product" screen should send. |
againstExisting | Default true: price the items as a replacement for the current subscription. Ignored when additive is set. |
compareCycles | Also price the other cycle, returned in cycleOptions |
The response (an organization adding one product to an empty subscription; values are illustrative):
{
"currencyCode": "AED",
"dueTodayMinor": 12900,
"recurringSubtotalMinor": 12900,
"discountTotalMinor": 0,
"taxTotalMinor": 0,
"recurringTotalMinor": 12900,
"futureRecurringTotalMinor": 12900,
"nextChargeDate": "…",
"lines": [
{
"kind": "product",
"productKey": "pos",
"billingUnit": "per_location",
"quantity": 1,
"unitAmountMinor": 12900,
"amountMinor": 12900,
"priceVersion": 3,
"cycle": "monthly",
"isTrial": false,
"reason": "…"
}
],
"cycleOptions": [ { "cycle": "annual", "recurringTotalMinor": 123840, "savingBps": 2000, "…": "…" } ],
"trials": [],
"recommendations": [],
"warnings": [],
"quotable": true,
"fingerprint": "63fe767c"
}lines[].kindisproduct,location_discount,discount,proration_creditorproration_charge. Each line has a plain-languagereason.futureRecurring*is what recurs once current trials end.recommendationssuggests a suite:kind: "save"when it would cost less than the products bought separately,kind: "upgrade"when it costs a little more and includes more.quotable: falsemeans the selection can't be sold as asked.warningssays why.fingerprintidentifies this exact price. Send it back when activating.
Activating
Adding products changes what the organization pays, so only the owner
can do it. Anyone else gets 403 owner_required. The server quotes the
selection again and charges from its own quote. No amount in the request is
used.
| Route | What it does |
|---|---|
POST /v1/subscriptions/products/:key/activate | Add one product, or start its trial |
POST /v1/subscriptions/activate | Add a basket of products in one all-or-nothing change |
POST /v1/subscriptions/products/:key/keep | Keep a trial instead of letting it end |
GET /v1/subscriptions/products/:key/cancel-preview | What cancelling would change |
POST /v1/subscriptions/products/:key/cancel | Cancel a product |
POST /v1/subscriptions/products/:key/locations/preview, PATCH /v1/subscriptions/products/:key/locations | Change the locations a product covers |
POST /v1/subscriptions/cycle/preview, PATCH /v1/subscriptions/cycle | Switch monthly ⇄ annual |
The single-product body:
{
"locationIds": [],
"cycle": "monthly",
"requestTrial": true,
"trialOnly": true,
"expectedFingerprint": "63fe767c",
"acknowledgeSuiteSavings": false
}Empty locationIds means the current restaurant. With trialOnly: true
the product starts as a free trial or not at all.
Activation can be refused with 409:
error | Meaning |
|---|---|
quote_changed | The price differs from expectedFingerprint. The body carries the new quote; show it and ask again. |
suite_cheaper | A suite would cost less. Show recommendations, then retry with acknowledgeSuiteSavings: true or buy the suite. Free trials are exempt. |
suite_switch_required | The suite replaces products already held. Use the suite switch routes under /v1/subscriptions/suites/:key/switch. |
trial_unavailable | With trialOnly, at least one item can't start as a trial. items lists each one and why. Nothing was started. |
What isn't live yet
Tahlib doesn't take card payments for subscriptions yet. Invoice collection
stays switched off until BILLING_COLLECTION_ENABLED is set, and the only
collection provider is a manual one: it never moves money, the invoice
carries bank-transfer instructions, and an admin marks it paid. No card
gateway is built.
The older plan-era routes POST /v1/billing/checkout, /start-trial,
/change-trial-plan and /activate-free serve organizations still on the
older billing model. Per-product organizations, which include every sign-up
since 2026-10-03, get 409 modular_billing from them. Don't build on them.
Sources
- Catalog route, default country:
apps/api/src/catalog/catalog.controller.ts; list-price rule, INTL, 404, cache:apps/api/src/catalog/catalog.service.ts - Catalog types (
billingUnit,kind,availability):packages/shared-types/src/catalog.ts - Quote and activation routes, permissions, owner rule:
apps/api/src/subscriptions/quote.controller.ts - Request and response schemas:
packages/shared-types/src/pricing.ts - 409 codes:
apps/api/src/subscriptions/subscription-actions.service.ts - Pricing engine:
packages/pricing; model:docs/adr/007-modular-product-pricing.md,docs/adr/011-hybrid-commercial-model.md - Collection:
.env.example(BILLING_COLLECTION_ENABLED),docs/pricing/BILLING_PROVIDER.md - Plan-era refusal:
assertLegacyBillinginapps/api/src/billing/legacy-billing.ts, called fromapps/api/src/billing/billing.service.ts - Response shapes checked against
GET /v1/catalogandPOST /v1/billing/quoteon a running API, 2026-10-20