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
string · required

Set to application/json.


X-Portone-Client-Key
string · required

The unique PortOne key for the merchant.


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
string · required

The unique PortOne key for the merchant.


signature_hash
string · required

Signature hash generated as per On-Demand Subscription Request Signature Documentation.


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
string · required

The source of creation: default, api, or checkout.


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 in international format (e.g., +91XXXXXXXXXX).


currency
string · required

The currency of the subscription (e.g., USD).


environment
string · required

Environment of the transaction, either sandbox or live.


notify_by_email
boolean

Specifies if email notifications should be sent (true/false).


notify_by_phone
boolean

Specifies if phone notifications should be sent (true/false).


plan_order_ref
string · required

The reference ID for the plan order.


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.


On-Demand Subscription-Specific Parameters

subscription_type
string · required

The type of subscription. Set to ONDEMAND.


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 or gift_wrap.
value
string · The value of the note. Example: Deliver between 9-11 AM or Yes.

additional_costs
array of objects
The JSON array for additional costs
key
string · The key describing the additional cost. Example: tax or shipping.
value
double · The value of the additional cost. Example: 50 for tax or 25 for shipping.

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

  1. Setup API Credentials: Ensure you have your PortOne Key, Secret Key, and JWT Token ready for authentication.
  2. Create Payload: Prepare the JSON request body with all required parameters.
  3. Generate Signature Hash: Generate the signature_hash as per the Signature Documentation.
  4. Send API Request: Use the API endpoint with the prepared payload.
  5. Handle API Response: Handle the response to retrieve the subscription link and its status.

Best Practices

  • Environment Selection: Use sandbox for testing and live 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.