Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Recurring Revenue. Automated.

Customers subscribe. We handle billing cycles, renewal recovery, and lifecycle management. You focus on your product.

​
How It Works

Customer subscribes → Billing cycle → Auto-charge → Repeat
If a renewal charge is not collected successfully, the subscription enters past_due. This is a recovery state, not an immediate termination state. The system can keep the subscription in a grace or retry window while the customer updates payment details.

​
Subscription Plan Structure

In Waffo Pancake, each separately purchasable subscription option is an independent subscription product. The most common distinction is billing interval, such as:
  • monthly
  • yearly
If you offer both monthly and yearly billing, you would normally create two subscription products.
Business offerWaffo model
Monthly plan1 subscription product
Yearly plan1 subscription product

​
Subscription States

StatusDescription
pendingAwaiting first payment
activeLive and billing normally
trialingIn free trial period
past_dueRenewal charge not collected, in recovery or grace period
cancelingCancellation requested, access continues until current period ends
canceledWill not renew after current period
expiredSubscription has reached the end of its term
closedNever activated — payment timed out

​
Billing Intervals

IntervalFrequencyBest For
WeeklyEvery 7 daysUsage-heavy products
MonthlyEvery monthStandard SaaS
QuarterlyEvery 3 monthsB2B software
YearlyEvery 12 monthsCommitted customers

​
Free Trials

Reduce signup friction. Let customers try before they commit.

​
Configure Trials

When creating a subscription product, enable the trial toggle and set the number of days in the Dashboard.

​
Platform-Level Trial Protection

Waffo Pancake acts as the Merchant of Record and automatically prevents trial abuse:
LayerHow It Works
Platform (Pancake)Tracks each consumer’s trial history across all merchants. Calculates the maximum available trial days for each new subscription.
MerchantCan pass requested_trial_days when creating an order via API to customize the trial length per customer.
How the two layers interact:
  • If the merchant requests ≤ the platform maximum → the merchant’s requested value is used
  • If the merchant requests > the platform maximum → falls back to the platform maximum
  • If the merchant doesn’t specify → the full platform maximum is used

​
Buyer Identity & Trial Protection

Trial eligibility is tracked by buyerIdentity — a stable identifier you provide via authenticated checkout. The platform uses this to detect repeat trial claims across sessions.
Without buyerIdentity (anonymous checkout), trial eligibility checks are skipped entirely. Any buyer can claim unlimited trials by changing their email address.
7-14 day trials work best. Too short = not enough time to evaluate. Too long = forgotten.

​
Renewal Recovery

When a renewal charge is not collected successfully, the subscription transitions to past_due. This usually means the subscription is in a retry or grace window while the customer updates their payment method, not that access is terminated immediately. Common handling includes:
  • notifying the customer to update payment details
  • keeping access active during a grace period
  • retrying collection based on the dunning policy
Treat past_due as “renewal requires recovery”, not simply “payment failed and service stopped”.

​
Managing Subscriptions

​
Cancel

Cancellation is always effective at the end of the current billing period. When a cancellation is requested, the subscription enters the canceling intermediate state. The customer retains access until the current billing period ends, at which point the status transitions to canceled. 
POST /v1/actions/subscription-order/cancel-order
{
  "orderId": "ORD_5dXBtmF2HLlHfbPNm0Wcnz"
}
Response includes currentPeriodEnd so you know when access expires. The returned status will be canceling (or canceled if the period has already ended).
There is no immediate cancellation option. Customers always retain access through the end of their paid period. The canceling → canceled transition happens automatically when the current billing period expires.

​
Resume Subscription

If a subscription is still in canceling, the customer can resume it before the current period ends. After resuming:
  • the subscription returns to active
  • access continues without interruption
  • future renewals continue on the original billing cycle
Resuming applies to subscriptions that were canceled but have not reached the end of the current period yet. It is effectively an undo for cancellation, not a brand-new purchase.

​
Upgrade/Downgrade

ScenarioBehavior
Upgrade mid-cycleTakes effect immediately
Downgrade mid-cycleTakes effect at the end of the current billing period
POST /v1/actions/subscription-order/change-product
{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "targetProductId": "target-product-uuid"
}
This endpoint currently returns 501 (Not Implemented). Upgrade/downgrade functionality is planned but not yet available.

​
Metrics

​
MRR (Monthly Recurring Revenue)

Weekly subscription:    $10 × 4.33 = $43.30 MRR
Monthly subscription:   $29 × 1 = $29 MRR
Annual subscription:    $290 ÷ 12 = $24.17 MRR

​
Key Metrics

MetricWhat It Tells You
MRRMonthly recurring revenue
Churn% subscriptions canceled
LTVCustomer lifetime value
ARPUAverage revenue per user

​
Webhooks

Subscribe to subscription lifecycle events via webhooks. Configure webhook endpoints in Settings —> Webhooks.
Specific webhook event names are not listed here as they may change. Refer to the webhook configuration in your Dashboard for the current list of available events.
Webhook payloads use standard Waffo Pancake conventions:
  • IDs are UUID v4 format
  • Amounts as display format strings
  • Timestamps in ISO 8601 UTC
  • Billing frequency uses the billingPeriod field (e.g., monthly, yearly)

​
Customer Portal

Let customers manage their own subscriptions:
  • View details
  • Update payment method
  • Change plans
  • Cancel
  • Resume subscription
  • Download invoices

Customer Portal

Self-service subscription management.

​
Best Practices

15-20% off yearly = lower churn + better cash flow.
A missed renewal charge does not need to mean instant cancellation. Give the customer time to recover the subscription.
Trial ending. Upcoming charge. No surprises.