> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kwikpaisa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Subscription

***

## icon: calendar-plus

# Create Subscription

Use the Create Subscription API to create a subscription for an existing customer using a previously created subscription plan.

The API creates a subscription mandate in KwikPaisa Neo Bank and returns a unique `mandate_id`. The subscription is initially created with a `pending` status.

Once created, the subscription can be used to initiate the customer authorization process through the subscription checkout flow.

This API supports:

* UPI
* Card
* Net Banking

***

## Endpoint

```text theme={null}
POST /api/v3/pg/subscription/create
```

***

#### To view all available base URLs and environments, refer to:

➡️ [API Resources](https://docs.kwikpaisa.com/guide/quick-start/api-resources.md)

#### This endpoint requires standard KwikPaisa Neo Bank authentication headers.

Refer to:

➡️ [Headers](https://docs.kwikpaisa.com/guide/authentication/headers.md)\
➡️ [Signature Generation](https://docs.kwikpaisa.com/guide/authentication/signature.md)\
➡️ [Timestamp Validation](https://docs.kwikpaisa.com/guide/authentication/timestamp.md)

***

## Request Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `plan_id` | String | Yes | Unique KwikPaisa Neo Bank plan ID |
| `customer_id` | String | Yes | Unique KwikPaisa Neo Bank customer ID |
| `type` | String | Yes | Payment method type, such as `upi`, `card`, or `netbanking` |
| `reference_id` | String/Integer | Yes | Unique merchant reference ID for the subscription |
| `amount_type` | String | No | Subscription amount type: `fixed` or `variable` |
| `quantity` | Integer | No | Subscription plan quantity |
| `total_cycles` | Integer | No | Total number of billing cycles |
| `start_date` | Date | No | Requested subscription start date |
| `end_date` | Date | No | Requested subscription end date |
| `start_at` | Integer/Null | No | Subscription start timestamp; provider-generated during authorization |
| `authorization_expires_at` | Integer/Null | No | Authorization expiry timestamp; provider-generated during authorization |
| `metadata` | Object | No | Additional merchant-defined subscription information |

### Metadata Parameters

The `metadata` object supports merchant-defined information associated with the subscription.

| Parameter | Type | Description |
| :- | :- | :- |
| `metadata.purpose` | String | Purpose of the subscription |
| `metadata.package` | String | Merchant-defined package or plan name |
| `metadata.addons` | Array | Additional items or services associated with the subscription |
| `metadata.addons[].item.name` | String | Add-on item name |
| `metadata.addons[].item.amount` | Integer/Decimal | Add-on amount |
| `metadata.addons[].item.currency` | String | Add-on currency code |

***

## Example Request Body

```text theme={null}
{
  "plan_id": "plan_7ec2fc01-2361-45ea-945b-936d88251844",
  "customer_id": "cust_d71f980e-4b3f-4e9b-9d14-7cfa92fd9134",
  "type": "upi",
  "reference_id": 1794458812,
  "amount_type": "fixed",
  "quantity": 1,
  "total_cycles": 12,
  "start_date": null,
  "end_date": null,
  "start_at": null,
  "authorization_expires_at": null,
  "metadata": {
    "purpose": "subscription",
    "package": "gold",
    "addons": [
      {
        "item": {
          "name": "Delivery charges",
          "amount": 3000,
          "currency": "INR"
        }
      }
    ]
  }
}
```

***

## Example cURL Request

```text theme={null}
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/pg/subscription/create \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--data '{
  "plan_id": "plan_7ec2fc01-2361-45ea-945b-936d88251844",
  "customer_id": "cust_d71f980e-4b3f-4e9b-9d14-7cfa92fd9134",
  "type": "upi",
  "reference_id": 1794458812,
  "amount_type": "fixed",
  "quantity": 1,
  "total_cycles": 12,
  "start_date": null,
  "end_date": null,
  "start_at": null,
  "authorization_expires_at": null,
  "metadata": {
    "purpose": "subscription",
    "package": "gold",
    "addons": [
      {
        "item": {
          "name": "Delivery charges",
          "amount": 3000,
          "currency": "INR"
        }
      }
    ]
  }
}'
```

***

## Signature Generation

Generate the request signature using the recursively sorted request payload.

```text theme={null}
$timestamp = time();

$sortPayload = function ($data) use (&$sortPayload) {
    if (!is_array($data)) {
        return $data;
    }

    ksort($data);

    foreach ($data as $key => $value) {
        $data[$key] = $sortPayload($value);
    }

    return $data;
};

$sortedPayload = $sortPayload($payload);
$jsonPayload = json_encode($sortedPayload, JSON_UNESCAPED_SLASHES);

$signature = hash_hmac(
    'sha256',
    $jsonPayload . $timestamp,
    $secretKey
);
```

***

## Example Success Response

```text theme={null}
{
  "status": true,
  "message": "Mandate created successfully.",
  "data": {
    "mandate_id": "mand_8dceeb5f-986b-4cb9-ade2-475f25df1ee5",
    "customer_id": "cust_d71f980e-4b3f-4e9b-9d14-7cfa92fd9134",
    "merchant_id": "pg_b68645dd-634d-49f9-89e4-afe856b8cabb",
    "plan_id": "plan_7ec2fc01-2361-45ea-945b-936d88251844",
    "type": "upi",
    "reference_id": 1794458812,
    "amount_type": "fixed",
    "amount": "699.00",
    "currency": "INR",
    "frequency": "monthly",
    "interval_count": 1,
    "quantity": 1,
    "total_cycles": 12,
    "start_date": null,
    "end_date": null,
    "remaining_count": 12,
    "metadata": {
      "purpose": "subscription",
      "package": "gold",
      "addons": [
        {
          "item": {
            "name": "Delivery charges",
            "amount": 3000,
            "currency": "INR"
          }
        }
      ]
    },
    "status": "pending",
    "updated_at": "2026-11-12T04:46:53.000000Z",
    "created_at": "2026-11-12T04:46:53.000000Z"
  }
}
```

***

## Response Parameters

| Parameter | Description |
| :- | :- |
| `status` | Indicates whether the subscription was created successfully |
| `message` | API response message |
| `data.mandate_id` | Unique KwikPaisa Neo Bank generated subscription/mandate ID |
| `data.customer_id` | Associated customer ID |
| `data.merchant_id` | Merchant payment gateway ID |
| `data.plan_id` | Associated subscription plan ID |
| `data.type` | Subscription payment method |
| `data.reference_id` | Merchant-provided subscription reference |
| `data.amount_type` | Subscription amount type |
| `data.amount` | Subscription amount inherited from the plan |
| `data.currency` | Subscription currency |
| `data.frequency` | Billing frequency inherited from the plan |
| `data.interval_count` | Billing interval count |
| `data.quantity` | Subscription plan quantity |
| `data.total_cycles` | Total billing cycles |
| `data.start_date` | Requested subscription start date |
| `data.end_date` | Requested subscription end date |
| `data.remaining_count` | Remaining billing cycles |
| `data.metadata` | Merchant-defined subscription information |
| `data.status` | Current subscription status |
| `data.created_at` | Subscription creation timestamp |
| `data.updated_at` | Subscription last update timestamp |

***

## Subscription Status

A newly created subscription is assigned the following initial status:

| Status | Description |
| :- | :- |
| `pending` | Subscription has been created and is awaiting customer authorization |

***

## Important Notes

* Create a customer before creating a subscription.
* Create a plan before creating a subscription.
* The supplied `customer_id` and `plan_id` must belong to the authenticated merchant account.
* The `reference_id` should be unique for each subscription under the merchant account.
* The subscription amount, currency, and billing frequency are derived from the associated plan.
* `metadata` is intended for additional merchant-defined information.
* `start_at` and `authorization_expires_at` are provider-generated values and are updated during the authorization process.
* A successful API response means the subscription record has been created; it does not mean that the customer has authorized the mandate.
* Store the returned `mandate_id` for subsequent subscription operations.
* Generate API signatures on your server only.
* Never expose your secret key in frontend applications.
* Use HTTPS for all API requests.

***

## Recommended Subscription Flow

1. Create a customer using the Create Customer API.
2. Create a subscription plan using the Create Plan API.
3. Create a subscription using the customer ID and plan ID.
4. Store the generated `mandate_id`.
5. Provide the subscription authorization/checkout URL to the customer when available.
6. Customer completes the mandate authorization process.
7. Receive the webhook notification and update the subscription status.
8. Use the Fetch Subscription API to retrieve the latest subscription details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.