Licensing & Billing API

This page is the integrator reference for everything around money: reading catalog prices, querying a business’s licence and owned products, taking payment through the checkout rail, reading invoices, and following the renewal cycle. It builds on the conventions in API Fundamentals (base URL, auth realms, branch scope, the error envelope, idempotency, rate limits).

Auth & roles

These endpoints use the Staff JWT realm (Authorization: Bearer <jwt> — see API Fundamentals). Role requirements differ by endpoint:

Endpoint summary

Reading the price list

The catalog is public — marketing pages read it too, so a price change made in the superadmin panel cannot leave the website advertising a stale amount.

curl "https://app.hummytummy.com/api/v1/catalog/pricing?locale=en"

Fields returned per product:

For what each product code grants, see the Entitlement Matrix.

Licence state and owned products

GET /v1/me/licensing lets the SPA render the whole licence screen in one request:

curl https://app.hummytummy.com/api/v1/me/licensing \
  -H "Authorization: Bearer $JWT"

license.status is one of four values:

The anniversary and proration

The day the licence is bought becomes the account’s immutable anniversary (the tenant-local calendar date; default Europe/Istanbul). Every annual item bought afterwards is prorated to the days remaining until that anniversary — so the whole account renews on ONE date with ONE itemized invoice.

• Rounding happens per unit, then multiplies: unitCents × qty === subtotalCents holds exactly.
• No priced line ever falls below ₺1 (MIN_LINE_CENTS = 100); a genuinely free item stays at 0.
• The cycle length is computed as 365 or 366, never hardcoded; a 29 Feb anniversary clamps to 28 Feb in common years.

VAT-inclusive pricing internals

Every catalog price is a gross (VAT-inclusive) amount, and the customer is charged exactly that. The quote engine derives the tax out of the gross; it never adds it on top:

netCents = round(grossLineSum / (1 + rate))
taxCents = grossLineSum - netCents

For TRY carts the rate is 20%. In the quote response subtotalCents is the net, taxCents is the embedded VAT, and totalCents is the gross amount that will be charged (including shipping when the cart holds hardware).

The checkout rail

The only way to buy a product is the checkout (PayTR) rail. No paid line is ever provisioned without proof of payment (paymentRef).

curl -X POST https://app.hummytummy.com/api/v1/checkout/quote \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "addon", "code": "license_annual", "qty": 1 },
      { "type": "addon", "code": "module_inventory", "qty": 1 },
      { "type": "addon", "code": "extra_branch", "qty": 2 }
    ]
  }'

curl -X POST https://app.hummytummy.com/api/v1/checkout/intent \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": { "items": [ { "type": "addon", "code": "license_annual", "qty": 1 } ] },
    "buyer": {
      "email": "[email protected]",
      "name": "Ali Veli",
      "phone": "+905551112233",
      "address": "..."
    },
    "returnUrl": "https://app.hummytummy.com/checkout/done",
    "acceptedDocumentIds": ["<KVKK>", "<DISTANCE_SALES>", "<REFUND>"]
  }'

The purchasability gate (before any charge)

Every addon line is checked before payment. A rejected line returns 409 and stops the whole cart — no intent row is written and PayTR is never called. The envelope carries { code, message, addOnCode }:

Other pre-charge rejections:

• 409 HARDWARE_OUT_OF_STOCK — not enough real stock for a hardware line (quantities for the same product are summed across lines before checking).
• 400 — the cart total is 0; PayTR rejects zero-value baskets, and free provisioning goes through the superadmin comp path.

Idempotency

PayTR retries aggressively (it retries even after a 200 OK if the body isn’t "OK"/"FAIL"). Three layers guard against double provisioning:

Invoices

Renewal (manual)

There is no card vault and no auto-charge. A renewal is paid by hand through the same checkout rail.

The renewal cart is at full list price: it is quoted as of the anniversary, so remaining days equal cycle days and proration returns the whole price. When it is paid, the same TenantAddOn row is reactivated in place — no duplicate row, the ownership identity survives, and any scheduled capacity reduction (pendingQuantity) is honoured.

Cancellation

Product cancellation lives on the marketplace rail and is ADMIN-only: DELETE /api/v1/marketplace/addons/:id (at period end by default, ?immediate=true to revoke right away). Details in the Marketplace API.

Retired rails

The following endpoints were removed in v3.3.0; a legacy integration calling them gets a 404:

Related

• Entitlement Matrix — the free core, product grants, fold rules, and the ENTITLEMENT_REQUIRED envelope.
• Marketplace API — catalog listing, owned products, and cancellation.
• API Fundamentals — base URL, auth realms, branch scope, error envelope, rate-limit tiers.
• Webhooks — the payment and checkout events that fire when these rails confirm.