---
title: "Create a plan"
method: POST
path: "/billing/plans"
---

# Create a plan

`POST /billing/plans`

## Request

- Base URL: `https://api-sandbox.ezypay.com/v2`
- URL: `https://api-sandbox.ezypay.com/v2/billing/plans`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://identity-sandbox.ezypay.com/token`

The create payment plan can be created using the create plan API. A plan Id is mandatory before a customer payment subscription can be created.

A plan can be created with different billing cycles and pricing tiers to accommodate the merchants products and services. 

A plan is a template containing a set of payment setting (amount and frequency) which can be standardise to customer payment subscription being created.

## Headers

- `merchant` string, required

## Request body

- object
  - `name` string, required: Plan name. Max of 50 characters.
  - `memo` string: Brief memo of the plan. Max of 50 characters.
  - `accountingCode` string: Specify an accounting code to categorise revenue collected from the plan's subscription payment. Max of 50 characters.
  - `amount` object: The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.
    - `currency` string, required: Three letter ISO 4217 currency code for the amount.
    - `value` number, double, required: The value of the amount. Must be positive value greater than zero.
    - `type` string: The type of the amount value. Supported values are: `percentage`, `fixed_amount`
  - `tax` object: The tax rate applied to the plan's amount. If left blank, uses the tax rate specified in the merchant settings by default.
    - `rate` number, double: Rate of the specified tax in percentage. Supported values are from 0 to 99.99.
  - `setupPayments` object[]: Setup payment settings.
    - `amount` object: Setup payment amount.
      - `currency` string, required: Three letter ISO 4217 currency code for the amount.
      - `value` number, double, required: The value of the amount. Must be positive value greater than zero.
      - `type` string: The type of the amount value. Supported values are: `percentage`, `fixed_amount`
    - `tax` object: The tax that is applicable to the setup payment, if the amount is taxable.
      - `rate` number, double: Rate of the specified tax in percentage. Supported values are from 0 to 99.99.
    - `description` string: Description. Max of 255 characters.
    - `accountingCode` string: Specify an accounting code to categorise revenue collected from the setup payment. Max of 50 characters.
  - `intervalUnit` string: Specifies frequency of billing. Valid values are `day`, `week` or `month`. If no value is provided, the default value is `week`.
  - `interval` integer: Number to be specified as interval to manipulate billing frequency. For example `interval=2` and `intervalUnit=week` would means billing every 2 weeks. If no value is provided, the default value is 1.
  - `billingStart` string: Specifies the default day the billing schedule starts for customers subscribed to the plan. Supported values are: `immediate` - Default value. Subscriptions will start on the same day. `day_of_week` - Subscriptions will start on a specific day as defined in billingStartValue. `day_of_month` - Subscriptions will start on specific day in the month as defined in billingStartValue.
  - `billingEnd` string: Specifies the rules to automate when a subscription ends. Supported values are: `ongoing` - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). `amount_collected` - Subscriptions will end when a specified amount is collected as defined in `billingEndValue`. `billing_cycles` - Subscriptions will end after a specified number of billing cycles as defined in `billingEndValue`. `end_date` - Subscriptions will end on specific date. Specify this date when you create a subscription in `billingEndValue`.
  - `firstBilling` string: Specifies the rules to auto-calculate the billing charges for the first scheduled billing. Supported values are: `full_amount` - Default value. The first billing will charge the full amount on the subscription as defined in the plan's amount. `prorate` - Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.
  - `metadata` object: Store additional data about the customer object using key/value pairs format.

## Response `200`

200

- object
  - `id` string
  - `status` string
  - `name` string
  - `memo` unknown
  - `accountingCode` string
  - `amount` object
    - `currency` string
    - `value` integer
    - `type` unknown
  - `tax` object
    - `rate` integer
  - `setupPayments` unknown
  - `intervalUnit` string
  - `interval` integer
  - `billingStart` string
  - `billingStartValue` string
  - `billingEnd` string
  - `billingEndValue` unknown
  - `firstBilling` string
  - `recurringBillingDay` unknown
  - `failedPaymentHandling` object
    - `initialAction` string
    - `autoRetry` boolean
    - `retryInDays` integer
    - `maximumFailedAttempts` integer
  - `metadata` unknown
  - `createdOn` string

## Other responses

- `400`: 400

## Changes

- **2026-11-03** `924be4030f56`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ezypay/apis/vault/changes/billing/plans/post.md)

---

[API](https://skmtc.dev/ezypay/apis/vault.md) - [All operations](https://skmtc.dev/ezypay/apis/vault/llms.txt) - [OpenAPI document](https://skmtc.dev/ezypay/apis/vault/revisions/924be4030f56?raw)