Plan Trials, Discounts & Currency Rules

This page covers three things that affect how you configure subscription plans on Spotflow: free trials, discounts, and the rules around mixing currencies in a single plan.

Currency Rules

USD Plans Are Standalone

If you want to bill in USD, it must be its own plan. You cannot combine USD with any other currency in the same plan’s pricing options. This is not allowed:

{
  "title": "Pro Plan",
  "frequency": "MONTHLY",
  "pricingOptions": [
    { "amount": 10, "currency": "USD" },
    { "amount": 5000, "currency": "NGN" }
  ]
}

This is correct — USD only:

{
  "title": "Pro Plan – USD",
  "frequency": "MONTHLY",
  "pricingOptions": [
    { "amount": 10, "currency": "USD" }
  ]
}

Local Currencies Can Be Combined

You can group any combination of local currencies — NGN, GHS, TZS, KES, ZAR, XOF, XAF, and others — into a single plan. This is the recommended approach if you serve customers across multiple African markets. This is correct — multiple local currencies in one plan:

{
  "title": "Pro Plan – Africa",
  "frequency": "MONTHLY",
  "pricingOptions": [
    { "amount": 5000, "currency": "NGN" },
    { "amount": 10, "currency": "GHS" },
    { "amount": 2000, "currency": "TZS" }
  ]
}

Summary

Combination	Allowed
USD only	✅
NGN + GHS	✅
NGN + GHS + TZS + KES	✅
USD + NGN	❌
USD + GHS	❌
USD + NGN + GHS	❌

If you need to offer both USD and local currency pricing for the same product, create two separate plans and direct customers to the one that matches their currency.

Free Trials

You can offer a trial period measured in calendar days. When a customer subscribes to a plan with a free trial, their payment profile is activated immediately, but their first automated billing prompt will not trigger until the trial days lapse.

For Card Subscriptions: The card is tokenized, and a background authorization charge occurs without pulling funds.
For Mobile Money Subscriptions: The customer approves the initial mandate signup prompt on their phone screen. Their wallet is marked as authorized, but zero funds are deducted until the trial period ends.

How It Works

When a customer subscribes to a plan with a trial:

They go through the normal enrolment flow
Their card or mobile money wallet is authorised but not charged
The trial runs for the number of days you set
On the trial end date, the first billing cycle begins and the customer is charged

If a customer cancels before the trial ends, they are not charged.

Setting Up a Trial

Add a trialDays field when creating your plan:

{
  "title": "Pro Plan",
  "frequency": "MONTHLY",
  "trialDays": 14,
  "pricingOptions": [
    { "amount": 5000, "currency": "NGN" },
    { "amount": 10, "currency": "GHS" }
  ]
}

Webhook Events During a Trial

Spotflow sends the following events during a trial period:

Event	When it fires
`subscription_trial_started`	When a customer successfully enrols in a trial
`subscription_trial_ending`	3 days before the trial ends
`subscription_trial_ended`	When the trial period closes and billing begins
`payment_successful`	When the first charge after trial is collected

Listen for subscription_trial_ending to send customers a reminder before they are charged. This reduces disputes and unexpected cancellations.

Discounts

Discounts let you reduce the price of a plan for a customer, either for a fixed number of billing cycles or permanently. Instead of making a trial completely free, you can specify an introductory price list (pricingList) that applies only during the trial window. For example, you can configure a plan that normally costs 5,000 NGN/month to charge just 1,000 NGN for the first 14 days before rolling over to the full amount. You can apply them as a flat amount or a percentage.

Types of Discounts

Type	How it works
Percentage	Reduces the plan price by a percentage (e.g. 20% off)
Flat amount	Reduces the plan price by a fixed value (e.g. ₦1,000 off)

Duration Options

Option	What it means
`once`	Applied to the first billing cycle only
`repeating`	Applied for a set number of billing cycles
`forever`	Applied to every billing cycle for the life of the subscription

Applying a Discount

Pass the discount details when creating or updating a subscription:

{
  "planId": "961ca3d6-0505-4bc5-8dd3-fc160ac4afc9",
  "currency": "NGN",
  "customer": {
    "email": "customer@email.com"
  },
  "discount": {
    "type": "percentage",
    "value": 20,
    "duration": "repeating",
    "durationInMonths": 3
  }
}

This gives the customer 20% off for their first 3 billing cycles.

Flat Amount Discount Example

{
  "discount": {
    "type": "flat",
    "value": 1000,
    "currency": "NGN",
    "duration": "once"
  }
}

For flat amount discounts, the currency field must match the currency of the plan pricing option being used. A flat NGN discount cannot be applied to a GHS pricing option.

Trials and Discounts With Mobile Money

