v1

latestOpenAPI 3.1.02026-07-1382141292.4 KB

Subscriptions

Preview Subscription Adjustment

Returns a preview of what a subscription adjustment would look like, including proration amount, payment method, and whether the adjustment can be made. This endpoint does not make any changes to the subscription. Use this to show users what will happen before they commit to an adjustment.

post/api/v1/subscriptions/{id}/preview-adjust

Path parameters

idstring required

Request body

Response

Successful response

canAdjustboolean required

Whether the adjustment can be made. If false, the reason field will contain the explanation.

reasonstring

The reason the adjustment cannot be made, if canAdjust is false.

previewGeneratedAtinteger required

Epoch milliseconds when this preview was generated. Useful for staleness detection.

prorationAmountnumber

The proration amount that will be charged, if applicable.

currentPlanTotalnumber

The total price of the current plan (sum of unitPrice * quantity for all items).

newPlanTotalnumber

The total price of the new plan (sum of unitPrice * quantity for all items).

resolvedTiming'immediately' | 'at_end_of_current_billing_period'

The resolved timing for the adjustment. When auto timing is requested, this indicates whether it resolved to immediate or end-of-period.

effectiveDateinteger

Epoch milliseconds when the adjustment will take effect.

isUpgradeboolean

Whether this adjustment is an upgrade (true) or downgrade/lateral move (false).

percentThroughBillingPeriodnumber

The percentage through the current billing period (0-1).

billingPeriodEndinteger

Epoch milliseconds when the current billing period ends.