Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotflow.one/llms.txt

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

​
What Subscriptions Are (And Who Needs Them)

Subscriptions are recurring products purchased on a set schedule. They are perfect for:
  • SaaS Licenses: Apps, APIs, or platform access.
  • Memberships: Communities, programs, or clubs.
  • Digital Content: Courses, media, or premium access.

​
Key Benefits of Spotflow Subscriptions:

  • Predictable Revenue: Automated renewals handle the heavy lifting.
  • Flexible Cycles: Monthly, daily, weekly, annual, custom intervals, and trials are all supported.
  • Plan Agility: Manage upgrades, and optional add-ons.
  • Developer-First: Clear APIs for creation, changes, and usage tracking.

​
Core Requirement: Card Tokenization

Spotflow’s recurring billing relies on secure Card Tokenization. How it Works: After a customer’s initial successful card payment, Spotflow replaces the sensitive card information with a unique, secure token. Subsequent payments are processed using this token. Therefore, recurring payments are currently limited to card payments only. You can choose automated payment plans, Set the cycle and amount; Spotflow handles the rest.

​
Creating Subscription Plans

Create recurring plans either directly in your Spotflow Dashboard or programmatically via API. To set up a recurring billing plan, define these key elements:
FieldDescription
Title & FrequencyA descriptive label and how often to charge (Daily, Weekly, Monthly, Annually, etc.).
CurrencyYou can set pricing in USD or in a Local Currency (e.g., NGN, GHS, ZAF).
Pricing OptionsAllows you to set different local prices for the same product across different regions.

​
Example: Creating a Local Currency Plan (NGN, GHS)

Create.plan
{
  "title": "My Pro Plan",
  "frequency": "MONTHLY",
  "pricingOptions": [
    { 
       "amount": 10000, "currency": "NGN" 
    },
    {  "amount": 10, "currency": "GHS" 
    }
  ]
}

​
Mobile Money Subscriptions

If your customers pay via mobile money, the recurring billing flow works differently from card subscriptions. Instead of card tokenisation, Spotflow uses a mandate system where the customer approves recurring charges upfront. Learn how to set up mobile money subscriptions →

​
API Management & Enrollment

Once a plan is created, enrolling a customer is simple: reference the planId during the customer’s initial charge.
ActionAPI EndpointDescription
Create Subscription PlanPOST /subscription plansCreate a new subscription programmatically.
Update Subscription PlanPUT /subscription plans/Modify quantities, change plans, or set cancellation.
List/Retrieve Subscription PlanGET /subscriptionsView all or retrieve details for a single subscription.
You can also create a bulk subscription plan using a CSV file. Learn more here.

​
Enrollment Sample (Using Spotflow Initialize/Redirect API):

When initiating the charge, include the planId and customer details. Spotflow tokenizes the card for future charges based on the plan frequency.
Create.plan
{
  "planId": "961ca3d6-0505-4bc5-8dd3-fc160ac4afc9",
  "currency": "USD",
  "localCurrency": "NGN", // Used for FX calculation in the local region
  "customer": 
  { "email": "customer@email.com" 
  }, // ... other charge details (encrypted card, metadata)
}

​
Webhooks: Real-Time Event Tracking

Spotflow sends automated webhooks to your server for all critical subscription events. To set up a recurring billing plan, define these key elements:
EventPurposeSample Payload Key
payment_successfulNotifies you of the first successful payment charge
subscription_successfulNotifies you of a successful renewal charge
payment_failedAlerts you when an attempted charge fails
subscription_cancelledNotifies you when a customer or you cancel the service.

​
Canceling and Activating

​
Best Practices

  • Start with clear tiers: Keep base plans simple and define 2–3 plans with obvious value differences.
  • Communicate pricing: Always show the total price, proration costs (if applicable), and the date of the next renewal.
  • Test changes: Validate all plan changes and proration logic meticulously in Test Mode before deploying live.
To learn more about what you can do with plans on Spotflow, check out our API Reference. If you’ve got any questions, don’t hesitate to reach out to our team at support@spotflow.one.