Free trials and discounts work with mobile money subscriptions in the same way they work with card subscriptions. For trials: When a customer enrols via mobile money, the mandate is approved during the trial period but no charge is made until the trial ends. The first debit happens automatically when the trial period closes. For discounts: The discounted amount is what gets charged to the customer’s mobile money wallet on each applicable billing cycle. No extra configuration is needed.

The same webhook events apply for mobile money trial and discount subscriptions. See Mobile Money Subscriptions for the full list of mandate and subscription events.

Combining Trials and Discounts

You can apply both a trial and a discount to the same plan. In this case:

The customer completes enrolment without being charged
The trial runs for the duration you set
When billing begins, the discount is applied to the first charge (or all charges, depending on your discount duration)

{
  "planId": "961ca3d6-0505-4bc5-8dd3-fc160ac4afc9",
  "currency": "NGN",
  "customer": {
    "email": "customer@email.com"
  },
  "discount": {
    "type": "percentage",
    "value": 50,
    "duration": "once"
  }
}

If the plan has trialDays: 7, the customer gets 7 days free, then pays 50% of the plan price on their first billing cycle, then the full price from the second cycle onwards.

API Reference: Creating a Plan with a Free Trial

To attach a trial or discount to a plan, include the trial object in your POST /api/v1/plans request body.

Trial Object Parameters

trial

object

Configuration object for the promotional introductory state.

Show properties

periodInDays

integer

required

The duration of the trial window in calendar days (e.g. 7 or 14).

pricingList

array

The price to charge during the trial period. To make the trial 100% free, set the amount to 0. If omitted, the trial defaults to free.

Show properties

amount

number

required

The promotional price during the trial window.

currency

string

required

The 3-letter ISO currency code.

Code Example

curl --request POST \
  --url https://api.spotflow.one/api/v1/plans \
  --header 'Authorization: Bearer sk_test_xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Pro Tier - Regional",
    "frequency": "monthly",
    "internalReference": "PLAN-PRO-REG-01",
    "pricingOptions": [
      { "amount": 5000, "currency": "NGN" },
      { "amount": 50, "currency": "GHS" }
    ],
    "trial": {
      "periodInDays": 7,
      "pricingList": [
        { "amount": 0, "currency": "NGN" },
        { "amount": 0, "currency": "GHS" }
      ]
    }
  }'

Best Practices

Create separate plans for USD and local currencies. This keeps your pricing clean and avoids configuration errors.
Set a trial only when you intend to convert. Trials without a retention strategy lead to high churn at the end of the free period.
Use repeating discounts for introductory pricing. It is more predictable than forever and easier to communicate to customers.
Always communicate discount end dates. Customers who are surprised by a price increase after a discount ends are more likely to cancel.
Test trial and discount flows in test mode before going live to make sure your system handles the transitions correctly.
For Mobile Money Trials: Customers will still receive a phone prompt to authorise the mandate even on a free trial. Tell them clearly on your checkout page that they will not be charged today, but approving the prompt is required to start the trial.
Notify before the first charge: Spotflow will trigger the charge automatically when the trial ends. Send an in-app or email notification 24 hours before so your customer expects the prompt and has their wallet funded.

Need Help?

Reach out to the Spotflow team at support@spotflow.one

Getting Started

How We Operate

Features

Expert Desk

Plan Trials, Discounts & Currency Rules

Currency Rules

USD Plans Are Standalone

Local Currencies Can Be Combined

Summary

Free Trials

How It Works

Setting Up a Trial

Webhook Events During a Trial

Discounts

Types of Discounts

Duration Options

Applying a Discount

Flat Amount Discount Example

Trials and Discounts With Mobile Money

Combining Trials and Discounts

API Reference: Creating a Plan with a Free Trial

Trial Object Parameters

Code Example

Best Practices

Need Help?

Getting Started

How We Operate

Features

Expert Desk

Documentation Index

​Currency Rules

​USD Plans Are Standalone

​Local Currencies Can Be Combined

​Summary

​Free Trials

​How It Works

​Setting Up a Trial

​Webhook Events During a Trial

​Discounts

​Types of Discounts

​Duration Options

​Applying a Discount

​Flat Amount Discount Example

​Trials and Discounts With Mobile Money

​Combining Trials and Discounts

​API Reference: Creating a Plan with a Free Trial

​Trial Object Parameters

​Code Example

​Best Practices

​Need Help?

Currency Rules

USD Plans Are Standalone

Local Currencies Can Be Combined

Summary

Free Trials

How It Works

Setting Up a Trial

Webhook Events During a Trial

Discounts

Types of Discounts

Duration Options

Applying a Discount

Flat Amount Discount Example

Trials and Discounts With Mobile Money

Combining Trials and Discounts

API Reference: Creating a Plan with a Free Trial

Trial Object Parameters

Code Example

Best Practices

Need Help?