Create Plans

Create a plan to define subscription offerings for your customers. Plans can be configured in two pricing modes:

Local Currency Mode (Default) - Fixed pricing in a single African currency
Settlement Currency Mode - Set prices in your settlement currency (USD, EUR, GBP) while customers pay in their local currency at the current exchange rate

Plan Details

Field	Data type	Required	Description
name	string	Yes	Name of plan
description	string	Yes	A short info describing the plan
interval	enum	Yes	Billing frequency. Valid values: `daily, weekly, monthly, quarterly, biannually, annually`
amount	integer	Yes	Plan amount. Use `amountCurrency` to specify the currency interpretation
localCurrency	string	Yes	The currency in which the customer will be charged. ISO 4217 currency code (e.g., `NGN, KES, ZAR, GHS, XOF, USD`)
amountCurrency	enum	No	Specifies how to interpret amount. Values: `local` (default), `settlement.` Use `settlement` when entering amount in your settlement currency
settlementCurrency	string	No	Your settlement currency (e.g., `USD, EUR, GBP, CAD`). If not provided, automatically detected from your business settings

Currency Values
Supported Customer Collection Currencies (localCurrency)

Currency Code	Currency Name	Country
NGN	Nigerian Naira	Nigeria
KES	Kenyan Shilling	Kenya
ZAR	South African Rand	South Africa
GHS	Ghanaian Cedi	Ghana
XOF	West African Franc	Ivory Coast
USD	US Dollar	General

Supported Settlement Currencies (settlementCurrency)

Currency Code	Currency Name
USD	US Dollar
EUR	Euro
GBP	British Pound
CAD	Canadian Dollar

After collecting the necessary plan details. Make a POST request to our plans endpoint.

Note : Before making a post request, the secret key should be specified in the header.

-H "x-api-key: your_secret_key".

{{host}}/v1/plans

You can make API calls using this sample request. once all parameters are meet you would also get the response below;

{
    "name": "Basic Plan",
    "description": "Access to basic features",
    "interval": "monthly",
    "amount": 5000,
    "localCurrency": "NGN"
}

{
    "status": true,
    "message": "Success",
    "code": 201,
    "data": {
        "name": "Basic Plan",
        "description": "Access to basic features",
        "interval": "monthly",
        "amount": "5000.00",
        "integration": {
            "id": "7783fd36-5d77-4f67-8c52-c69c27721790",
            "reference": "ACCT_433003k7cm924vm",
            "splitCode": null,
            "isActive": true,
            "isDefault": true,
            "comments": {},
            "createdAt": "2023-10-20T12:00:23.447Z",
            "updatedAt": "2023-10-25T10:25:23.477Z",
            "version": 3,
            "region": {
                "id": "faa05b6c-1851-4174-bbdf-67e15aa86817",
                "name": "Nigeria",
                "code": "NGA",
                "alpha2Code": "NG",
                "flagSvg": "https://flagcdn.com/ng.svg",
                "flagPng": "https://flagcdn.com/w320/ng.png",
                "currency": {
                    "code": "NGN",
                    "name": "Nigerian naira",
                    "symbol": "₦"
                },
                "demonym": "Nigerian",
                "dialingCode": "+234",
                "isActive": true,
                "isDefault": false,
                "isSettlement": false,
                "isCollection": true,
                "createdAt": "2023-09-11T21:52:43.997Z",
                "updatedAt": "2023-09-11T21:52:43.997Z",
                "version": 1
            }
        },
        "code": "PLN_7263269_dIz_JeiVoKjr6Dm",
        "deletedAt": null,
        "id": "e2acfea4-2e5d-4bae-8581-f856beebc341",
        "sendSms": false,
        "sendInvoices": false,
        "limit": "0.00",
        "hostedPage": false,
        "isActive": true,
        "createdAt": "2024-06-21T15:41:21.664Z",
        "updatedAt": "2024-06-21T15:41:21.664Z",
        "version": 1
    }
}

{
    "name": "Premium Plan",
    "description": "Full access to all features",
    "interval": "monthly",
    "amount": 100,
    "localCurrency": "NGN",
    "amountCurrency": "settlement",
    "settlementCurrency": "USD"
}

{
    "status": true,
    "message": "Success",
    "code": 201,
    "data": {
        "name": "Premium Plan",
    		"description": "Full access to all features",
    		"interval": "monthly",
   			"amount": 0,
    		"settlementAmount": 100,
    		"settlementCurrency": "USD",
    		"localCurrency": "NGN",
        "integration": {
            "id": "7783fd36-5d77-4f67-8c52-c69c27721790",
            "reference": "ACCT_433003k7cm924vm",
            "splitCode": null,
            "isActive": true,
            "isDefault": true,
            "comments": {},
            "createdAt": "2023-10-20T12:00:23.447Z",
            "updatedAt": "2023-10-25T10:25:23.477Z",
            "version": 3,
            "region": {
                "id": "faa05b6c-1851-4174-bbdf-67e15aa86817",
                "name": "Nigeria",
                "code": "NGA",
                "alpha2Code": "NG",
                "flagSvg": "https://flagcdn.com/ng.svg",
                "flagPng": "https://flagcdn.com/w320/ng.png",
                "currency": {
                    "code": "NGN",
                    "name": "Nigerian naira",
                    "symbol": "₦"
                },
                "demonym": "Nigerian",
                "dialingCode": "+234",
                "isActive": true,
                "isDefault": false,
                "isSettlement": false,
                "isCollection": true,
                "createdAt": "2023-09-11T21:52:43.997Z",
                "updatedAt": "2023-09-11T21:52:43.997Z",
                "version": 1
            }
        },
        "code": "PLN_7263269_dIz_JeiVoKjr6Dm",
        "deletedAt": null,
        "id": "e2acfea4-2e5d-4bae-8581-f856beebc341",
        "sendSms": false,
        "sendInvoices": false,
        "limit": "0.00",
        "hostedPage": false,
        "isActive": true,
        "createdAt": "2024-06-21T15:41:21.664Z",
        "updatedAt": "2024-06-21T15:41:21.664Z",
        "version": 1
    }
}

Error Responses

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request body
422	UNPROCESSABLE_ENTITY	Business has no active integration for the specified currency
422	UNPROCESSABLE_ENTITY	No FX rate found for settlement currency conversion (settlement mode only)