Create Subscription Plan
Create a new subscription plan with billing frequency, installment amounts, terms, and payment details.
Create Subscription Plan
Version: 3.0.0
Generate an API Key for the Subscription channel before making requests.
Add a subscription plan and share the payment links with your customers. This endpoint creates a subscription plan with billing frequency, installment amounts, terms, and optional email notifications.
All Subscription Open API requests use base URL https://api.payorc.com/subscriptions/v1/ with merchant-key and merchant-secret headers (Subscription channel API key).
Endpoint
| Method | URL |
|---|---|
| POST | https://api.payorc.com/subscriptions/v1/add |
Please use the test credentials for sandbox testing.
Authentication
Include the following headers in every request:
| Header | Type | Description |
|---|---|---|
merchant-key | String | Your merchant key (e.g. live-D111PIS13YK) |
merchant-secret | String | Your merchant secret (e.g. sec-JI11G0P13Z0) |
All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected.
Request Body
Send a JSON object with the fields below. Amount fields must be numbers (not quoted strings). Dates use YYYY-MM-DD HH:mm.
| Field | Type | Required | Description |
|---|---|---|---|
plan_name | String | Yes | Plan name. Max 50 characters. Must be unique for the same billing frequency, currency, and installment amount. |
plan_description | String | No | Plan description. Max 250 characters. Letters, numbers, spaces, ., -, , only. |
billing_frequency | Object | Yes | How often the customer is billed. |
billing_frequency.frequency | String | Yes | One of: daily, weekly, monthly, yearly. |
billing_frequency.interval | Number | Yes | Billing interval (e.g. 1 = every cycle, 2 = every other cycle). Min 1. |
installment_amount | Object | Yes | Standard installment amount (excluding fees). |
installment_amount.currency | String | Yes | 3-letter ISO currency enabled on your merchant account (e.g. AED). |
installment_amount.value | Number | Yes | Installment amount. Min 1. Must be ≥ initial, final, and discount amounts. |
terms | Object | Yes | Plan duration and optional discount. |
terms.unlimited | String | Yes | yes = unlimited recurring terms; no = fixed number of terms. |
terms.value | Number | Conditional | Required when terms.unlimited is no. Number of billing terms (1–1999). Omit when unlimited is yes. |
terms.discount_term | Number | No | Term number (1-based) that uses the discounted amount. Must be ≤ terms.value when unlimited is no. |
terms.discount_amount | Number | No | Discounted installment amount for the specified term. Required if discount_term > 0. |
initial_payment_amount | Number | Yes | First payment amount. Min 1. Cannot exceed installment_amount.value. |
final_payment_amount | Number | Yes | Last payment amount (when terms are fixed). Min 1. Cannot exceed installment_amount.value. |
shipping_fee | Number | Yes | Shipping fee added to each payment. Min 0. |
convenience_fee | Number | Yes | Convenience fee added to each payment. Min 0. |
start_date | String | Yes | Plan start date/time. Format: YYYY-MM-DD HH:mm. Must be today or a future date. |
expiry_date | String | No | Plan expiry date/time. Format: YYYY-MM-DD HH:mm. Must be after start_date if provided. |
note | String | No | Internal note. Max 250 characters. |
customer_emails | String | Yes* | Comma-separated recipient emails (max 40). *Key must be present; send empty string "" to skip email. |
customer_email_cc | String | Yes* | Comma-separated CC emails (max 5). *Key must be present; send empty string "" if not used. |
subject | String | Yes* | Email subject. Max 200 characters. *Key must be present; send empty string "" if not sending email. |
product_details | String | Yes* | Product info shown to the customer. Max 200 characters. *Key must be present; send empty string "" if not used. |
Email fields (optional): To create a plan without sending email, set customer_emails, customer_email_cc, subject, and product_details to empty strings. If you set customer_email_cc or subject without customer_emails, the request is rejected. If you set customer_emails, subject is also required.
IDs in responses: data_id is the encrypted plan identifier — store this for update, activate, deactivate, details, and send-mail. plan_id is the plain display plan number shown to customers.
Response (200 OK)
| Field | Type | Description |
|---|---|---|
data_id | String | Encrypted plan identifier — use for update, activate, deactivate, details, and send-mail. |
plan_id | String | Plain display plan number. |
qr_code | String | Base64-encoded image data of the QR code. |
link | String | Payment link associated with the created subscription plan. |
message | String | Message indicating the success of the subscription plan creation. |
status | String | success or error. |
code | String | Status code, e.g., 00 for success. |
Code Examples
curl --location 'https://api.payorc.com/subscriptions/v1/add' \
--header 'merchant-key: YOUR_MERCHANT_KEY' \
--header 'merchant-secret: YOUR_MERCHANT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"plan_name": "Shree ram yatra",
"plan_description": "pratishtha",
"billing_frequency": {
"frequency": "daily",
"interval": 2
},
"installment_amount": {
"currency": "AED",
"value": 300
},
"terms": {
"unlimited": "no",
"value": 20,
"discount_term": 5,
"discount_amount": 90
},
"initial_payment_amount": 109,
"final_payment_amount": 80,
"shipping_fee": 20,
"convenience_fee": 10,
"start_date": "2027-01-15 10:00",
"expiry_date": "2027-06-15 23:59",
"note": "",
"customer_emails": "[email protected]",
"customer_email_cc": "[email protected]",
"subject": "Subscription plan details",
"product_details": ""
}'Example Response
{
"data_id": "WGcrVHhrNllyY2tLMlBmcTBBZ3FaZz09",
"plan_id": "0000000007",
"qr_code": "{qr_code}",
"link": "{payment_url}",
"message": "Subscription plan created successfully.",
"status": "success",
"code": "00"
}Store the data_id safely — you will need it to update or deactivate the plan later.