Use the status field together with isActive to decide whether a customer should have access to your product or service.

Status Values

Status	Access	Description
ACTIVE	Yes	Subscription is active and the customer should have access. Future renewals will be attempted according to the plan interval.
PAST_DUE	No	A renewal payment failed. The customer should not have access until payment succeeds. The system may retry within the configured grace period.
NON_RENEWING	Yes, until period end	Subscription is still active for the current paid period but will not renew.
COMPLETED	No	Subscription has completed all allowed billing cycles, usually because `invoiceLimit` was reached.
CANCELLED	No	Subscription has been cancelled and will no longer renew or retry.

Access Control

To decide whether a customer should have access, use:

Grant Access When

status = ACTIVE and isActive = true

Ending Subscriptions (Grace Period)

status = NON_RENEWING and isActive = true
The customer may keep access until currentPeriodEnd

Do NOT Grant Access When

status = PAST_DUE
status = CANCELLED
status = COMPLETED
isActive = false

Status Scenario

{
  "status": "ACTIVE",
  "isActive": true,
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "nextPaymentDate": "2026-06-01T00:00:00.000Z"
}

Meaning:
Customer has access.
Next renewal will be attempted on nextPaymentDate.

{
  "status": "PAST_DUE",
  "isActive": false,
  "pastDueAt": "2026-06-01T00:00:00.000Z",
  "nextRetryAt": "2026-06-02T00:00:00.000Z",
  "retryCount": 1,
  "maxRetryCount": 3,
  "gracePeriodDays": 3
}

Meaning:
Renewal failed.
Customer should not have access.
System will retry payment at nextRetryAt.

{
  "status": "NON_RENEWING",
  "isActive": true,
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "cancelReason": "cancel_at_period_end"
}


Meaning:
Customer keeps access until currentPeriodEnd.
Subscription will not renew afterward.

{
  "status": "COMPLETED",
  "isActive": false,
  "invoiceLimit": 12,
  "invoicesPaid": 12
}


Meaning:
Subscription has been cancelled.
Customer should not have access.
No future renewals will be attempted.

{
  "status": "CANCELLED",
  "isActive": false,
  "cancelledAt": "2026-06-01T10:00:00.000Z",
  "cancelReason": "payment_failed"
}

 
Meaning:
Subscription has been cancelled.
Customer should not have access.
No future renewals will be attempted.

Status Transitions

Create subscription
→ ACTIVE
→ renewal succeeds
→ ACTIVE

ACTIVE
→ payment fails
→ PAST_DUE
→ retry succeeds
→ ACTIVE

ACTIVE
→ payment fails
→ PAST_DUE
→ retries fail
→ CANCELLED

ACTIVE
→ NON_RENEWING
→ current period ends
→ CANCELLED or COMPLETED

ACTIVE
→ invoicesPaid reaches invoiceLimit
→ COMPLETED