Guides
Billing for integrators

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:

FieldMeaning
keyStable product key, used in quotes and activation
name, nameAr, tagline, descriptionDisplay copy (English and Arabic)
kindcore, module or suite
suiteMemberKeysFor a suite, the products it contains
moduleKeysThe API modules the product unlocks, the keys behind 402 responses
billingUnitHow quantity is counted: per_location, per_organization, base_plus_location, …
pricesOne entry per billing cycle on sale (see below)
annualSaving{ amountMinor, bps }: what a year costs less than twelve months, or null
trialEnabled, trialDaysWhether a free trial is offered, and for how long
availabilityavailable, coming_soon or hidden in this country
dependenciesProducts 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.view permission.
  • 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
}
FieldMeaning
itemsUp to 60 { productKey, locationIds, requestTrial? }. locationIds is empty for per_organization products.
cyclemonthly (default) or annual
promoCodeOptional promotion code
additivetrue: price adding these items to what the organization already has. This is what an "add product" screen should send.
againstExistingDefault true: price the items as a replacement for the current subscription. Ignored when additive is set.
compareCyclesAlso 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[].kind is product, location_discount, discount, proration_credit or proration_charge. Each line has a plain-language reason.
  • futureRecurring* is what recurs once current trials end.
  • recommendations suggests 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: false means the selection can't be sold as asked. warnings says why.
  • fingerprint identifies 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.

RouteWhat it does
POST /v1/subscriptions/products/:key/activateAdd one product, or start its trial
POST /v1/subscriptions/activateAdd a basket of products in one all-or-nothing change
POST /v1/subscriptions/products/:key/keepKeep a trial instead of letting it end
GET /v1/subscriptions/products/:key/cancel-previewWhat cancelling would change
POST /v1/subscriptions/products/:key/cancelCancel a product
POST /v1/subscriptions/products/:key/locations/preview, PATCH /v1/subscriptions/products/:key/locationsChange the locations a product covers
POST /v1/subscriptions/cycle/preview, PATCH /v1/subscriptions/cycleSwitch 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:

errorMeaning
quote_changedThe price differs from expectedFingerprint. The body carries the new quote; show it and ask again.
suite_cheaperA suite would cost less. Show recommendations, then retry with acknowledgeSuiteSavings: true or buy the suite. Free trials are exempt.
suite_switch_requiredThe suite replaces products already held. Use the suite switch routes under /v1/subscriptions/suites/:key/switch.
trial_unavailableWith 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: assertLegacyBilling in apps/api/src/billing/legacy-billing.ts, called from apps/api/src/billing/billing.service.ts
  • Response shapes checked against GET /v1/catalog and POST /v1/billing/quote on a running API, 2026-10-20