Create Subscription

---

description: >- The Create Subscription API allows partners to create recurring payments using a card or bank account token.

Create Subscription

POST https://<PayEngine-host>/api/merchant/:merchantId/recurring-payments/subscriptions

Path Parameters

Name	Type	Description
merchant_id*	string	Merchant ID

Request Body

Name	Type	Description
merchant_id*	string	Merchant ID
data.plan_id*	string	Plan ID (created using Create Plan API)
data.description	string	Plan Description
data.start_date*	date	Start of the recurring payment. First transaction will be executed on this date.
data.card_token	string	Card token generated by PayEngine secure field API Required for Credit card subscription. Note: Either data.card_token or data.bank_account_token is required
data.bank_account_token	string	Bank Account Token. Required for ACH subscription. Note: Either data.card_token or data.bank_account_token is required

200

Field Definitions

Field Name	Type	Description	Required?
merchant_id	string	Merchant ID	Required
data.subscription_id	string	PayEngine system ID for the subscription	Required
data.subscription_status	string	ACTIVE | PENDING | CANCELLED | EXPIRED| BLOCKED	Required
data.plan_id	string	Recurring Payment Plan ID	Required
data.name	string	Recurring Payment Plan Name
data.amount	string	Recurring Payment Plan Amount
data.currency_code	string	Recurring Payment Plan Currency code ee.g. USD
data.billing_period	string	Recurring Payment Plan Billing Period Accepted values are DAILY | WEEKLY | MONTHLY | QUARTERLY| ANNUAL
data.duration	string	Recurring Payment Plan Duration. Specify the number of recurring payments that will be processed in total
data.duration_unit	string	Recurring Payment Plan Duration Unit. Accepted values are DAYS | WEEKS | MONTHS | YEARS
data.created_at	string	Subcription Creation Date & Time
data.billing_start_date	string	Subscription Start date. First transaction will be executed on this date.
data.description	string	Subscription description

Subscription Status

• PENDING: The subscription is not yet created.

• ACTIVE: The subscription is currently active.

• BLOCKED: The subscription is currently paused.

• CANCELLED: The subscription has been cancelled.

• EXPIRED: The subscription has expired.

Sample Request Body

{
    "merchant_id": "1cc7b594-b80f-4227-a0fa-299c4c6ce8ab",
    "data": {  
        "plan_id": "8049a73c-2ac4-431c-b9a0-2e60acd937eb",
        "start_date": "2023-09-10T00:00:00.000Z",  
        "card_token": "card_sandbox_xxxx",
        "description":"test subscription"
    }
}

Sample Response Body

{
    "merchant_id": "83710aeb-aa3b-4b58-ab23-6c585bf4b9ba",
    "data": {
        "plan_id": "ac3467a3-f583-409a-a3ca-573eb09df933",
        "subscription_id": "67b55cfc-a6b5-435f-8195-6f176bb48a36",
        "name": "Test Plan",
        "amount": "100.00",
        "currency_code": "USD",
        "billing_period": "MONTHLY",
        "duration": "2",
        "duration_unit": "MONTHS",
        "created_at": "2025-05-10T01:57:47.043Z",
        "billing_start_date": "2025-05-09T00:00:00.000Z",
        "subscription_status": "ACTIVE",
        "description":"test subscription"
    }
}

Webhook event: SUBSCRIPTION_CREATED

Webhook Payload Example

{
  "event_uid": "494a7be1a88d3a5516f5e949c9c0d6c9",
  "event": "SUBSCRIPTION_CREATED",
  "data": {
    "name": "Test Plan",
    "amount": "100.00",
    "plan_id": "ac3467a3-f583-409a-a3ca-573eb09df933",
    "duration": "2",
    "created_ct": "2025-05-10T02:10:14.419Z",
    "account_id": "e0e9a31e-1d9e-4612-ae1f-209f549ffd71",
    "merchant_id": "83710aeb-aa3b-4b58-ab23-6c585bf4b9ba",
    "currency_code": "USD",
    "duration_unit": "MONTHS",
    "billing_period": "MONTHLY",
    "subscription_id": "ea20d802-2f0b-4cc5-aeb8-5a6c927c8c16",
    "billing_start_date": "2025-05-09T00:00:00.000Z",
    "subscription_status": "ACTIVE",
    "description":"test subscription"
  }
}