---
title: "Create Subscription"
method: POST
path: "/api/subscription/createSubscription"
tags: ["Subscription APIs"]
---

# Create Subscription

`POST /api/subscription/createSubscription`

Create a Subscription link. In response you will get the Subscription Link reference and the Subscription link URL. You can share the subscription link with your customer. The master merchant can also create the subscription link for their sub-merchants, by passing the sub-merchant key as a header. Refer API docs for additional information.

## Headers

- `Content-Type` string
- `X-Portone-Client-Key` string
- `Authorization` string

## Request body

- object
  - `portone_key` string, required — The unique PortOne key for merchant
  - `signature_hash` string, required — The signature_hash of subscription generated as per <a href="/docs/regular-subscription" target="_blank">Regular Subscription Request Signature Documentation</a> or <a href="/docs/ondemand-subscription" target="_blank">Ondemand Subscription Request Signature Documentation</a>
  - `merchant_order_ref` string, required — The unique merchant order reference generated by the merchant
  - `description` string — Product name for the customer's subscription purchase
  - `source` 'default' | 'api' | 'checkout', required — default, api or checkout -- The Source of creation.
  - `customer_email_address` string — Email address of the customer
  - `customer_name` string — Name of the customer
  - `customer_phone_number` string — Phone number of the customer
  - `currency` string, required — The currency of the subscription
  - `environment` 'live' | 'sandbox', required — The environment of transacation either live OR sandbox
  - `notify_by_email` boolean — Specifies if email notifications should be sent
  - `notify_by_phone` boolean — Specifies if phone notifications should be sent
  - `plan_order_ref` string, required — The reference ID for the plan order
  - `notes` object[] — Additional Notes
    - `key` string — Title
    - `value` string — Description
  - `additional_costs` object[] — Additional Cost. Optional for REGULAR Subscription, not available for ONDEMAND Subscription
    - `key` string — Type of cost
    - `value` number, double — Amount
  - `success_url` string, required — The URL to redirect to after a successful subscription
  - `failure_url` string, required — The URL to redirect to after a failed subscription
  - `pending_url` string, required — The URL to redirect to for a pending subscription
  - `subscription_type` 'REGULAR' | 'ONDEMAND', required — The type of subscription
  - `initial_amount` number, double — The amount of the first deduction, can be a floating-point number. Required only for ONDEMAND Subscription, not available for REGULAR Subscription
  - `first_txn_auto_refund` boolean — Indicates whether the first transaction should be auto-refunded. Available only for ONDEMAND Subscription, not available for REGULAR Subscription
  - `allow_accumulate` 'Y' | 'N' — Indicates whether accumulated payments are allowed. Possible values Y or N. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
  - `quantity` integer — The quantity of the item being subscribed. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
  - `recurrance_count` number — The number of times the subscription will recur. Required only for REGULAR Subscription, not available for ONDEMAND Subscription
  - `started_at` string — The start date and time of the subscription. Send empty value to start immediately, not available for ONDEMAND Subscription
  - `trial_frequency` integer — To have a trial set the trial frequency greater than 0. Use either start_date or trial_frequency and trial_period for REGULAR Subscription, not available for ONDEMAND Subscription
  - `trial_period` 'H' | 'D' | 'W' | 'M' | 'Q' | 'Y' — To have a trial set the trial period. Use either start_date or trial_frequency and trial_period for REGULAR Subscription, not available for ONDEMAND Subscription. Hour trial_period is only for testing purpose
  - `expiry_date` string — The expire date and time of the subscription link

## Response `200`

Successful response

- object
  - `is_success` boolean — The boolean flag denoting if subscription link was successfully created
  - `merchant_order_ref` string — The unique Order reference generated by merchant
  - `order_ref` string — The unique subscription link reference stored in PortOnes database
  - `subscription_link` string — The subscription link generated on PortOne
  - `status_code` string — The status_code for API request execution result

## Other responses

- `400` — Failure response

---

[API](https://skmtc.net/portone/apis/payment-apis.md) · [All operations](https://skmtc.net/portone/apis/payment-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/portone/payment-apis/versions/f3ccea652555/schema)