Subscriptions

Subscription is billing state; entitlement is an application decision

Store the subscription_id, status, Product, ProductPrice snapshot, and current-period end. Query BenefitGrants when your application needs the current entitlements.

const subscription = await fetch(
  `${apiUrl}/public/v2/subscriptions/${subscriptionId}`,
  { headers: apiHeaders },
).then((res) => res.json())

State and access

Grant access only after a valid Checkout and its Subscription event. active and recovery-state past_due retain BenefitGrants; canceled revokes them.

Renewal lifecycle

PayOS does not automatically debit recurring payments. Before renewal VietBilling creates a pending Order, Checkout, and Payment attempt. When payment succeeds, order.paid, payment.succeeded, checkout.succeeded, and subscription.updated advance the period.

1. Store every webhook event id idempotently.
2. Deliver the renewal Checkout URL through your channel.
3. Receive subscription.updated after Payment succeeds.
4. Update the current period and refresh BenefitGrants.

Do not renew access merely because a customer opened the renewal URL.