Create Billing Plan

Creates a new billing plan. Billing plans are the basis of all billing agreements with automatic charges.

Relationship to other components

Subscription: The underlying link between a merchant and a stored payment method. Created via the Initialize Payment Session /cit endpoint by sending the Subscription object.

Billing Plan: Defines recurring details like price, interval, and retry policy. Used only when ePay manages the billing schedule automatically.

Billing Agreement: Connects a Subscription to a Billing Plan. Tracks scheduled processing and charge lifecycle.

Billing Agreement Charge: Represents a scheduled billing event created from an agreement. Each charge can have multiple transaction attempts and a completion deadline.

Transaction: The base payment model used for all processing. Charges and transactions are linked to maintain attempt history.

Creates a new billing plan. Billing plans are the basis of all billing agreements with automatic charges. :::info Relationship to other components - Subscription: The underlying link between a merchant and a stored payment method. Created via the [Initialize Payment Session <code>/cit</code>](/api/initialize-payment-session) endpoint by sending the Subscription object. - Billing Plan: Defines recurring details like price, interval, and retry policy. Used only when ePay manages the billing schedule automatically. - Billing Agreement: Connects a Subscription to a Billing Plan. Tracks scheduled processing and charge lifecycle. - Billing Agreement Charge: Represents a scheduled billing event created from an agreement. Each charge can have multiple transaction attempts and a completion deadline. - Transaction: The base payment model used for all processing. Charges and transactions are linked to maintain attempt history. :::

Authorization

BearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Create billing plan data

TypeScript Definitions

Use the request body type in TypeScript.

namestring

Required

Human-readable name of the billing plan.

Length:

1 <= length <= 256

amountinteger

Required

Charge amount (in the smallest currency unit, e.g. cents).

Range:

1 <= value

currencystring

Required

ISO 4217 alpha-3 currency code (e.g., USD, EUR).

Match:

^[A-Z]{3}$

Length:

3 <= length <= 3

The InstantCapture mode to use for all charges related to the plan.

OFF indicates that the payment should not be captured instantly (Default).

VOID indicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided.

NO_VOID indicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)

The `InstantCapture` mode to use for all charges related to the plan.<ul><li> `OFF` indicates that the payment should not be captured instantly (Default).</li><li> `VOID` indicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided.</li><li> `NO_VOID` indicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)</li></ul>

Default:

"OFF"

Possible values:

"OFF""VOID""NO_VOID"

Example:

"OFF"

stringstring

The InstantCapture mode to use for all charges related to the plan.

OFF indicates that the payment should not be captured instantly (Default).

VOID indicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided.

NO_VOID indicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)

Default:

"OFF"

Possible values:

"OFF""VOID""NO_VOID"

Example:

"OFF"

nullnull

The InstantCapture mode to use for all charges related to the plan.

OFF indicates that the payment should not be captured instantly (Default).

VOID indicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided.

NO_VOID indicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)

Default:

"OFF"

Possible values:

"OFF""VOID""NO_VOID"

Example:

"OFF"

maxAttemptsinteger

Required

Maximum number of billing attempts before giving up.

Range:

1 <= value <= 31

The frequency between automatic charges. A frequency=2 and period=WEEK means one charge every two weeks.

The frequency between automatic charges. A `frequency=2` and `period=WEEK` means one charge every two weeks.

periodstring

Required

The time unit of the frequency field

Possible values:

"DAY""WEEK""MONTH""YEAR"

Example:

"MONTH"

frequencyinteger

Required

The number of period's between each charge.

Range:

1 <= value <= 31

Example:

1

Response Body

`application/json`

curl -X POST "https://example.com/public/api/v1/subscriptions/billing/plans" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "amount": 1,    "currency": "str",    "maxAttempts": 1,    "interval": {      "period": "MONTH",      "frequency": 1    }  }'

{  "billingPlan": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "instantCapture": "OFF",    "name": "string",    "color": "string",    "emoji": "string",    "amount": 0,    "currency": "str",    "maxAttempts": 0,    "interval": {      "period": "MONTH",      "frequency": 1    },    "createdAt": "2019-08-24T14:15:22Z"  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

{  "errorCode": "VALIDATION_ERROR",  "message": "Input validation errors",  "errors": {    "amount": [      "[required]: Is a required non-nullable field",      "[int]: Must be an integer",      "[min:0]: Must be greater than 0",      "[max:999999999]: Must be less than 999999999"    ]  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

Authorization

Request Body

Response Body

200application/json

400application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`