Hosted checkout

Subscriptions

Sell a SUBSCRIPTION offer once; PayLumia runs renewals, grace and retries. You read, cancel and resume.

How they start

A hosted payment on a SUBSCRIPTION offer collects consent, starts the subscription and returns a subscriptionUid. Renewals are platform-managed: you never trigger a charge. Each collected renewal arrives as entitlement.updated; loss of access as entitlement.revoked.

Trials

When the offer has trial days, the first payment succeeds with nothing charged. The subscription is TRIALING until trialEndsAt, and you receive subscription.trial_started, then subscription.trial_will_end as a reminder.

Read

GET/v1/subscriptions/{subscriptionUid}

200 OK

{
  "success": true,
  "data": {
    "subscriptionUid": "sub_2Rt8xVq0LmN4pK7a",
    "status": "ACTIVE",
    "productUid": "premium",
    "offerUid": "premium_daily",
    "subscriberUid": "sbr_7Hq2LmN4pR8sT1vW",
    "currentPeriodEnd": "2026-09-21T15:12:44Z",
    "cancelAt": null
  }
}

Cancel

POST/v1/subscriptions/{subscriptionUid}/cancel

whenenumrequired: NOW ends access immediately. PERIOD_END keeps access until cancelAt, the end of the last paid period.

cURL

curl -X POST https://api.sandbox.paylumia.com/v1/subscriptions/sub_2Rt8xVq0LmN4pK7a/cancel \
  -H "Authorization: Bearer $PAYLUMIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "when": "PERIOD_END" }'

Resume

POST/v1/subscriptions/{subscriptionUid}/resume

Withdraws a scheduled PERIOD_END cancellation and returns the subscription to ACTIVE. No body. It is not a plan change.

Statuses you’ll see

Status	Meaning
`TRIALING`	In a free trial.
`ACTIVE`	Paid and running.
`PRE_CANCELED`	Will end at cancelAt; access continues until then.
`IN_GRACE`	A renewal could not be collected yet; access per your offer’s grace policy.
`SUSPENDED · CANCELED · EXPIRED`	Access has ended.