Creating an On-Demand Subscription
This document provides a comprehensive guide for creating an On-Demand Subscription using the PortOne API. Merchants can generate subscription links and share them with customers for flexible, usage-based billing.
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_1729672233762",
"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",
"initial_amount": 100,
"country_code": "US",
"currency": "USD",
"environment": "sandbox",
"notify_by_email": false,
"notify_by_phone": false,
"plan_order_ref": "2mbuAw2lSOkLHfB9cAyuxBxdd2W",
"subscription_type": "ONDEMAND",
"notes": [
{ "key": "special_instructions", "value": "Deliver between 9-11 AM" },
{ "key": "gift_wrap", "value": "Yes" }
],
"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 an On-Demand 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 On-Demand 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.
On-Demand Subscription-Specific Parameters
subscription_type
subscription_type
string · required
The type of subscription. Set to ONDEMAND
.
initial_amount
initial_amount
double · required
The amount for the first deduction (can be a floating-point number).
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.
expiry_date
expiry_date
string
The expiration date and time of the subscription link.
Response
Success Response
{
"is_success": true,
"merchant_order_ref": "Subscription_1729672233762",
"order_ref": "2mbuAw2lSOkLHfB9cAyuxBxdd2W",
"subscription_link": "https://subscription.portone.cloud/?ref=2mbuAw2lSOkLHfB9cAyuxBxdd2W",
"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 an On-Demand Subscription
- Setup API Credentials: Ensure you have your
PortOne Key
,Secret Key
, andJWT 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 On-Demand Subscriptions using the PortOne API.
Updated 5 days ago