Recurring PaymentsPlansCreate Plan

Create a Plan

A plan defines how much a customer is charged, how often billing happens, and optionally how many successful invoices the subscription can have.

Endpoint

POST https://backendapi.sayswitchgroup.com/api/v1/plan

Request

curl --request POST \
  --url https://backendapi.sayswitchgroup.com/api/v1/plan \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Email Monthly",
    "description": "Monthly access to the email service",
    "amount": 15000,
    "currency": "NGN",
    "interval": "monthly",
    "invoice_limit": 12
  }'

Request Fields

FieldTypeRequiredDescription
namestringYesPlan name, up to 120 characters.
descriptionstringNoPlan description, up to 1,000 characters.
amountnumber or numeric stringYesAmount to charge in major NGN units. For example, 15000 charges NGN 15,000.00. Minimum value is 1; values are stored to two decimal places.
currencystringNoCurrency code. Only NGN is currently supported; it defaults to NGN.
intervalstringYesBilling frequency: daily, weekly, monthly, quarterly, biannually, or annually.
invoice_limitinteger or nullNoMaximum number of successful billing invoices. Must be at least 1 when provided.

If invoice_limit is omitted or null, the subscription continues until it is cancelled. If it is 12, the subscription becomes completed after 12 successful billing invoices.

Response

A new plan returns HTTP 201.

{
  "status": true,
  "message": "Plan created.",
  "data": {
    "id": 42,
    "business_id": 169,
    "plan_code": "PLN_4m8q1v2x7b9n3k6p5r0s",
    "name": "Email Monthly",
    "description": "Monthly access to the email service",
    "amount": "15000.00",
    "currency": "NGN",
    "interval": "monthly",
    "invoice_limit": 12,
    "status": "active",
    "domain": "test",
    "created_at": "2026-09-25T10:30:00.000000Z",
    "updated_at": "2026-09-25T10:30:00.000000Z"
  }
}

Save data.plan_code; you need it when initializing a subscription.

Validation Error

Validation errors return HTTP 422.

{
  "status": false,
  "message": "Invalid plan details.",
  "errors": {
    "interval": [
      "The selected interval is invalid."
    ]
  }
}