Skip to main content
This page answers the questions merchants ask most often about Waffo subscriptions. Field-level contracts live in the Subscription API Specification.

​
How do I upgrade or downgrade a user’s plan?

Call /api/v1/subscription/change. The change request creates a new subscription based on the original one, and any remaining amount from the original subscription is applied to the new one — you do not need to cancel and re-create manually.
  • Track the result with /api/v1/subscription/change/inquiry.
  • Waffo also pushes a SUBSCRIPTION_CHANGE_NOTIFICATION when the change completes.

​
What is the difference between change, update, and manage?

Amount updates are validated against your contract limits.

​
Can I charge different amounts in different periods?

Yes. Two mechanisms combine to cover tiered pricing and first-period offers:
  • Trial periods — set trialPeriodAmount and numberOfTrialPeriod when creating the subscription. Custom trial granularity is supported via trialPeriodType and trialPeriodInterval.
  • Scheduled amounts — configure per-period amounts for specific formal periods (for example, a discounted first period), either at creation or later through /api/v1/subscription/update.
If a period has no scheduled amount, the subscription’s base amount applies.

​
A deduction failed. What happens next?

Failed deductions are retried automatically according to the subscription’s retry strategy — you do not need to trigger retries yourself.
  • Every payment attempt, including failure reason, timestamp and retry details, is pushed through the subscription payment order notification.
  • If you only care about the final outcome of each billing period, listen to SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION instead — it fires once per period with the final result and skips intermediate retry events.
The specific retry schedule and caps depend on the retry strategy configured for your contract. Contact integration support if you need the exact policy for your account.

​
Which subscription notifications should I listen to?

For any notification, respond with success after processing. If Waffo receives failed or unknown, Waffo retries the notification on a back-off schedule spread over the following day; see Webhook retry for the schedule.

​
How does a user cancel a subscription?

Two paths:
  • Merchant-initiated — call /api/v1/subscription/cancel.
  • User-initiated — redirect the user to the hosted management page obtained from /api/v1/subscription/manage, where they can view details and cancel.
  • Wallet-side — if the user revokes the payment authorization inside their wallet app, the wallet notifies Waffo. If the revoked method was the only one on the subscription, the subscription is cancelled automatically; if a backup method is available, that method becomes the default instead. This is reported to you through the subscription status notification, so treat the webhook — not your own records — as the source of truth for whether a subscription is still active.
Once a subscription reaches a cancelled state no new billing period is opened. Whether an already-pending retry is dropped immediately depends on a setting in your contract — confirm it with integration support if that matters to you.

​
Does Waffo support daily billing or cross-currency subscriptions?

Yes on both:
  • DAILY is a supported periodType, alongside the other billing cycles.
  • Cross-currency subscriptions are supported via the userCurrency field — the user pays in their local currency.
Payment-method-specific capabilities and limitations are listed in the appendix of the Subscription API Specification.

​
What should I pass in subscriptionManagementUrl?

subscriptionManagementUrl is documented as required on subscription create and you should always send it. Be aware that the server does not currently reject a request that omits it — an omission will not surface as a validation error, it will surface later as a missing link in the customer emails that are routed to your page. Point it at a page the user can open in a desktop browser. An app deeplink is a poor choice here: users who open it on a PC may not be able to reach the page at all. You have three options:
  • Build your own authenticated subscription management page and pass its URL.
  • Wrap the hosted page Waffo returns from /api/v1/subscription/manage in a page of your own and pass that.
  • Use Waffo’s hosted management page directly.
The page is a feature entry point, not a step in the payment flow. It is not shown during the real-time transaction; you surface it after the subscription payment succeeds — in the user’s account area, an order confirmation page, or anywhere else that suits your site.

​
I received a subscription notification, but an immediate query says the subscription is not ACTIVE

Subscription state is eventually consistent. When a notification arrives, the internal state update can still be settling, so a query fired immediately afterwards may return a status that is not yet ACTIVE. That is a read timing effect, not a failed subscription. Handle it like this:
  • Do not treat the first inquiry result as final. Re-query after a short pause.
  • Prefer the subscription status notification as your trigger for state changes, and use the inquiry to confirm rather than to decide.

​
Can the trial-period amount be the same as the regular amount?

No. At creation trialPeriodAmount must be strictly lower than amount; an equal value is rejected with a parameter error whose message reads trial period amount should be less than subscription amount. Zero is a valid trial amount (a free trial), so the accepted range is 0 ≤ trialPeriodAmount < amount. If the trial is meant to shift the billing calendar without changing the price, do not configure a trial at all — use startTime to defer the first charge, or scheduledAmounts to price specific early periods.