> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Subscriptions
> Recurring billing for ongoing access to products and services — pricing setup, billing lifecycle, invoicing, and customer management.
Subscriptions let you sell ongoing access to a product or service with recurring billing. Customers purchase a subscription plan at checkout, and TWICE handles the billing cycle — generating invoices, collecting payments off-session, retrying failures, and sending lifecycle emails.
Subscriptions are available on all TWICE Commerce plans. They are not available for Wix-integrated storefronts.
## How it works
A subscription starts when a customer purchases a listing that has subscription pricing. The lifecycle has four phases:
1. **Setup** — you configure subscription plans on a listing's Price Table (commitment length, payment cycle, renewal behaviour, cancellation terms).
2. **Purchase** — the customer selects a plan on the storefront, picks a start date, and checks out. TWICE captures the first payment and stores the card for future billing.
3. **Billing** — daily automated jobs generate invoices at each billing cycle, collect payment off-session, and retry failures. The subscription stays active as long as payments succeed.
4. **End** — the subscription ends by cancellation (customer or merchant), commitment completion (no renewal), or payment failure after all retries are exhausted.
### Subscription statuses
| Status | Meaning |
| :------------ | :------------------------------------------------------------------------------------------------------------------ |
| **Active** | Billing normally. If a cancellation is scheduled, the admin shows "Cancels {date}" while the status remains active. |
| **Past due** | A charge failed but automatic retries are still scheduled. |
| **Failed** | All retry attempts are exhausted. No further automatic collection. You can retry manually from the admin. |
| **Completed** | The commitment period ended and no renewal is configured. Terminal. |
| **Cancelled** | Cancelled by the customer or merchant. Terminal. |
## Pricing setup
Subscription pricing is configured as pricing rows on a [Price Table](/docs/concepts/catalog/price-tables). Enable the **Subscriptions** toggle on the Price Table, then add one or more subscription plans.
Each subscription pricing row defines a plan with these fields:
| Field | Description |
| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label** | Customer-facing plan name (e.g. "Monthly", "Annual"). |
| **Price** | Per-cycle price in your store currency. |
| **Payment cycle** | How often the customer is billed — a unit (`days`, `weeks`, `months`, `years`) and an amount. Example: every 1 month. |
| **Commitment cycles** | Number of payment cycles the customer commits to. A 3-cycle commitment on a monthly plan means 3 months minimum. Maximum 24 cycles. |
| **Initial charge type** | When the first invoice is due: at **order creation** (charged immediately at checkout) or at **subscription start** (charged on the start date). |
| **Renewal type** | What happens after the commitment ends: **Auto-renew** continues billing per cycle until cancelled; **None** ends the subscription when the commitment completes. |
| **Renewal price** | Per-cycle price after the commitment period (auto-renew only). Leave blank to continue at the original price. |
| **Collection method** | **Charge automatically** (default) collects via the stored card. **Send invoice** generates the invoice without charging — the customer pays manually. |
| **Cancellation lead time** | How far in advance a cancellation must be requested (e.g. 1 month). The cancellation takes effect at the later of the notice period end and the commitment end. |
### Per-variant pricing
If a listing has [variants](/docs/concepts/catalog/variants), subscription plans use the same base plan definition for all variants. Each variant value can apply a **rate multiplier** to the base price. A multiplier of `1.0` matches the base; `1.2` adds 20%; `0.8` discounts by 20%.
### Multiple plans
A Price Table can hold multiple subscription rows. The storefront displays them as a dropdown so the customer can pick a plan (e.g. "Monthly" vs "Annual"). If only one plan exists, it displays inline without a selector.
## Storefront purchase flow
On the listing page, the booking widget shows a **subscription details** section when the listing has subscription pricing:
1. **Plan selection** — if multiple plans exist, a dropdown shows each plan with its rate label (e.g. "€10.00/month"). Single-plan listings display the rate inline.
2. **Start date** — a calendar lets the customer pick when the subscription begins. Days without available inventory are disabled.
3. **Subscription summary** — a summary card shows the product, per-cycle rate, pay-now amount, and next billing date.
4. **Schedule preview** — a timeline previews the billing schedule: the pay-now charge followed by future billing dates with amounts, ending with "until cancelled" (auto-renew) or the final cycle date.
5. **Add to cart** — the customer clicks "Buy subscription" to add the plan to their cart. The subscription terms are frozen at this point and carried through checkout.
At checkout, the customer's card is stored for future off-session billing (via Stripe mandate or Adyen tokenisation).
## Billing lifecycle
### Daily billing jobs
Three automated jobs run daily to manage subscription billing:
| Job | Schedule | What it does |
| :--------------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Invoice generation** | 06:00 (account timezone) | Finalises any due cancellations, then generates invoices for subscriptions whose next billing date has arrived. Auto-collected invoices are charged immediately. |
| **Payment retries** | 06:30 (account timezone) | Retries payment on open invoices whose retry date has arrived. |
| **Notifications** | 07:00 (account timezone) | Sends renewal-upcoming and ending-soon emails for subscriptions due or ending in 7 days. |
### Invoice generation
Each billing cycle generates an Invoice linked to the order. The invoice captures the billing period (start and end dates), line items, and amounts. A unique constraint on subscription + period start date prevents double-billing.
Invoice statuses:
| Status | Meaning |
| :---------------- | :--------------------------------------- |
| **Draft** | Just created, not yet finalised. |
| **Open** | Finalised and awaiting payment. |
| **Cancelled** | Withdrawn — no longer owed. |
| **Uncollectible** | Written off as bad debt by the merchant. |
Whether an invoice is paid is determined by its linked payments, not the status field. An open invoice with a successful payment is considered paid.
### Off-session payment collection
TWICE collects subscription payments automatically using the card the customer provided at checkout:
* **Stripe**: uses `off_session` PaymentIntents with the stored mandate
* **Adyen**: uses `ContAuth` shopper interaction with `UnscheduledCardOnFile` recurring model
If a payment requires 3D Secure (SCA) challenge, the charge fails because no customer is present to complete authentication. The subscription enters the retry flow.
### Payment retry schedule
When a charge fails, TWICE retries on an escalating schedule measured from the invoice due date:
| Attempt | Days after due date |
| :---------- | :------------------ |
| 1 (initial) | 0 (due date) |
| 2 | +1 day |
| 3 | +3 days |
| 4 | +5 days |
| 5 | +7 days |
After 5 failed attempts, automatic collection stops and the subscription status changes to **Failed**. You can still retry manually from the admin.
During retries the subscription status is **Past due**. The customer receives a payment-failed email after each unsuccessful attempt.
## Cancellation
Cancellation honours both the commitment period and the notice period:
* The cancellation takes effect at the **later** of the notice period end and the commitment end. A customer on a 6-month commitment with 1-month notice who cancels in month 2 will have the subscription end after month 6 (commitment takes precedence).
* While a cancellation is pending, the subscription stays **Active** and continues billing any in-window cycles. The admin shows "Cancels {date}" on the status chip.
* On the effective cancellation date, a daily sweep changes the status to **Cancelled**.
Customers can cancel through the self-service portal (if available). Merchants can cancel from the admin order view.
## Email notifications
TWICE sends lifecycle emails for subscription events. You manage templates under **Settings → Emails**.
| Email | When it sends | Default state |
| :-------------------- | :------------------------------------- | :------------- |
| **Payment upcoming** | 7 days before a renewal charge | Draft (opt-in) |
| **Payment confirmed** | After a successful charge | Active |
| **Payment failed** | After a failed charge attempt | Active |
| **Cancelled** | When cancellation is confirmed | Active |
| **Ending soon** | 7 days before a non-renewing plan ends | Draft (opt-in) |
Draft templates are not sent until you activate them. Edit the email content under **Settings → Emails** to match your brand voice.
## Subscription discounts
[Discount codes](/docs/concepts/catalog/discount-codes) support subscription-specific duration settings that control how long the discount applies:
| Duration | Behaviour |
| :------------ | :---------------------------------------------------------------- |
| **Once** | Applies to the first billing cycle only. |
| **Repeating** | Applies for a set number of billing cycles (e.g. first 3 months). |
| **Forever** | Applies to every billing cycle for the life of the subscription. |
When creating a discount code, restrict it to the **Subscription** purchase type and choose the duration. The discount allocation tracks which cycle it starts applying from.
## Admin management
### Order summary
The order summary tab shows subscription-specific details for each subscription line item:
* **Status chip** — current subscription status with colour coding (green for active, yellow for past due, red for failed)
* **Invoiced to date** — total amount invoiced across all cycles
* **Paid** — total amount collected
* **Commitment until** — end date of the commitment period
* **Renewal** — "Auto-renew at {rate}" or "No renewal"
* **Cancellation notice** — required lead time and earliest possible cancellation date
### Invoices table
The Payments tab includes an invoices table with columns for invoice number, status, billing period, total, and issued date. Available actions on open invoices:
* **Mark as paid** — record an off-platform payment
* **Retry** — attempt to collect payment again
* **Write off** — mark as uncollectible (bad debt)
* **Cancel** — withdraw the invoice (only if no payments have been captured)
Each invoice can be downloaded or printed as a PDF.
## Related
Configure subscription pricing rows on Price Tables.
Subscription as a purchase type alongside rental and sale.
Subscription-specific discount durations.
Payment collection and refund flows.