Marketplace API

The Marketplace is the catalogue of products a tenant can buy individually. The free core gives every tenant an entitlement baseline; catalog products raise that baseline (an extra branch, an e-Fatura integration, advanced reports, AI credits, and so on). There are no plans, tiers, or bundles: every paid capability is sold with the annual licence (license_annual) as its prerequisite.

Buying a product writes a TenantAddOn row, and the entitlement projector folds that row’s grants map into the tenant’s existing entitlement set. The combine rule depends on the key prefix:

All paths are under the /api global prefix. Prices are in TRY and stored in the catalogue as cents (priceCents): 490000 = ₺4,900.00. Amounts are shown KDV-inclusive (gross). For base URL, auth realms, the error envelope, and rate-limit tiers, see API Fundamentals.

Endpoints

These are tenant-level endpoints: they do not expect X-Branch-Id. The checkout intent and the cancel endpoint move/settle money or entitlements and are protected accordingly.

List the catalogue

The catalogue is public (it also shows on the landing site); no authentication is required. Only published products are returned, and each row is trimmed for the UI.

# All published products
curl https://hummytummy.com/api/v1/marketplace/addons
 
# Filter by kind: license | module | integration | capacity | credit | service
curl "https://hummytummy.com/api/v1/marketplace/addons?kind=integration"

const res = await fetch(
  "https://hummytummy.com/api/v1/marketplace/addons?kind=integration",
);
const addons = await res.json();

Response:

[
  {
    "code": "module_inventory",
    "name": "Stok & Maliyet Yönetimi",
    "description": "Reçete, stok sayımı, satın alma siparişi, fire takibi, tedarikçi yönetimi ve şubeler arası transfer.",
    "kind": "module",
    "billing": "annual",
    "priceCents": 390000,
    "currency": "TRY",
    "deps": [],
    "requiresLicense": true,
    "creditKind": null,
    "creditUnits": null,
    "maxQuantity": null,
    "sortOrder": 11,
    "i18n": { "tr": { "name": "…", "description": "…" }, "en": { "…": "…" } }
  }
]

Catalogue summary

Every sellable product at a glance. The Grants column is shown here for reference only; it is not part of the public catalogue payload. For the details, see the Entitlement Matrix.

Retired codes (kds_extra_screen, kds_extra_station, extra_tablet) are archived, never deleted: MarketplaceAddOn.code may not be reused and TenantAddOn.addOnId is onDelete: Restrict. All three granted limit.kdsScreens / limit.kdsStations / limit.tablets — keys no enforcement code has ever read — and the à-la-carte model drops device-capacity pricing entirely.

Buy a product (checkout intent)

The only way to buy is the checkout (PayTR) rail. A paid product is never provisioned without proof of payment (paymentRef).

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

const res = await fetch("https://hummytummy.com/api/v1/checkout/intent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwt}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cart: {
      items: [
        { type: "addon", code: "license_annual", qty: 1 },
        { type: "addon", code: "fiscal_hugin", qty: 1 },
      ],
    },
    buyer: {
      email: "[email protected]",
      name: "Ali Veli",
      phone: "+905551112233",
      address: "...",
    },
    returnUrl: "https://app.hummytummy.com/checkout/done",
    acceptedDocumentIds: [kvkkId, distanceSalesId, refundId],
  }),
});
const { paymentRef, iframeToken, paymentLink } = await res.json();

Purchasability and dependencies (deps)

Every addon line passes the purchasability gate before any charge. A rejected line returns 409 and stops the whole cart:

Every entry in deps is a catalog product code and must be satisfied at purchase time by an active ownership row or by a sibling line in the same cart. Today the products carrying deps are the four credit packs (credit_ai_* → module_ai_studio, credit_sms_500 → sms_integration).

Duplicate-purchase guard

Buying the same product twice and gaining nothing is blocked: if an active row already exists for the same (tenantId, addOnId, branchId), the second purchase is rejected with ADDON_ALREADY_OWNED. Capacity products are bought by the unit, so their ceiling is maxQuantity instead. Credit packs are consumable and are never blocked. Two concurrent purchases are caught by a Serializable transaction; the loser gets a retryable 409 (the card is not charged twice).

Idempotency

PayTR retries aggressively (it retries even after a 200 OK if the body isn’t "OK"/"FAIL"). There are multiple layers of protection against double provisioning:

My current products

Lists the rows the tenant currently holds.

curl https://hummytummy.com/api/v1/marketplace/addons/mine \
  -H "Authorization: Bearer $JWT"

const res = await fetch(
  "https://hummytummy.com/api/v1/marketplace/addons/mine",
  { headers: { Authorization: `Bearer ${jwt}` } },
);
const mine = await res.json();

Each row carries the product catalogue (addOn) plus its status/period fields:

[
  {
    "id": "ta_01J...",
    "tenantId": "t_01J...",
    "addOnId": "ao_01J...",
    "branchId": null,
    "quantity": 2,
    "pendingQuantity": null,
    "status": "active",
    "activatedAt": "2026-08-13T10:00:00.000Z",
    "currentPeriodStart": "2026-08-13T00:00:00.000Z",
    "currentPeriodEnd": "2027-03-10T00:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "paymentRef": "CK-018f...",
    "chargedCents": 434300,
    "currency": "TRY",
    "origin": "purchase",
    "addOn": { "code": "extra_branch", "name": "Ek Şube", "...": "..." }
  }
]

Cancel a product

Cancellation is ADMIN-only (it is a billing decision). By default the row is cancelled at period end; pass ?immediate=true to revoke right away.

curl -X DELETE \
  https://hummytummy.com/api/v1/marketplace/addons/$TENANT_ADDON_ID \
  -H "Authorization: Bearer $JWT"

curl -X DELETE \
  "https://hummytummy.com/api/v1/marketplace/addons/$TENANT_ADDON_ID?immediate=true" \
  -H "Authorization: Bearer $JWT"

Only active and past_due rows can be cancelled; anything else returns 400. For a past_due row the cancellation is always immediate — its paid period has already ended, so deferring to period end would only keep the grace grant alive with no way to revoke it.

Related

• Entitlement Matrix — the free core, product grants, licence suppression, and the ENTITLEMENT_REQUIRED envelope.
• Licensing & Billing API — the checkout rail, proration, the anniversary, invoices, and renewals.
• API Fundamentals — base URL, auth realms, error envelope, rate-limit tiers.
• Webhooks — receive outbound events (the api_access module grants feature.apiAccess).
• Operator experience (browsing, buying, and tracking products in the panel): Marketplace help.