Lifecycle and statuses
Use this page to understand subscription statuses and the fields your backend should inspect before granting, extending, recovering, or ending access.
Subscription status is one signal. For paid access, combine status with invoice events and billing-period fields.
What this page is for
This page explains:
- subscription lifecycle states;
- which statuses are active, recoverable, terminal, or uncommon;
- how billing-period fields affect access decisions;
- how cancellation fields affect access decisions;
- how payment failure and recovery fit into the lifecycle;
- how Paypercut retries failed automatic payments.
Subscription lifecycle overview
Most subscription integrations move through this shape:
- The subscription is created.
- Paypercut attempts the first payment or waits for a trial or anchor.
- The subscription becomes
active,trialing,past_due, or fails before creation depending on the flow. - Paypercut creates invoices for billing periods.
- Your backend uses invoice events to grant, extend, or recover access.
- The subscription eventually continues, is canceled, or reaches another terminal state.
Status reference
| Status | What it means | Should the customer have access? | What your backend should do |
|---|---|---|---|
incomplete |
Subscription exists, but the first payment has not been fully collected yet. | Usually no paid access unless your access rules deliberately allow a grace state. | Wait for invoice/payment outcome or retrieve latest state before granting access. |
trialing |
Subscription is in a trial period and no charge is due until the trial ends. | Your access rules. Grant trial access only if your business offers it. | Track trial_start and trial_end; prepare for first billing at trial end. |
active |
Subscription is active and billing normally. | Usually yes, if the relevant billing period is paid or otherwise allowed by your policy. | Keep access aligned with invoice.paid, current_period_end, and your plan mapping. |
past_due |
A recent automatic charge failed. Paypercut retries the charge on a fixed schedule; see Failed payment retries. | Your access rules. Some businesses allow a grace period; others restrict access. | Handle invoice.payment_failed, notify the customer, and recover with a valid payment method. |
incomplete_expired |
All payment retries for a default_incomplete subscription failed. Terminal. |
No paid access. | Stop provisioning and ask the customer to start a new subscription flow. |
canceled |
Subscription has been canceled. Terminal. | No access after the effective end of service. | Stop future billing and end access according to your cancellation policy. |
unpaid |
Public enum value for unpaid subscriptions. Failed payment retries do not move a subscription to unpaid. |
Treat defensively as non-active unless your account has explicit guidance. | Retrieve latest state and decide recovery or support action. |
paused |
Public enum value for paused billing. Not verified as a primary public flow in this phase. | Merchant policy. | Retrieve latest state and avoid assuming billing is continuing. |
Access decision guidance
Use a layered decision:
- Map the subscription to your internal account.
- Check the latest subscription
status. - Check invoice events for the billing period.
- Check
current_period_startandcurrent_period_end. - Check cancellation fields.
- Apply your access rules for trials, grace periods, and failed payments.
invoice.paid is the main paid-period signal. invoice.payment_failed is the main recovery signal. Payment and PaymentIntent events are useful for support and reconciliation, but they should not be the primary subscription access contract.
Billing period fields
| Field | Use |
|---|---|
current_period_start |
Start of the current billing period. |
current_period_end |
End of the current billing period. Use this when deciding how long paid access should last. |
next_billing_date |
Next scheduled billing date. Useful for customer-facing billing UI and support. |
billing_cycle_anchor |
Reference point for future billing dates. |
Do not extend access only from next_billing_date. Use paid invoice events and the current billing period.
Cancellation fields
| Field | Use |
|---|---|
cancel_at_period_end |
Indicates a subscription is intended to cancel at the end of the current period. |
cancel_at |
Indicates a scheduled cancellation date when present. |
canceled_at |
Timestamp when cancellation was recorded. |
ended_at |
Timestamp when the subscription ended. |
cancellation_details |
Reason or feedback details attached to cancellation. |
For immediate cancellation, end access according to your access rules and latest subscription state.
For period-end or scheduled cancellation, the public OpenAPI describes cancel_at_period_end and cancel_at, but the verified service path still needs confirmation before this guide gives detailed task instructions. Until that is resolved, retrieve the subscription after cancellation changes and use the returned fields as the source of truth.
Payment failure and recovery states
When collection fails:
- Paypercut sends
invoice.payment_failed. - The subscription can move to
past_due. - Your backend should notify the customer or show recovery UI.
- After the customer has a valid payment method, your backend can use resume for eligible
past_dueautomatic-collection subscriptions. - A successful resume moves the subscription back to
active. - A failed resume returns
402and leaves the subscriptionpast_due.
Failed payment retries
When an automatic charge for a subscription is declined, Paypercut retries it. This applies to the first charge of a subscription created with default_incomplete or allow_incomplete, the first charge after a trial, and every renewal.
Retry schedule
Paypercut makes up to three charge attempts for each billing period:
| Attempt | When Paypercut makes it |
|---|---|
| Original charge | On the billing date. |
| Retry 1 | 24 hours after the original charge is declined. |
| Retry 2 | 48 hours after retry 1 is declined, about 72 hours after the original decline. |
The schedule is the same for every account and cannot be changed per subscription.
Only a decline from the customer's payment method uses up an attempt. If an attempt ends with a technical error or an unknown outcome, Paypercut confirms the result of that attempt instead of charging again, and the attempt does not count as a decline.
Status during retries
While retries are pending, the subscription is past_due. This applies to every payment_behavior, with one exception at creation:
- With
error_if_incomplete, Paypercut charges the first payment before it creates the subscription. If that charge is declined, the API returns402, no subscription is created, and there are no retries. Declined renewals are retried as described on this page. - With
allow_incompleteordefault_incomplete, a declined first charge moves the new subscription topast_dueand starts the retry schedule.
When a retry succeeds
The subscription moves back to active. The billing dates do not move: the paid period starts on the original billing date, not on the date of the successful retry, and the next renewal stays on its usual date.
When all retries fail
If retry 2 is declined, Paypercut stops retrying and ends the subscription:
payment_behavior |
Final status |
|---|---|
default_incomplete |
incomplete_expired |
allow_incomplete or error_if_incomplete |
canceled, with cancellation_details.reason set to payment_failed |
Treat both statuses as ended: Paypercut does not charge the subscription again, and the customer must start a new subscription to continue. Retrieve the subscription to read its final status rather than assuming one.
Recover a payment during retries
- Update the payment method. Ask the customer for a new payment method and set it as the subscription's
default_payment_method. Paypercut does not charge immediately; the next scheduled retry uses the new payment method. - Cancel the subscription. Canceling a
past_duesubscription stops the remaining retries.
Every retry follows the same schedule regardless of the decline reason, so a card that is declined as expired or closed is still retried. Ask the customer to update their payment method as soon as you receive invoice.payment_failed instead of waiting for the retries to finish.
Trial states
trialing is externally visible. During trial, Paypercut does not collect the initial charge until the trial ends.
Whether a trialing customer has access to your service is decided by your access rules. If you grant trial access, store the trial dates and define what happens when the trial ends without successful payment.
Reserved or uncommon statuses
The public enum includes paused and unpaid. This phase did not verify a public beginner flow that creates those states. Treat them defensively:
- do not assume billing is continuing;
- retrieve latest subscription and invoice state;
- avoid granting paid access unless your access rules explicitly allow it.
Common mistakes
- Granting access from the Checkout success URL.
- Treating
201 Createdfrom direct creation as paid access proof. - Ignoring
invoice.payment_failed. - Ending access immediately on every failed payment without checking your grace-period rules.
- Assuming
trialingalways grants access. - Assuming
pausedorunpaidbehave likeactive.

