Create Subscription

curl --request POST \ --url https://uat-api.clinkbill.com/api/subscription \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: <api-key>' \ --header 'X-Timestamp: <x-timestamp>' \ --data ' { "customerId": "cus_xxxxx", "productId": "prd_xxxxx", "priceId": "price_xxxxx", "paymentInstrumentId": "pi_xxxxx", "paymentMethodType": "CARD", "paymentCurrency": "USD", "returnUrl": "https://merchant.example.com/subscription/return", "merchantReferenceId": "sub_ref_123", "metadata": { "orderNo": "SO-10001" }, "scheduledPhases": [ { "sequence": 1, "effectiveCycle": 2, "priceSnapshotId": "ps_xxxxx", "quantity": 1, "metadata": { "plan": "pro" } } ], "platformType": "WEB", "deviceType": "Android" } '

{ "code": 200, "msg": "success", "data": { "subscriptionId": "<string>", "sessionId": "<string>", "paymentInstrumentId": "<string>", "action": { "redirectUrl": "<string>", "walletHandleRedirectOrDisplayQrCode": { "imageUrlPng": "<string>", "imageUrlSvg": "<string>", "imageDataUrl": "<string>", "hostedInstructionsUrl": "<string>", "mobileAuthUrl": "<string>", "fallbackUrl": "<string>", "packageName": "<string>", "expiresAt": 123, "expiresSecond": 123 }, "paymentMethodType": "<string>", "postData": {} }, "amount": 123, "currency": "<string>", "orderId": "<string>", "invoiceId": "<string>" } }

Authorizations

X-API-KEY

string

header

required

Your secret API key obtained from the Clink dashboard (Developers section)

Headers

X-Timestamp

string

required

Current timestamp in milliseconds since Unix epoch (required for request signing)

Example:

"1783513683000"

Body

application/json

Parameters required to create a subscription by API. Provide at least one of customerId, customerEmail, or referenceCustomerId.

priceId

string

required

Recurring price ID.

productId

string

required

Product ID for the subscription.

paymentMethodType

enum<string>

required

Payment method type. Supported values are uppercase.

Available options:

CARD,

GCASH,

CASHAPP,

UPI,

PIX

paymentCurrency

string

required

Payment currency. The value is normalized to uppercase.

returnUrl

string

required

URL where the customer is redirected after required payment actions.

customerId

string

Existing customer ID. At least one customer identifier is required.

customerEmail

string

Customer email. Used to resolve or create a customer when customerId is not provided.

referenceCustomerId

string

Merchant-side customer ID used to resolve, create, or bind a customer.

merchantReferenceId

string

Merchant-side reference ID for reconciliation.

paymentInstrumentId

string

Existing payment instrument ID used for the initial payment and renewals. Required for payment methods that do not support automatic payment instrument creation. Can be omitted for CASHAPP, GCASH.

promotionCode

string

Promotion code to apply.

metadata

object

Merchant metadata. Values must be strings.

Show child attributes

platformType

enum<string>

Platform type. Supported values are WEB and WAP.

Available options:

WEB,

WAP

deviceType

enum<string>

Device type. Supported values are Android and iOS.

Available options:

Android,

iOS

scheduledPhases

object[]

Optional scheduled subscription plan changes. Each phase takes effect at a future billing period boundary.

Maximum array length: 10

Show child attributes

Response

Subscription created successfully

code

integer<int32>

Response status code, 200 when success

Example:

200

msg

string

Brief description of what happened, 'success' when happy case

Example:

"success"

data

object

Response data returned after creating a subscription. It contains the subscription, order, and invoice identifiers, together with the payment flow result.

Show child attributes

API Documentation

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

API Reference

Subscription API

Test Clock

Agent Payment Session

Authorizations

Headers

Body

Response