# Create Subscription

Use this API to creates a subscription against the plan.

## Environment

Use our UAT environment endpoint for testing and for integration utilize our production endpoint.

| Environment                    | Endpoints                                                       |
| :----------------------------- | :-------------------------------------------------------------- |
| User Acceptance Testing \[UAT] | `https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions` |
| Production \[PROD]             | `https://api.pluralpay.in/ps/api/v1/public/subscriptions`       |

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "subscription",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://pluraluat.v2.pinepg.in/ps/api/v1/public"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "x-bearer-format": "bearer"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/subscriptions": {
      "post": {
        "summary": "Create Subscription",
        "description": "Use this API to creates a subscription against the plan.",
        "operationId": "create-subscription",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "description": "The type of content included in the HTTP message body.<br><br>Possible value: `application/json`.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "The HTTP header where you can include your secret token for authentication.<br><br>Example: `Bearer <access_token>`<br><br>**Note**: Use the access token generated using our <a href=\"https://developer.pluralonline.com/v3.0/reference/generate-token\" target=\"_blank\">Generate Token API</a>.",
            "required": true,
            "schema": {
              "type": "string",
              "default": "Bearer"
            }
          },
          {
            "name": "Request-Timestamp",
            "in": "header",
            "description": "Use ISO 8601 UTC Timestamp, to create a timestamp when the generate token is requested.<br><br>Example: `2024-07-09T07:57:08.022Z`",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Request-ID",
            "in": "header",
            "description": "Use a global unique identifier [GUID] for the request.<ul><li>Minimum: 1 characters.</li><li>Maximum: 50 characters</ul></li>Example: `c17ce30f-f88e-4f81-ada1-c3b4909ed235`",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_subscription_reference",
                  "plan_id",
                  "start_date",
                  "end_date",
                  "customer_id",
                  "integration_mode"
                ],
                "properties": {
                  "merchant_subscription_reference": {
                    "type": "string",
                    "description": "Unique identifier of the merchant subscription reference entered while creating a suscription.<ul><li>Minimum length: 1 character.</li><li>Maximum length: 50 characters.</ul></li>Example: `1234567890`"
                  },
                  "plan_id": {
                    "type": "string",
                    "description": "Unique identifier for the subscription plan in the Pine Labs Online database.<br><br>Example: `v1-plan-4405071524-aa-qlAtAf`<br><br>**Note**: The plan should be in an active state."
                  },
                  "enable_notification": {
                    "type": "boolean",
                    "description": "Indicates if notifications are enabled.<br><br>Example: `true`<br><br>Possible values:<ul><li>`true`: Webhook notification will be sent to the configured webhook URL.</li><li>`false`: Webhook notification will not be sent to the configured webhook URL."
                  },
                  "start_date": {
                    "type": "string",
                    "description": "The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.<br><br>Example: `2022-02-01T17:32:28Z`  <br><br>**Note**: On ignoring this field plan start date will be considered as start date"
                  },
                  "end_date": {
                    "type": "string",
                    "description": "The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.<br><br>Example: `2022-09-21T17:32:28Z` <br><br>**Note**: <ul><li>On ignoring this field, the plan will be on Active state unless there is a manual update.</li><li>For one-time, the end date should be within 60 days from the start date.</ul></li>"
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "Unique identifier of the customer in the Pine Labs Online database.<br><ul><li>Minimum length: 1 character.</li><li>Maximum length: 19 characters.</ul></li>Example: `123456`<br><br>Refer to our <a href=\"https://developer.pinelabsonline.com/reference/customers\" target=\"_blank\">Customers</a> documentation to learn more."
                  },
                  "allowed_payment_methods": {
                    "type": "string",
                    "description": "The type of payment methods you want to offer customers.<br><br>Accepted value:<ul><li>`UPI`</ul></li>Example: `UPI`"
                  },
                  "integration_mode": {
                    "type": "string",
                    "description": "The integration mode for the subscription.Accepted values:<ul><li>`SEAMLESS`</li><li>`REDIRECT `</ul></li>   Example: `SEAMLESS`"
                  },
                  "merchant_metadata": {
                    "type": "object",
                    "description": "An object of key-value pair that can be used to store additional information.<br><br>Example: `\"key1\": \"DD\"`",
                    "properties": {
                      "key_1": {
                        "type": "string"
                      },
                      "key_2": {
                        "type": "string"
                      }
                    }
                  },
                  "is_tpv_enabled": {
                    "type": "boolean",
                    "description": "Indicates if Third-Party Validation (TPV) is enabled.<br><br>Example: `true`<br><br>Refer to our <a href=\"https://developer.pinelabsonline.com/docs/about-third-party-validations\" target=\"_blank\">Third Party Validations</a> documentation to learn more."
                  },
                  "bank_account": {
                    "type": "object",
                    "description": "**Mandatory** only when `is_tpv_enabled` is true.<br><br>An object that contains bank account details.",
                    "required": [
                      "account_number",
                      "name",
                      "ifsc"
                    ],
                    "properties": {
                      "account_number": {
                        "type": "string",
                        "description": "Customer's bank account number.<ul><li>Minimum length: 1 characters</li><li>Maximum length: 50 characters.</ul></li>Example: `04992990009595`"
                      },
                      "name": {
                        "type": "string",
                        "description": "Name of Customer.<br><br>Example: `Kevin Bob`"
                      },
                      "ifsc": {
                        "type": "string",
                        "description": "IFSC code of the bank account.<ul><li>Minimum: 11 characters</li><li>Maximum: 11 characters</ul></li>Example: `HDFC0001234`</li>Supported Characters:<ul><li>A-Z (Uppercase letters)</li><li>0-9 (Digits)</li></ul>"
                      }
                    }
                  },
                  "callback_url": {
                    "type": "string",
                    "description": "Use this URL to redirect your customers to specific success or failure pages based on the order or product details.<br><br>Example: https\\://sample-callback-url>/td>"
                  },
                  "failure_callback_url": {
                    "type": "string",
                    "description": "The URL specifically used to redirect customers to a failure page based on the order or product details.  Example: `https://sample-failure-callback-url` <br><br>**Note**:<ul><li>If the `failure_callback_url` is not provided, customers will be redirected to the `callback_url` for both successful and failed transactions.</li><li>If the `failure_callback_url` is provided, the `callback_url` will be used exclusively for successful transactions, while the `failure_callback_url` will be used for failed transactions.</li><li>If neither URL is provided, the default URL configured during merchant onboarding will be used.</ul></li>"
                  }
                }
              },
              "examples": {
                "Create Subscriptions": {
                  "value": {
                    "merchant_subscription_reference": "38ed3d71-1b0f-469e-b5e4-67606406f676",
                    "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,
                    "callback_url": "www.google.com",
                    "failure_callback_url": "www.example.com/failure"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"callback_url\": \"www.google.com\",\n    \"failure_callback_url\": \"www.example.com/failure\",\n    \"redirect_url\": \"https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_ye7V868X7DP92HQCSnVq7XZNlxvVhOQ3OgXGt96Buwfc53BwN9mUDwJsOcr%2Fw5uq&subscription_id=v1-sub-250612062122-aa-3HLXL5\",\n    \"order_id\": \"v1-250612062122-aa-UZyPbu\",\n    \"subscription_id\": \"v1-sub-250612062122-aa-3HLXL5\",\n    \"merchant_subscription_reference\": \"f5d77ef9-fa11-4f58-a9f4-543e4a7022c5\",\n    \"enable_notification\": true,\n    \"plan_details\": {\n        \"plan_id\": \"v1-pla-250612061639-aa-666Zge\",\n        \"status\": \"ACTIVE\",\n        \"plan_name\": \"Monthly Plan 2025-06-12T06:16:37.364Z\",\n        \"plan_description\": \"Diwali dhammaka plan intended to attract customers on diwali time\",\n        \"frequency\": \"Month\",\n        \"amount\": {\n            \"value\": 100,\n            \"currency\": \"INR\"\n        },\n        \"max_limit_amount\": {\n            \"value\": 210,\n            \"currency\": \"INR\"\n        },\n        \"trial_period_in_days\": 0,\n        \"start_date\": \"2025-06-12T06:16:39.927105Z\",\n        \"end_date\": \"2026-10-21T12:02:28Z\",\n        \"merchant_metadata\": {\n            \"key1\": \"DD\"\n        },\n        \"merchant_plan_reference\": \"b41770ac-cd3a-48d3-9e93-7dc9246b4751\",\n        \"created_at\": null,\n        \"modified_at\": null,\n        \"initial_debit_amount\": {\n            \"value\": 110,\n            \"currency\": \"INR\"\n        },\n        \"auto_debit_ot\": false\n    },\n    \"start_date\": \"2025-06-12T06:22:21Z\",\n    \"end_date\": \"2025-06-21T17:32:28Z\",\n    \"customer_id\": \"cust-v1-250519171901-aa-dPF6mg\",\n    \"payment_mode\": null,\n    \"allowed_payment_methods\": [\n        \"UPI\"\n    ],\n    \"integration_mode\": \"REDIRECT\",\n    \"merchant_metadata\": {\n        \"key1\": \"DD\",\n        \"key2\": \"XOF\"\n    },\n    \"status\": \"CREATED\",\n    \"is_tpv_enabled\": false,\n    \"bank_account\": {\n        \"account_number\": null,\n        \"name\": null,\n        \"ifsc\": null\n    },\n    \"created_at\": \"2025-06-12T06:21:22.242344Z\",\n    \"modified_at\": \"2025-06-12T06:21:22.267111Z\",\n    \"order_amount\": {\n        \"value\": 210,\n        \"currency\": \"INR\"\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "callback_url": {
                      "type": "string",
                      "example": "www.google.com"
                    },
                    "failure_callback_url": {
                      "type": "string",
                      "example": "www.example.com/failure"
                    },
                    "redirect_url": {
                      "type": "string",
                      "example": "https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_ye7V868X7DP92HQCSnVq7XZNlxvVhOQ3OgXGt96Buwfc53BwN9mUDwJsOcr%2Fw5uq&subscription_id=v1-sub-250612062122-aa-3HLXL5"
                    },
                    "order_id": {
                      "type": "string",
                      "example": "v1-250612062122-aa-UZyPbu"
                    },
                    "subscription_id": {
                      "type": "string",
                      "example": "v1-sub-250612062122-aa-3HLXL5"
                    },
                    "merchant_subscription_reference": {
                      "type": "string",
                      "example": "f5d77ef9-fa11-4f58-a9f4-543e4a7022c5"
                    },
                    "enable_notification": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "plan_details": {
                      "type": "object",
                      "properties": {
                        "plan_id": {
                          "type": "string",
                          "example": "v1-pla-250612061639-aa-666Zge"
                        },
                        "status": {
                          "type": "string",
                          "example": "ACTIVE"
                        },
                        "plan_name": {
                          "type": "string",
                          "example": "Monthly Plan 2025-06-12T06:16:37.364Z"
                        },
                        "plan_description": {
                          "type": "string",
                          "example": "Diwali dhammaka plan intended to attract customers on diwali time"
                        },
                        "frequency": {
                          "type": "string",
                          "example": "Month"
                        },
                        "amount": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "integer",
                              "example": 100,
                              "default": 0
                            },
                            "currency": {
                              "type": "string",
                              "example": "INR"
                            }
                          }
                        },
                        "max_limit_amount": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "integer",
                              "example": 210,
                              "default": 0
                            },
                            "currency": {
                              "type": "string",
                              "example": "INR"
                            }
                          }
                        },
                        "trial_period_in_days": {
                          "type": "integer",
                          "example": 0,
                          "default": 0
                        },
                        "start_date": {
                          "type": "string",
                          "example": "2025-06-12T06:16:39.927105Z"
                        },
                        "end_date": {
                          "type": "string",
                          "example": "2026-10-21T12:02:28Z"
                        },
                        "merchant_metadata": {
                          "type": "object",
                          "properties": {
                            "key1": {
                              "type": "string",
                              "example": "DD"
                            }
                          }
                        },
                        "merchant_plan_reference": {
                          "type": "string",
                          "example": "b41770ac-cd3a-48d3-9e93-7dc9246b4751"
                        },
                        "created_at": {},
                        "modified_at": {},
                        "initial_debit_amount": {
                          "type": "object",
                          "properties": {
                            "value": {
                              "type": "integer",
                              "example": 110,
                              "default": 0
                            },
                            "currency": {
                              "type": "string",
                              "example": "INR"
                            }
                          }
                        },
                        "auto_debit_ot": {
                          "type": "boolean",
                          "example": false,
                          "default": true
                        }
                      }
                    },
                    "start_date": {
                      "type": "string",
                      "example": "2025-06-12T06:22:21Z"
                    },
                    "end_date": {
                      "type": "string",
                      "example": "2025-06-21T17:32:28Z"
                    },
                    "customer_id": {
                      "type": "string",
                      "example": "cust-v1-250519171901-aa-dPF6mg"
                    },
                    "payment_mode": {},
                    "allowed_payment_methods": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "UPI"
                      }
                    },
                    "integration_mode": {
                      "type": "string",
                      "example": "REDIRECT"
                    },
                    "merchant_metadata": {
                      "type": "object",
                      "properties": {
                        "key1": {
                          "type": "string",
                          "example": "DD"
                        },
                        "key2": {
                          "type": "string",
                          "example": "XOF"
                        }
                      }
                    },
                    "status": {
                      "type": "string",
                      "example": "CREATED"
                    },
                    "is_tpv_enabled": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "bank_account": {
                      "type": "object",
                      "properties": {
                        "account_number": {},
                        "name": {},
                        "ifsc": {}
                      }
                    },
                    "created_at": {
                      "type": "string",
                      "example": "2025-06-12T06:21:22.242344Z"
                    },
                    "modified_at": {
                      "type": "string",
                      "example": "2025-06-12T06:21:22.267111Z"
                    },
                    "order_amount": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "integer",
                          "example": 210,
                          "default": 0
                        },
                        "currency": {
                          "type": "string",
                          "example": "INR"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"code\": \"SUBSCRIPTION_DURATION_OUTSIDE_PLAN\",\n  \"message\": \"Subscription start or end is before plans\"\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "PLAN_NOT_FOUND"
                        },
                        "message": {
                          "type": "string",
                          "example": "Plan not found"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "CUSTOMER_NOT_FOUND"
                        },
                        "message": {
                          "type": "string",
                          "example": "Customer not found"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "SUBSCRIPTION_DURATION_OUTSIDE_PLAN"
                        },
                        "message": {
                          "type": "string",
                          "example": "Subscription start or end is before plans"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "422",
            "content": {
              "application/json": {
                "examples": {
                  "Duplicate Request": {
                    "value": "{\n  \"code\": \"DUPLICATE_REQUEST\",\n  \"message\": \"Duplicate Merchant Reference ID received\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "DUPLICATE_REQUEST"
                    },
                    "message": {
                      "type": "string",
                      "example": "Duplicate Merchant Reference ID received"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"code\": \"INTERNAL_ERROR\",\n  \"message\": \"Internal Server Error\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "INTERNAL_ERROR"
                    },
                    "message": {
                      "type": "string",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```