Skip to main content
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.

​
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?

​
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.

​
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.

​
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. Exact timing, suppression rules and how to avoid double-emailing are on Subscription emails to your customers.

​
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.