# Create Subscription

**Method:** `POST`

**Path:** `/ps/api/v1/public/subscriptions`

**Category:** Subscriptions - Subscriptions

**Authentication:** Required

## Description

Creates a new subscription against an existing plan. The subscription
defines the recurring billing cycle for a customer based on the
selected plan's pricing and frequency.


## Request Body

Content-Type: `application/json`

- `merchant_subscription_reference` (`string`) **required** — **Idempotency Key.** Unique identifier of the merchant subscription reference. Duplicate requests with the same `merchant_subscription_reference` will return the existing subscription instead of creating a new one.
- `plan_id` (`string`) **required** — Unique identifier for the subscription plan.
- `enable_notification` (`boolean`) — Indicates if notifications are enabled.
- `start_date` (`string`) **required** — The ISO 8601 UTC Timestamp when the subscription starts.
- `end_date` (`string`) **required** — The ISO 8601 UTC Timestamp when the subscription expires.
- `customer_id` (`string`) **required** — Unique identifier of the customer in the Pine Labs Online database.
- `allowed_payment_methods` (`string[]`) — The type of payment methods you want to offer customers.
- `integration_mode` (`SEAMLESS | REDIRECT`) **required** — Type of integration.
- `merchant_metadata` (`object`) — Key-value pairs for additional information. Max 10 pairs, 256 chars each.
- `is_tpv_enabled` (`boolean`) — Indicates if Third-Party Validation (TPV) is enabled.
- `bank_account` (`object`) — Bank account details for Third-Party Validation (TPV).
  - `account_number` (`string,null`) — Bank account number.
  - `name` (`string,null`) — Name of Customer.
  - `ifsc` (`string,null`) — IFSC code of the bank account.

- `callback_url` (`string`) — URL to redirect customers to specific success or failure pages.
- `failure_callback_url` (`string`) — URL specifically used to redirect customers to a failure page.

### Example Request

```json
{
  "merchant_subscription_reference": "f5d77ef9-fa11-4f58-a9f4-543e4a7022c5",
  "plan_id": "v1-pla-250612061639-aa-666Zge",
  "enable_notification": true,
  "start_date": "2025-06-12T06:22:21Z",
  "end_date": "2025-06-21T17:32:28Z",
  "customer_id": "cust-v1-250519171901-aa-dPF6mg",
  "allowed_payment_methods": [
    "UPI"
  ],
  "integration_mode": "REDIRECT",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "is_tpv_enabled": false,
  "bank_account": {
    "account_number": "12345678912345",
    "name": "Kevin Bob",
    "ifsc": "HDFC0001234"
  },
  "callback_url": "www.google.com",
  "failure_callback_url": "www.example.com/failure"
}
```

## Responses

- `201` — Subscription created successfully.
- `404` — 
- `422` — Unprocessable Entity — validation failed or duplicate request.
- `500` — 

---

Reference: https://localhost:3000/api/subscriptions-subscriptions/create-subscription