Skip to main content
POST
/
plans
cURL
curl --request POST \
  --url https://api.spotflow.co/api/v1/plans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Standard Monthly Plan",
  "cycleCount": "3",
  "retrial": "3",
  "endDate": "2026-10-29",
  "internalReference": "PLAN-STD-001",
  "pricingOptions": [
    {
      "amount": 123,
      "currency": "NGN"
    }
  ],
  "trial": {
    "periodInDays": 0,
    "pricingList": [
      {
        "amount": 123,
        "currency": "NGN"
      }
    ]
  }
}
'
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "string",
    "amount": 123,
    "currency": "NGN",
    "createdAt": "2023-11-07T05:31:56Z",
    "internalReference": "string",
    "regions": [
      "<string>"
    ],
    "subscribers": 123,
    "subscriptions": 123,
    "trial": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "periodInDays": 123,
      "pricingList": [
        {
          "amount": 123,
          "currency": "NGN"
        }
      ]
    },
    "pricingOptions": [
      {
        "amount": 123,
        "currency": "NGN"
      }
    ]
  }
]

​
Mobile Money

When it is a mobile_moneypayment and a planId is included, Spotflow will automatically send a mandate approval request to the customer’s phone. The subscription will only activate once the mandate is approved.See the full guide on Mobile Money Subscriptions.
To learn on payment states, go to this page

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
title
string

Name or title of the plan

Example:

"Standard Monthly Plan"

​
cycleCount
integer

Maximum billing cycles before the plan completes

Example:

"3"

​
retrial
integer

Note that retrial only applies to card subscriptions, not mobile money. Retry count for failed card payments.

Example:

"3"

​
endDate
integer

The date all subscription cycles end

Example:

"2026-10-29"

​
frequency
enum<string>

Billing frequency for the plan

Available options:
DAILY,
WEEKLY,
MONTHLY,
QUARTERLY,
ANNUAL
​
internalReference
string

Internal reference code for the plan

Example:

"PLAN-STD-001"

​
pricingOptions
object[]

Pricing options for the plan

​
trial
object

Response

A JSON array of subscription objects.

​
id
string<uuid>
required

Unique identifier of the subscription plan (UUID).

​
title
string
required

The title or name of the subscription plan.

Example:

"string"

​
frequency
enum<string>
required

Billing frequency for the subscription plan.

Available options:
DAILY,
WEEKLY,
MONTHLY,
QUARTERLY,
BIANNUAL,
ANNUAL
​
amount
number
required

The cost amount for the subscription plan.

​
currency
string
required

The currency of the subscription plan (e.g., NGN, USD).

Example:

"NGN"

​
status
enum<string>
required

The current status of the subscription plan.

Available options:
ACTIVE,
INACTIVE,
ARCHIVED
​
createdAt
string<date-time>
required

Date and time when the plan was created.

​
internalReference
string

Internal reference code or identifier for the plan.

Example:

"string"

​
regions
string[]

List of regions where this plan is available.

​
subscribers
integer

Total number of active subscribers under this plan.

​
subscriptions
integer

Total number of subscriptions created for this plan.

​
trial
object

Details about the trial period associated with this plan.

​
pricingOptions
object[]

Different pricing options available for the plan.