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

# Subscription Payment Collections

> Offer recurring billing for memberships, SaaS, or services with flexible cycles, tiered pricing, and automated renewals. This is your engine for predictable revenue.

## 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](/api-reference/subscription-plans/create-single-plan), define these key elements:

| Field                 | Description                                                                             |
| --------------------- | --------------------------------------------------------------------------------------- |
| **Title & Frequency** | A descriptive label and how often to charge (Daily, Weekly, Monthly, Annually, etc.).   |
| **Currency**          | You can set pricing in USD or in a Local Currency (e.g., NGN, GHS, ZAF).                |
| **Pricing Options**   | Allows you to set different local prices for the same product across different regions. |

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

```java Create.plan lines icon="repeat" theme={null}
{
  "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 →](/features/mobile-money-subscriptions)

<Info>
  There are rules around which currencies can be combined in a single plan. You can also add free trials and discounts to any plan. See [Plan Trials, Discounts & Currency Rules](/features/plan-trials-discounts-and-currency-rules) for details.
</Info>

## API Management & Enrollment

Once a plan is created, enrolling a customer is simple: reference the planId during the customer's initial charge.

| **Action**                          | **API Endpoint**                                                                 | **Description**                                         |
| ----------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Create Subscription Plan**        | [POST /subscription plans](/api-reference/subscription-plans/create-single-plan) | Create a new subscription programmatically.             |
| **Update Subscription Plan**        | [PUT /subscription plans/{id}](/api-reference/subscription-plans/update-plan)    | Modify quantities, change plans, or set cancellation.   |
| **List/Retrieve Subscription Plan** | [GET /subscriptions](/api-reference/subscription-plans/fetch-plan)               | View all or retrieve details for a single subscription. |

You can also create a ***bulk subscription plan*** using a CSV file. Learn more [here](/api-reference/subscription-plans/create-bulk-plan).

## Enrollment Sample (Using [Spotflow Initialize/Redirect API](/api-reference/payments/initialize-collection)):

When initiating the charge, include the planId and customer details. Spotflow tokenizes the card for future charges based on the plan frequency.

```java Create.plan lines icon="repeat" theme={null}
{
  "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](/api-reference/subscription-plans/create-single-plan), define these key elements:

| **Event**                    | **Purpose**                                             | **Sample Payload Key**                     |
| ---------------------------- | ------------------------------------------------------- | ------------------------------------------ |
| **payment\_successful**      | Notifies you of the first successful payment charge     | {`"event": "payment_successful",...`}      |
| **subscription\_successful** | Notifies you of a successful renewal charge             | {`"event": "subscription_successful",...`} |
| **payment\_failed**          | Alerts you when an attempted charge fails               | {`"event": "payment_failed",...`}          |
| **subscription\_cancelled**  | Notifies you when a customer or you cancel the service. | {`"event": "subscription_cancelled",...`}  |

## Canceling and Activating

* Cancel Subscription: Cancel an individual customer subscription via the [Cancel Subscription Endpoint](/api-reference/subscriptions/subscription-cancel).
* Cancel Plan: Canceling [the entire plan](/api-reference/subscription-plans/cancel-plan) cancels all associated customer subscriptions.
* Reactivating: Canceled [subscriptions](/api-reference/subscriptions/subscription-activate) and [plans](/api-reference/subscription-plans/activate-plan) can be reactivated using the corresponding Activate endpoints.

## 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](/api-reference/subscription-plans/activate-plan).
If you've got any questions, don’t hesitate to reach out to our team at [support@spotflow.one](mailto:support@spotflow.one).