Create Billing Agreement

Test this endpoint live

Open the same request directly in API Explorer.

Server URL

Creates a new Billing Agreement based on an existing Subscription and a Billing Plan.

A billing agreement represents a scheduled payment relationship between the merchant and the cardholder, managed automatically by ePay. It links a subscription and a plan together, allowing ePay to handle recurring charges according to the plan’s configuration - for example, charging the customer monthly based on the defined price and interval.

Important: Billing agreements is an optional extension of the base subscription and is only necessary if you want ePay to automatically manage recurring or interval-based billing on your behalf.

If you only need to perform unscheduled MIT (Merchant-Initiated Transaction) payments - meaning you trigger the charge manually via the API whenever needed - you do not need to create a billing agreement or billing plan. In that case, use the existing Subscription created through the Initialize Payment Session /cit endpoint, and perform MIT transactions directly.

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.

Authorization

BearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

Create billing agreement data

TypeScript Definitions

Use the request body type in TypeScript.

billingPlanIdstring

Required

Identifier for the associated billing plan.

Format:

uuid

subscriptionIdstring

Required

Identifier for the related subscription. Subscription must be in ACTIVE state.

Format:

uuid

Example:

null

referencestring

Nullable

Optional reference string.

Example:

"agreement-1"

nextChargeAtstring

Nullable

Date of the next scheduled charge. If none is given, the current date and interval from the plan is used to calculate the next charge date.

Format:

date

Example:

"2030-07-29"

Response Body

`application/json`

curl -X POST "https://example.com/public/api/v1/subscriptions/billing/agreements" \  -H "Content-Type: application/json" \  -d '{    "billingPlanId": "13568ff4-f6e3-4ead-8359-ef949748a0cf",    "subscriptionId": null  }'

{  "billingAgreement": {    "id": "019a729e-2d93-7612-9329-8f783f66f834",    "billingPlanId": "019a729e-41c2-7d16-a1e2-fdb15a8146bb",    "subscriptionId": "019a729e-51ed-7426-b7c9-0e212b2d77d4",    "sessionId": "019a729e-660a-7a05-90ad-5160ad0decc5",    "customerId": "user-1",    "nextChargeAt": "2030-08-29T15:51:28.071Z",    "lastChargeAt": "2030-07-29T15:51:28.071Z",    "desiredDate": 30,    "state": "PENDING",    "stateChangedAt": "2030-07-29T15:51:28.071Z",    "reference": "agreement-1",    "createdAt": "2030-07-29T15:51:28.071Z"  }}

{  "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`