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).

Subscription Flow

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.

Create Subscription Plan

Create Subscription Plan

Endpoint

Authentication

Request Body

Response (200 OK)

Code Examples

Example Response

On this page