> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Lifecycle & Payment Method Management

> How to schedule a subscription to start in the future, what you can do before it starts, how users manage multiple payment methods with automatic backup retry, amount-update rules, and the lifecycle notifications Waffo sends to end users.

Deferred starts, payment-method management and end-user notifications across
the subscription lifecycle. Upgrades, per-period amounts and webhook selection
are covered in the [Subscription FAQ](/docs/en/support/subscription-faq).

## Can I create a subscription that starts on a future date?

Yes. Pass `startTime` (ISO 8601 with timezone) when calling
`/api/v1/subscription/create`:

* The subscription is created immediately and activates automatically when
  `startTime` arrives — no scheduler needed on your side. Before the start
  date it is already in `ACTIVE` status with no billing period consumed yet,
  so read `startTime` (not the status) to tell a not-yet-started
  subscription from a running one.
* With a trial configured, the trial starts counting from `startTime`; without
  one, the first deduction is executed on `startTime`.
* `startTime` must be strictly in the future and at most 365 days ahead;
  omitting it keeps the current behavior (immediate start).
* On activation Waffo pushes an activation webhook; a failed first deduction
  enters the normal retry flow.

## Is the user's payment method verified before the start date?

Yes, at creation time, via a **zero-amount authorization** that validates the
method and stores the token for future charges — the user sees a
"verification only, no charge today" step, not a payment.

* If verification fails, the subscription is **not created** and the API
  returns a payment-method verification error — ask the user to try another
  method.
* Your contract must allow zero-amount orders for this flow; otherwise
  creation is rejected.
* No funds are ever held, so cancelling before the start date needs no refund
  handling.

## What operations are allowed before the start date?

| Operation | Allowed? | Behavior |
| - | - | - |
| Cancel | Yes | Status becomes `MERCHANT_CANCELLED` (or `USER_CANCELLED` from the hosted page); no deduction ever happens. |
| Update amounts (`amount` / `scheduledAmounts`) | Yes | New values apply once the subscription activates. |
| Plan change (upgrade / downgrade) | No | Rejected while the subscription has not started. Cancel and re-create instead. |
| Query | Yes | Returns the subscription with its `startTime`; no billing period is consumed yet. |

## Can users change or add payment methods on an existing subscription?

Yes, on the hosted subscription management page. Users can add extra payment
methods, set a new default, reorder backups, or delete a method.

* Supported for **card, Apple Pay and Google Pay** subscriptions only, and
  not once the subscription is cancelled or expired; the default method of an
  active subscription cannot be deleted.
* The subscription detail response returns `canChangePaymentMethod` and the
  list of bound payment methods so you can drive your own UI.
* A newly added method is verified with the same zero-amount authorization
  flow; switching the default takes effect from the next deduction.

## What happens when the default payment method fails to charge?

If backup payment methods are bound, Waffo **immediately retries with the
backups in priority order**, without waiting for the normal retry interval:

* When a backup succeeds, the user is emailed and asked whether to make it
  the new default (the stored default stays unchanged until they confirm).
* If every backup fails, the order falls back to the configured retry
  strategy on the default method. Backup attempts are **not** counted against
  the card-scheme rolling retry window, and they do not trigger the
  payment-failed email — see
  [Subscription retries & payment methods](/docs/en/support/subscription-retry-and-payment-methods-faq).

## Can I raise the amount through the update API?

No. `/api/v1/subscription/update` (both `amount` and `scheduledAmounts`)
only accepts values **lower than or equal to** the current ones. To charge
more, use `/api/v1/subscription/change` and move the user to a new plan.

After a successful update, Waffo emails a price-change notice to the subscriber
(original amount, new amount, effective period) — provided that notification is
enabled on your account — and pushes `SUBSCRIPTION_UPDATE_NOTIFICATION` to the
subscription's `notifyUrl`. The `update` response is still the primary record
of what changed, so persist it; the webhook confirms the same change
asynchronously. Changes apply from the next billing period; the current period
is untouched. See
[Subscription amounts & per-period scheduling](/docs/en/support/subscription-amount-scheduling-faq).

## Which notifications does Waffo send to my end users?

Waffo emails subscribers directly at key lifecycle points. Each type can be
enabled or disabled per merchant; the language is the subscription's
`cashierLanguage` if you set one, otherwise derived from the user currency.

| Notification | Trigger |
| - | - |
| Subscription activated | First-period payment succeeds. |
| Trial ending reminder | Sent shortly before the trial period ends. |
| Upcoming charge notice | Sent ahead of each deduction, trial periods included. |
| Payment failed | A scheduled retry attempt or the final attempt fails; includes a link for the user to add or update payment methods. **Not** sent for a first-period failure or for backup-method attempts. |
| Cancellation confirmation | Cancellation completes. |
| Subscription changed | You change the amount through the update API. |

Exact timing, suppression rules and how to avoid double-emailing are on
[Subscription emails to your customers](/docs/en/support/subscription-notifications-faq).

## How are failed deductions retried?

Automatically, per the retry strategy configured for your contract; the
schedule adapts to the billing cycle. Additional behaviors:

* Retries end when the period's attempts reach the contract maximum (the
  period's order closes; the subscription itself stays `ACTIVE`) or when the
  subscription is cancelled with the close-retries-on-cancellation setting on.
  There is no separate "non-retryable decline" class that ends retries early.
* Card retries are additionally capped by card-network compliance rules;
  attempts beyond the cap are deferred automatically.
* Whether pending retries stop the moment a subscription is cancelled depends
  on a setting in your contract. If you require that no further attempt is
  made after cancellation, confirm this setting with integration support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.