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"
},
"billingAddress": {
"city": "San Francisco",
"region": "CA",
"country": "US",
"line1": "123 Market Street",
"line2": "Suite 100",
"postalCode": "94105"
},
"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>",
"status": 1,
"action": {
"redirectUrl": "<string>",
"method": "GET",
"type": "ALIPAY",
"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>"
}
}"<string>"Create Subscription
Create a subscription and initiate its first payment. Provide an existing payment instrument, or omit paymentInstrumentId for payment methods that support automatic payment instrument creation. You can provide billingAddress for the payment instrument and first-invoice tax calculation.
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"
},
"billingAddress": {
"city": "San Francisco",
"region": "CA",
"country": "US",
"line1": "123 Market Street",
"line2": "Suite 100",
"postalCode": "94105"
},
"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>",
"status": 1,
"action": {
"redirectUrl": "<string>",
"method": "GET",
"type": "ALIPAY",
"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>"
}
}"<string>"Authorizations
Your secret API key obtained from the Clink dashboard (Developers section)
Headers
Current timestamp in milliseconds since Unix epoch (required for request signing)
"1783513683000"
Body
Parameters required to create a subscription by API. Provide at least one of customerId, customerEmail, or referenceCustomerId.
Recurring price ID.
Product ID for the subscription.
Payment method type. Supported values are uppercase. CARD (requires a previously saved card and its paymentInstrumentId).
CARD, GCASH, CASHAPP, UPI, PIX Payment currency. The value is normalized to uppercase.
URL where the customer is redirected after required payment actions.
Existing customer ID. At least one customer identifier is required.
Customer email. Used to resolve or create a customer when customerId is not provided.
Merchant-side customer ID used to resolve, create, or bind a customer.
Merchant-side reference ID for reconciliation.
Existing payment instrument ID used for the initial payment and renewals. Required for payment methods that do not support automatic payment instrument creation. CARD requires a previously saved card and its paymentInstrumentId. Can be omitted for CASHAPP, GCASH.
Promotion code to apply.
Merchant metadata. Values must be strings.
Show child attributes
Show child attributes
Optional billing address used for the payment instrument and first-invoice tax calculation. This address takes precedence over the existing payment instrument address, customer billing address, and request IP country for the first invoice. When Clink automatically creates a payment instrument, the address is saved to the new payment instrument. When paymentInstrumentId references an existing payment instrument, this address does not update that payment instrument.
Show child attributes
Show child attributes
Platform type. Supported values are WEB and WAP.
WEB, WAP Device type. Supported values are Android and iOS.
Android, iOS Optional scheduled subscription plan changes. Each phase takes effect at a future billing period boundary.
10Show child attributes
Show child attributes
Response
Subscription created successfully
Response status code, 200 when success
200
Brief description of what happened, 'success' when happy case
"success"
Response data returned after creating a subscription. It contains the subscription, order, and invoice identifiers, together with the payment flow result.
Show child attributes
Show child attributes