Subscriptions

A subscription binds a customer to a plan and drives the billing engine: trials, period invoices, dunning, plan changes and cancellation. This page covers the whole lifecycle through the merchant API.

All endpoints use your secret key as a Bearer token under https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions — the segment appears twice on purpose: the first subscriptions is the product namespace, the second is this resource group. List endpoints use cursor pagination (pageSize, pageToken).

Lifecycle at a glance

Every transition emits a webhook — subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.canceled — so your system can mirror state without polling. The full event table is at the bottom.

Status values

The status field on a subscription takes exactly these values (you can also filter the list endpoint by status):

Entitlements are honored while the status is ACTIVE or PAST_DUE. Terminal statuses (UPGRADED, DOWNGRADED, CANCELED, EXPIRED) never transition again.

Create a subscription

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_01JX2F9K4T",
    "planId": "plan_01JX2G3M8V",
    "idempotencyKey": "order-84172-sub",
    "paymentCardId": "card_01JX2H5N1Q",
    "collectionMethod": "AUTO_CHARGE",
    "skipTrial": false,
    "startsAt": "2026-08-01T00:00:00Z"
  }'

{
  "success": true,
  "data": {
    "id": "sub_01JX5B8R3M",
    "customerId": "cust_01JX2F9K4T",
    "planId": "plan_01JX2G3M8V",
    "status": "TRIALING",
    "collectionMethod": "AUTO_CHARGE",
    "currentPeriodEnd": "2026-09-01T00:00:00Z"
  }
}

Collection methods

Trials

If the plan has trialPeriodDays > 0, the subscription starts in trial: entitlements are live, but no charge happens until the trial ends. Pass skipTrial: true on create to bypass it and bill immediately.

Before the trial ends the platform emits subscription.trial_will_end — use it to prompt the customer to add or confirm a payment method. When the trial ends, the first period invoice is generated and collected per collectionMethod; the subscription emits subscription.activated.

Cancel

POST /api/v1/subscriptions/subscriptions/:id/cancel

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/cancel \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAtPeriodEnd": true }'

Emits subscription.canceled. Customers can also cancel themselves through the customer portal — that path additionally requires an email confirmation token as fraud protection.

Pause & resume

POST /api/v1/subscriptions/subscriptions/:id/pause suspends billing; pass an optional resumeAt to schedule automatic reactivation. POST /api/v1/subscriptions/subscriptions/:id/resume reactivates immediately.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/pause \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "resumeAt": "2026-10-01T00:00:00Z" }'
 
# later, or instead of resumeAt:
curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/resume \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

While paused, no period invoices are generated. Emits subscription.paused and subscription.resumed.

Change plan (upgrade / downgrade)

POST /api/v1/subscriptions/subscriptions/:id/change-plan with the target newPlanId and a behavior:

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/change-plan \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "newPlanId": "plan_01JX2G9P7W",
    "behavior": "NEXT_PERIOD"
  }'

A common pattern: upgrades IMMEDIATE (the customer gets the bigger plan right away), downgrades NEXT_PERIOD (they keep what they paid for until renewal).

Retrieve, list & audit

The audit log is the tool for support questions like "why did this customer's plan change?" — every mutation above appears there with its timestamp and origin.

Errors

Webhooks

See Webhooks for delivery, retries and signature verification.

Next steps

• Invoices — period invoices, dunning and retry-charge
• Customer Portal — let customers manage their own subscription
• Features & Add-ons — per-subscription add-on charges
• Usage & Entitlements — metered billing and quota checks