CartThrob 10 documentation for ExpressionEngine commerce teams Visit CartThrob.com
CartThrob.com

Subscription Statuses and Access

Every Subscription has a Status. It is shown in the Subscriptions list, the Status filter, and the Edit Subscription form. The status controls whether CartThrob will try to bill the Subscription again. Whether the customer can still see subscription-protected content depends on the status and the Subscription’s End Date.

This page explains each status, how a Subscription moves between them, and what each one means for billing and access.

Status summary

Status What it means Will CartThrob bill it? Does the customer keep access?
Open Active agreement. Yes, when it is due, if a saved card is attached (see No saved card). Yes, unless its End Date has passed.
Hold A renewal failed or could not be prepared. Also used when the End Date has passed but a saved card is still attached. Retried by the rebill command after the Rebill Retry Interval. Only if the End Date is still in the future.
Pending A payment for this Subscription is in progress or needs review. Older versions of Subscriptions also used Pending for other purposes. No. Automatic and manual charges are blocked until the payment is resolved. Only if the End Date is still in the future.
Closed The agreement has ended. No. Only if the End Date is still in the future.

“Access” here means has_subscription_permission. With a valid permission assignment, a Subscription qualifies when:

  • it is Open and has no End Date, or its End Date is still in the future;
  • it is Hold, Pending or Closed and its End Date is still in the future;
  • and it has no completed cancellation refund. A refunded cancellation ends access immediately, whatever End Date is stored.

While a cancellation refund is under review, access lasts no longer than the paid-through date recorded for it.

Access ends at the End Date itself. It doesn’t wait for the rebill command to change the status. has_permission ignores the Subscription entirely. See Which permission tag should I use?

Hold and Pending usually mean no access. A Subscription on Hold after a declined renewal, or Pending while a renewal charge is under review, normally has no End Date. The customer therefore loses subscription access until the payment succeeds or the review is resolved. If a customer reports that they paid but can’t see members content, check Payments > Needs review first.

The dates on a Subscription

Field Meaning
Start Date The billing calendar anchor and earliest date for scheduled billing selection. Frontend checkout uses the checkout time; the Control Panel can store a different date. It does not delay an immediate charge or activate content access. See What Start Date controls.
Last Bill Date When the most recent successful payment was collected.
Next Billing Date The next scheduled renewal. Calendar months keep the same day of the month, using the last day of shorter months (a Subscription started on the 31st renews on June 30, then July 31). Dates are calculated in UTC.
End Date When the Subscription stops, if a stop date is set. A future End Date keeps access after billing has stopped, for example after a cancellation without a refund. Blank means no stop date.

Changing Next Billing Date in the Control Panel moves the schedule without changing payment history. The date you choose, at 00:00 UTC, becomes the new calendar day for later renewals.

Total Occurrences limits the number of payments, counting the first payment at checkout. Used Occurrences counts the payments collected so far. After the final allowed payment, the saved card is removed and End Date is set to the end of that paid period; the Subscription is closed after that date (see Open with no saved card). A blank or 0 Total Occurrences means unlimited.

How a Subscription moves between statuses

Open

A completed checkout, or a Subscription created in the Control Panel, starts Open. Each successful renewal keeps or returns the Subscription to Open, clears the error message, and resets Failed rebill attempts to 0.

Open with no saved card

A Subscription with no saved card (an empty Vault ID) is not renewed. A customer cancellation without a refund works this way:

  • it removes the saved card;
  • it sets End Date to the paid-through date;
  • it leaves the status Open, so the customer keeps access for the time they already paid for.

Collecting the final payment allowed by Total Occurrences has the same effect.

Access ends at that End Date. The next time the rebill command runs after the date, it changes the status to Closed. The status change is bookkeeping only: access has already ended, even if the command is delayed.

Hold

The rebill command places a due Subscription on Hold when any of the following happens:

  • The gateway declines the renewal. Failed rebill attempts increases by one, and the rebill_failure notification is sent.
  • The renewal cannot be calculated or prepared, for example because of a configuration or data problem. This does not count as a failed payment attempt.
  • The End Date has passed while a saved card is still attached.

A Subscription on Hold is retried by the next rebill command after the Rebill Retry Interval (default 24 hours) has passed since it was last changed. Saving the Subscription in the Control Panel restarts that wait. A successful retry returns it to Open.

When a declined renewal reaches Maximum Rebill Attempts (default 4, counting the first decline), the Subscription is Closed instead, and the rebill_final_failure notification is sent. There is always at least one retry: values of 0 and 1 allow two attempts. See Maximum Rebill Attempts.

Pending

