Subscription Billing
A full recurring-billing engine: model your catalog once, subscribe customers to plans, and let the platform generate invoices, charge saved cards, retry failures with dunning schedules and notify you of every state change through webhooks. You can run the whole lifecycle programmatically over the API — or embed the pricing & portal SDK on your own website and let visitors subscribe without ever leaving your page.
All amounts are minor-unit integers (kuruş): "price": 49900 means ₺499.00. This holds for every request and response in the subscription API.
The object model
Everything hangs off a simple chain — each object owns the next:
| Object | What it is | Created via |
|---|---|---|
| Product | The thing you sell ("Pro", "Enterprise"). Carries default price-change policy and translations. | POST /api/v1/subscriptions/products |
| Plan | A price + billing cadence for a product: amount, currency, trial days, billing rule, dunning settings. | POST /api/v1/subscriptions/plans |
| Customer | Your end user, upserted by your own externalId — no duplicate bookkeeping. | PUT /api/v1/subscriptions/customers |
| Card | A saved payment method bound to a customer (3DS-verified vault token). | POST /api/v1/subscriptions/cards |
| Subscription | Customer × plan. Owns state (trial, active, paused, canceled) and the billing clock. | POST /api/v1/subscriptions/subscriptions |
| Invoice | Generated automatically each billing period; charged, retried or sent depending on the collection method. | generated by the engine |
Collection methods
When you create a subscription you choose how each invoice gets collected:
collectionMethod | Behaviour |
|---|---|
AUTO_CHARGE | The platform charges the customer's saved card automatically when the invoice is due. Failures enter the plan's dunning schedule (dunningScheduleDays, maxDunningAttempts, gracePeriodDays). |
SEND_INVOICE | The invoice is issued and delivered to the customer for them to pay — no automatic card charge. |
MANUAL | The invoice is created and left open; you collect the money out-of-band and reconcile via the API. |
Sell from your own site
The headline feature: build your pricing page on your own website and take subscribers directly. The publishable-key catalog API serves your plans, products and branding straight to the browser, and the portal JS SDK takes the visitor from "pick a plan" to "card saved, subscription active" — as a drop-in UI, fully headless, or a hybrid of both. No redirect to an external checkout, no iframe walls around your pricing table.
See Pricing & Portal SDK for the end-to-end integration.
Four surfaces
| Surface | Auth | Who calls it | Use it for |
|---|---|---|---|
Merchant API — /api/v1/subscriptions/* | Bearer (at_live_…) | Your backend | Full CRUD: products, plans, customers, cards, subscriptions, invoices, usage |
Public Catalog — /api/public/v1/subscription/* | Publishable key (mk_live_pk_…) + Origin allow-list | The browser | Read-only plans / products / branding for your pricing page |
Customer Portal — /api/portal/v1/* | Portal token → OTP → session JWT | Your end customer | Self-service: view invoices, change plan, update card, cancel |
Portal JS SDK — cdn.lunixi.com | Publishable key or backend-bootstrapped session | The browser | Pricing tables, embedded portal UI, headless subscription flows |
Lifecycle & webhooks
Every transition emits a webhook — subscription.created, subscription.activated, subscription.paused, subscription.canceled, subscription.trial_will_end, invoice.created, invoice.paid, invoice.payment_failed, card.expiring_soon and more. Drive your own provisioning and entitlement logic from these events rather than polling.