Create a Subscription Link

Create Subscription Link API

The Create Subscription Link API allows merchants to generate subscription links that can be sent to customers for processing subscriptions. This API supports various parameters to customize the subscription link, including plan, customer details, and more.

You can visit Create Subscription API for our interactive documentation for testing this endpoint

Endpoint

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

Headers

X-Portone-Client-Key: Unique identifier for the client.
Authorization: Bearer token for authentication.
Content-Type: The content type of the request body (application/json).

Request Body

The request body should be in JSON format and includes the following parameters:

{
    "portone_key": "string",                 // PortOne key of the merchant
    "signature_hash": "string",              // Hash used for verifying the request's authenticity
    "merchant_order_ref": "string",          // Unique merchant reference for the subscription link
    "source": "string",                      // Source of the request (e.g., "api")
    "customer_email_address": "string",      // Customer's email address
    "customer_name": "string",               // Full name of the customer
    "customer_phone_number": "string",       // Customer's phone number in international format (e.g., +91XXXXXXXXXX)
    "quantity": "integer",                   // Number of products being purchased
    "currency": "string",                    // Currency code (e.g., USD, EUR, THB)
    "environment": "string",                 // API environment (e.g., "sandbox" for testing, "production" for live)
    "allow_accumulate": "string",            // Whether to allow accumulation of charges to the next cycle for failed deductions (Y/N)
    "recurrance_count": "integer",           // Number of times the deduction must be made for the subscription
    "notify_by_email": "boolean",            // Whether the customer should be notified via email (true/false)
    "notify_by_phone": "boolean",            // Whether the customer should be notified via phone (true/false)
    "plan_order_ref": "string",              // Unique reference for the subscription's plan
    "subscription_type": "string",           // Type of subscription (e.g., "REGULAR", "ONDEMAND")
    "notes": [                               // Additional notes related to the order
        {
            "key": "string",                 
            "value": "string"               
        },
        {
            "key": "string",                
            "value": "string"              
        }
    ],
    "additional_costs": [                    // Any additional costs related to the order (e.g., taxes, shipping)
        {
            "key": "string",                 // Description of the additional cost (e.g., "Tax")
            "value": "float64"               // Amount of the additional cost
        },
        {
            "key": "string",                 // Another additional cost description (e.g., "Shipping")
            "value": "float64"               // Amount of this additional cost
        }
    ],
    "started_at": "string",                  // Start date of the subscription in ISO date format, or empty if not set
    "expiry_date": "string",                 // Expiry date of the subscription link in ISO date format
    "success_url": "string",                 // URL to redirect the customer to upon successful subscription
    "failure_url": "string",                 // URL to redirect the customer to upon failure of the subscription
    "pending_url": "string"                  // URL to redirect the customer to if the subscription is pending
}

Example Request

curl --location 'https://api.portone.cloud/api/subscription/createSubscription' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {BEARER_TOKEN}' \
--header 'X-Portone-Client-Key: {PORTONE_KEY}' \

--data-raw '{
    "portone_key": "{PORTONE_KEY}",
    "signature_hash": "signature_hash",
    "merchant_order_ref": "Subscription_1729675716234",
    "source": "api",
    "customer_email_address": "[email protected]",
    "customer_name": "NGUYEN VAN A",
    "customer_phone_number": "+919876543210",
    "quantity": 3,
    "currency": "THB",
    "environment": "sandbox",
    "allow_accumulate": "Y",
    "recurrance_count": 3,
    "notify_by_email": false,
    "notify_by_phone": false,
    "plan_order_ref": "2UernXdexzqfkiNnmUm5rhcKglg",
    "subscription_type": "REGULAR",
    "notes": [
        {
            "key": "key1",
            "value": "value1"
        },
        {
            "key": "key2",
            "value": "value2"
        }
    ],
    "additional_costs": [
        {
            "key": "Tax",
            "value": 35
        },
        {
            "key": "Shipping",
            "value": 50
        }
    ],
    "started_at": "2023-06-27T17:30:00.000Z",
    "expiry_date": "2023-06-27T17:30:00.000Z",
    "success_url": "https://subscription.portone.cloud/success.html",
    "failure_url": "https://subscription.portone.cloud/failure.html",
    "pending_url": "https://subscription.portone.cloud/pending.html"
}'

Responses

Success

Status Code: 200 OK
Content-Type: application/json
Body: Contains the details of the created subscription link, including the link URL and status.

Error

Status Code: 400 Bad Request or 401 Unauthorized
Content-Type: application/json
Body: Contains error details and message explaining the issue.

Additional Information

Authentication: An Authorization header with a Bearer token is required.
Environment: Set environment to sandbox for testing purposes.
For further assistance or questions, please refer to the PortOne support documentation or contact support.

Summary

Creating subscription links on PortOne is simple and can be done either manually via the Dashboard or automatically via APIs. Follow the above steps to ensure you set up your subscription links correctly and efficiently.

For additional support or queries, please refer to the PortOne support resources or contact customer support.