curl --request POST \
--url https://uat-api.clinkbill.com/api/subscription/{id}/update/preview \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"priceId": "price_xxxx",
"quantity": 1,
"promotionCode": "SUMMER25",
"immediate": true,
"billingCycleAnchor": "now",
"prorationBehavior": "none"
}
'{
"code": 200,
"msg": "success",
"data": {
"subscriptionId": "<string>",
"immediate": true,
"billingCycleAnchor": "unchanged",
"prorationBehavior": "always_invoice",
"recurringPrice": {
"periodStart": 123,
"periodEnd": 123,
"priceId": "<string>",
"priceSnapshotId": "<string>",
"productId": "<string>",
"productName": "<string>",
"totalAmount": 123,
"unitAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123,
"interval": "day",
"recurring": "<string>"
},
"lines": {
"proratedCredit": {
"productName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123
},
"proratedCharge": {
"productName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123
},
"periodStart": 123,
"periodEnd": 123,
"subtotalAmount": 123,
"taxAmount": 123,
"taxRate": 123,
"taxName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD"
},
"discountObject": {
"couponId": "<string>",
"couponName": "<string>",
"couponTerms": "<string>",
"promotionCode": "<string>",
"discountAmount": 123,
"durationType": "<string>",
"durationMonths": 123,
"couponUsedTimes": 123
}
}
}"<string>"Preview Subscription Update
Preview a subscription upgrade or downgrade before confirming it. The target price must be a recurring price owned by the current merchant and must support the subscription payment currency. Use immediate to request an immediate or period-end update, or omit it to let the system decide. billingCycleAnchor and prorationBehavior may only be supplied with immediate=true. The preview returns the effective billing options when applicable. See the subscription guide for billing combinations and free-trial restrictions.
curl --request POST \
--url https://uat-api.clinkbill.com/api/subscription/{id}/update/preview \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"priceId": "price_xxxx",
"quantity": 1,
"promotionCode": "SUMMER25",
"immediate": true,
"billingCycleAnchor": "now",
"prorationBehavior": "none"
}
'{
"code": 200,
"msg": "success",
"data": {
"subscriptionId": "<string>",
"immediate": true,
"billingCycleAnchor": "unchanged",
"prorationBehavior": "always_invoice",
"recurringPrice": {
"periodStart": 123,
"periodEnd": 123,
"priceId": "<string>",
"priceSnapshotId": "<string>",
"productId": "<string>",
"productName": "<string>",
"totalAmount": 123,
"unitAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123,
"interval": "day",
"recurring": "<string>"
},
"lines": {
"proratedCredit": {
"productName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123
},
"proratedCharge": {
"productName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD",
"quantity": 123
},
"periodStart": 123,
"periodEnd": 123,
"subtotalAmount": 123,
"taxAmount": 123,
"taxRate": 123,
"taxName": "<string>",
"totalAmount": 123,
"currencySymbol": "<string>",
"currency": "USD"
},
"discountObject": {
"couponId": "<string>",
"couponName": "<string>",
"couponTerms": "<string>",
"promotionCode": "<string>",
"discountAmount": 123,
"durationType": "<string>",
"durationMonths": 123,
"couponUsedTimes": 123
}
}
}"<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"
Path Parameters
Unique identifier of the subscription
Body
Subscription update preview request
Parameters required to preview a subscription upgrade or downgrade.
Target recurring price ID. The price must belong to the current merchant and support the subscription payment currency.
Number of units for the target price. Optional; defaults to 1 when omitted. null and values below 1 are invalid.
x >= 1Promotion code to apply to the updated subscription.
Whether to force the update to take effect immediately. true requests an immediate update; false schedules it for the end of the current billing or trial period. Omitted or null lets the system decide. Explicit true requires both current and target prices to use flat_rate pricing. Outside a free trial, the target full-cycle amount (unit amount multiplied by quantity) must be greater than the current full-cycle amount; immediate downgrades and equal-amount changes are rejected.
true
Billing cycle anchor for an immediate update. A non-null value requires immediate=true. now starts a new full billing cycle at the update time; unchanged preserves the current period end. Outside a free trial, omitted or null uses unchanged. For an immediate free-trial update, omit this field if the target still has trial time remaining; when switching directly to paid billing, only now or omitted/null is allowed, and now is used.
now, unchanged, null "now"
Proration policy for an immediate update. A non-null value requires immediate=true. always_invoice credits the unused portion of the current plan and charges the target plan for the remaining period with unchanged, or a full cycle with now. none gives no credit for the current plan and charges the target plan's full-cycle amount with either anchor; it does not waive payment. Discounts and tax are applied afterward. Outside a free trial, omitted or null uses always_invoice. For an immediate free-trial update, omit this field if the target still has trial time remaining; when switching directly to paid billing, only none or omitted/null is allowed, and none is used.
always_invoice, none, null "always_invoice"
Response
Subscription update preview returned successfully