--- title: "Preview Subscription Adjustment" method: POST path: "/api/v1/subscriptions/{id}/preview-adjust" tags: ["Subscriptions"] --- # Preview Subscription Adjustment `POST /api/v1/subscriptions/{id}/preview-adjust` 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. ## Path parameters - `id` string, required ## Request body - object - `adjustment` union, required - object - `timing` 'immediately', required — Apply the adjustment immediately. - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - `prorateCurrentBillingPeriod` boolean — Whether to prorate the current billing period. Defaults to true for immediate adjustments. - object - `timing` 'at_end_of_current_billing_period', required - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - object - `timing` 'auto', required — Automatically determine timing: upgrades happen immediately, downgrades at end of period. - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - `prorateCurrentBillingPeriod` boolean — Whether to prorate if the adjustment is applied immediately. Defaults to true. ## Response `200` Successful response - PreviewAdjustSubscriptionOutput - `canAdjust` boolean, required — Whether the adjustment can be made. If false, the reason field will contain the explanation. - `reason` string — The reason the adjustment cannot be made, if canAdjust is false. - `previewGeneratedAt` integer, required — Epoch milliseconds when this preview was generated. Useful for staleness detection. - `prorationAmount` number — The proration amount that will be charged, if applicable. - `currentPlanTotal` number — The total price of the current plan (sum of unitPrice * quantity for all items). - `newPlanTotal` number — 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. - `effectiveDate` integer — Epoch milliseconds when the adjustment will take effect. - `isUpgrade` boolean — Whether this adjustment is an upgrade (true) or downgrade/lateral move (false). - `percentThroughBillingPeriod` number — The percentage through the current billing period (0-1). - `billingPeriodEnd` integer — Epoch milliseconds when the current billing period ends. - `paymentMethod` PreviewPaymentMethod - `id` string, required - `type` string, required - `last4` string - `brand` string - `currentSubscriptionItems` PreviewSubscriptionItem[] — The current subscription items. - `name` string, required - `unitPrice` number, required - `quantity` number, required - `priceId` string, required - `newSubscriptionItems` PreviewSubscriptionItem[] — The new subscription items that will be applied. - `name` string, required - `unitPrice` number, required - `quantity` number, required - `priceId` string, required ## Other responses - `400` — Invalid input data - `401` — Authorization not provided - `403` — Insufficient access - `500` — Internal server error --- [API](https://skmtc.dev/flowglad/apis/flowglad-api-2.md) · [All operations](https://skmtc.dev/flowglad/apis/flowglad-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flowglad/flowglad-api-2/revisions/c838c92c3606/schema)