CartThrob saves a payment claim before it contacts the gateway for:

  • an automatic renewal;
  • Charge Next Billing;
  • a balance charge during cancellation;
  • a paid Plan change.

While the claim is unresolved, the Subscription is Pending. It cannot be charged, cancelled, changed or edited. If the result is uncertain, the Subscription stays Pending until an administrator resolves it. See Payment review and recovery.

A cancellation refund under review keeps the Subscription Open rather than Pending, so the customer keeps access through the term they already paid for.

Pending was used by older Subscriptions workflows too. A Pending status alone doesn’t prove that a payment needs review. Use Payments > Needs review to find the Subscriptions that do.

Closed

A Subscription becomes Closed when:

  • its Total Occurrences are used up and the last paid period has ended;
  • a declined renewal reaches Maximum Rebill Attempts;
  • the rebill command finds an Open Subscription with no saved card that is past its End Date;
  • a customer or administrator cancels with an immediate end (see the table below);
  • an administrator changes Status to Closed on the Edit Subscription form.

When an administrator changes Status to Closed on the Edit form:

  • An End Date entered in the same save is kept. To close a Subscription and end access at once, set End Date to today in the same save.
  • Otherwise, End Date becomes the Next Billing Date, so the customer keeps the time already paid for. During a trial that is the end of the trial period.
  • An earlier End Date is never moved later, so closing can’t extend access.

Closing through the Edit form does not refund anything, does not send a notification, and leaves the saved card attached.

Closed stops renewal even when a saved card is still attached. Most ways of closing a Subscription, including this one, a declined renewal reaching Maximum Rebill Attempts, and an immediate cancellation, leave the card reference in place. The card is kept so that any open payment or refund review can still be resolved against it. In templates, {is_cancelled} reports whether a card is attached, not whether the Subscription is Closed. Check the status, or {can_renew}, to tell whether it will renew.

Cancellation outcomes

These outcomes apply to the cancel_sub_form tag and the Control Panel Cancel Subscription screen.

Situation Result Access
Paid term, no refund (or no refundable amount) Stays Open, saved card removed, End Date set to the paid-through date. No further renewals. Through the paid-through date.
Paid term, refund requested and a refundable amount exists The refund is sent to the gateway. See Cancellation refunds. Ends immediately once the refund is confirmed. While it is under review, access lasts through the paid-through date at most.
Paid trial Same as a paid term without a refund: stays Open, saved card removed, End Date set to the end of the paid trial period. No refund is calculated. Through the paid trial period.
Free trial Closed immediately. Ends immediately.
Customer is behind on payments, Balance Account selected and a balance is owed The balance is charged first. On success, the Subscription is Closed. Ends on success.
Customer is behind on payments, no balance charged Closed immediately. Ends immediately.

Refund amounts require Purchased Items. Without it, the refundable amount is zero, and a refund request is handled as a cancellation without a refund.

Cancellation refunds

A cancellation with a refund always stops renewal, whatever happens to the refund. What changes is how long access lasts:

Situation Status Renewal Access Review
Refund result uncertain, paid time remains Open Stopped Through the paid-through date Needs review
Refund result uncertain, paid time has ended Closed (after the next rebill run) Stopped None. Access ends at the paid-through date without waiting for the rebill run. Still needs review
Refund completed Closed Stopped Ends immediately Resolved
No refund was made (declined, did not complete, reversed, or Refund not issued), paid time remains Open, not renewing Stopped Remaining paid time only Resolved; the outcome stays in the history
No refund was made, paid time has ended Closed Stopped None Resolved

Example. Jane pays 30.00 for a quarterly membership on March 1 and cancels on April 1 with Refund Difference. The gateway times out, so CartThrob can’t tell whether the refund of about 20.00 for the unused two months went through.

  • The Subscription stays Open but will not renew.
  • Jane keeps access until June 1, when the quarter she paid for ends.
  • The Subscription appears under Payments > Needs review.

The administrator then checks the processor. If the refund completed, they record Refund completed, and Jane’s access ends at once. If it did not, they record Refund did not complete, and Jane keeps access until June 1. If nobody resolves the review by then, Jane’s access still ends on June 1 and the review stays open until someone records the processor result.

See Payment review and recovery for the resolution steps.

Finding Subscriptions in the Control Panel

The Subscriptions list has three filters:

  • Status: Open, Closed, Hold or Pending.
  • Payments:
    • Overdue lists Subscriptions that the next rebill command would process. This includes due renewals, Hold retries whose wait has passed, and Open Subscriptions with no saved card that are past their End Date.
    • Needs review lists Subscriptions with an unresolved payment or refund, whatever their status.
  • Plans.