Creating a Regular Subscription
This document provides a comprehensive guide for creating a Regular Subscription using the PortOne API. Merchants can generate subscription links and share them with customers to process subscriptions seamlessly.
API Endpoint
POST https://api.portone.cloud/api/subscription/createSubscription
Headers
Content-Type
Content-Type
string · required
Set to application/json
.
X-Portone-Client-Key
X-Portone-Client-Key
string · required
The unique PortOne key for the merchant.
Authorization
Authorization
string · required
JWT for authenticating API requests. Learn how to generate the token here.
Request Example
Request Body:
{
"portone_key": "PORTONE_KEY",
"merchant_order_ref": "Subscription_1729672233761",
"source": "api",
"customer_email_address": "[email protected]",
"customer_name": "NGUYEN VAN A",
"customer_phone_number": "+919876543210",
"description": "Product name for the customer's subscription purchase",
"quantity": 1,
"currency": "USD",
"country_code": "US",
"environment": "sandbox",
"allow_accumulate": "Y",
"recurrance_count": 3,
"notify_by_email": false,
"notify_by_phone": false,
"plan_order_ref": "2nsJNracNOB6mzJ4elECMmnOlu2",
"subscription_type": "REGULAR",
"notes": [
{ "key": "special_instructions", "value": "Deliver between 9-11 AM" },
{ "key": "gift_wrap", "value": "Yes" }
],
"additional_costs": [
{ "key": "tax", "value": 50 },
{ "key": "shipping", "value": 25 }
],
"started_at": "",
"success_url": "https://subscription.portone.cloud/success.html",
"failure_url": "https://subscription.portone.cloud/failure.html",
"pending_url": "https://subscription.portone.cloud/pending.html"
}
Request Body Parameters
Below are the required and optional parameters for creating a Regular Subscription:
General Parameters
portone_key
portone_key
string · required
The unique PortOne key for the merchant.
signature_hash
signature_hash
string · required
Signature hash generated as per Regular Subscription Request Signature Documentation.
merchant_order_ref
merchant_order_ref
string · required
The unique merchant order reference generated by the merchant.
description
description
string
Product name for the customer's subscription purchase.
source
source
string · required
The source of creation: default
, api
, or checkout
.
customer_email_address
customer_email_address
string
Email address of the customer.
customer_name
customer_name
string
Name of the customer.
customer_phone_number
customer_phone_number
string
Phone number of the customer in international format (e.g., +91XXXXXXXXXX
).
currency
currency
string · required
The currency of the subscription (e.g., USD
).
environment
environment
string · required
Environment of the transaction, either sandbox
or live
.
notify_by_email
notify_by_email
boolean
Specifies if email notifications should be sent (true/false
).
notify_by_phone
notify_by_phone
boolean
Specifies if phone notifications should be sent (true/false
).
plan_order_ref
plan_order_ref
string · required
The reference ID for the plan order.
success_url
success_url
string · required
The URL to redirect to after a successful subscription.
failure_url
failure_url
string · required
The URL to redirect to after a failed subscription.
pending_url
pending_url
string · required
The URL to redirect to for a pending subscription.
Regular Subscription-Specific Parameters
subscription_type
subscription_type
string · required
The type of subscription. Set to REGULAR
.
allow_accumulate
allow_accumulate
string · required
Indicates whether accumulated payments are allowed (Y
or N
).
quantity
quantity
integer · required
The quantity of the item being subscribed.
recurrance_count
recurrance_count
integer · required
The number of times the subscription will recur.
started_at
started_at
string
The start date and time of the subscription in ISO format, or empty for immediate start.
expiry_date
expiry_date
string
The expiration date and time of the subscription link.
notes
array of objects
The JSON array for additional notes
key
string · The key describing the note. Example:special_instructions
orgift_wrap
.
value
string · The value of the note. Example:Deliver between 9-11 AM
orYes
.
additional_costs
array of objects
The JSON array for additional costs
key
string · The key describing the additional cost. Example:tax
orshipping
.
value
double · The value of the additional cost. Example:50
for tax or25
for shipping.
Response
Success Response
{
"is_success": true,
"merchant_order_ref": "Subscription_1729672233761",
"order_ref": "2nsJNracNOB6mzJ4elECMmnOlu2",
"subscription_link": "https://subscription.portone.cloud/?ref=2nsJNracNOB6mzJ4elECMmnOlu2",
"status_code": "200"
}
Error Response
{
"is_success": false,
"message": "The API request failed due to invalid parameters.",
"status_code": "400",
"status_reason": "Bad Request"
}
Steps to Create a Regular Subscription
- Setup API Credentials: Ensure you have your PortOne Key, Secret Key, and JWT Token ready for authentication.
- Create Payload: Prepare the JSON request body with all required parameters.
- Generate Signature Hash: Generate the
signature_hash
as per the Signature Documentation. - Send API Request: Use the API endpoint with the prepared payload.
- Handle API Response: Handle the response to retrieve the subscription link and its status.
Best Practices
- Environment Selection: Use
sandbox
for testing andlive
for production. - Validation: Validate all required fields before sending the request.
This document serves as a comprehensive guide to creating Regular Subscriptions using the PortOne API.
Updated 5 days ago