Creating an OnDemand Plan

This document provides a comprehensive guide for creating an On-Demand Plan using the PortOne API. An On-Demand Plan allows merchants to charge customers based on their usage or activity without fixed intervals.

API Endpoint

POST https://api.portone.cloud/api/subscription/createPlan

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": "Plan_1729672233766",
  "source": "api",
  "currency": "USD",
  "name": "OnDemand USD plan",
  "description": "OnDemand USD plan",
  "environment": "sandbox",
  "plan_type": "ONDEMAND",
  "notes": [
    { "key": "key1", "value": "value1" },
    { "key": "key2", "value": "value2" }
  ]
}

Request Body Parameters

Below are the required and optional parameters for creating an On-Demand Plan:

General Parameters

portone_key

string · required

The unique PortOne key for the merchant.

signature_hash

string · required

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

merchant_order_ref

string · required

The unique merchant order reference generated by the merchant.

source

string · required

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

description

string

A description of the plan.

environment

string · required

Plan environment, either live or sandbox.

name

string · required

Name of the plan.

notes

array of objects

On-Demand Plan-Specific Parameters

currency

string · required

Currency of the plan (e.g., USD).

plan_type

string · required

Type of plan. Set to ONDEMAND.

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"
}

Signature Hash Generation

To ensure the authenticity of the request, generate the signature_hash by following the On-Demand Plan Request Signature Documentation.

Best Practices

• Environment Selection: Use sandbox for testing and live for production.
• Validation: Ensure all required fields are correctly validated before sending the request.
• Testing: Test your API integration in the sandbox environment before moving to production.

Key Notes

• OnDemand Plans: Ideal for usage-based subscriptions or services with variable billing.
• Descriptive Details: Use descriptive names and notes for easier plan management and tracking.

This document serves as a comprehensive guide to creating OnDemand Plans with the PortOne API.