--- title: "Preview Variant/Price Change" method: POST path: "/orders/line_items/{line_item_id}/changes" tags: ["Orders::LineItems::Change"] --- # Preview Variant/Price Change `POST /orders/line_items/{line_item_id}/changes` Returns a non-destructive preview of changing the variant and price of a subscription line item, including proration math, the next charge amount, and the effective date. Follows the same upgrade/downgrade rules as the in-app self-serve flow. When accessing the API through an OAuth connection from a third-party platform acting on another team's workspaces, this endpoint requires trusted platform access and returns 403 without it. This trusted-access check does not apply when acting on your own account (your own API key, or an OAuth app within its own team). Option discovery via change_options is a read and is never gated. Source allowed `products_price_id` targets from `GET /products/prices/{price_id}/change_options`. After previewing, call `POST /orders/line_items/{line_item_id}/changes/perform` with the same body to commit. The response envelope is identical between preview and commit and only the `preview` flag flips. On commit, the `previous_line_item` block reflects the line item's pre-change state for `products_price`, `products_variant`, `original_product`, and `prorated`. Other scalar attributes (`created_at`, `updated_at`, `quantity`) reflect the post-commit state on the underlying record. ## Path parameters - `line_item_id` union, required - integer - string ## Request body - OrdersLineItemsChangeRequest — Parameters to preview or commit a subscription line item variant/price change - `orders_line_items_change` object, required - `products_price_id` union, required — Target price. Accepts either the integer database id or the obfuscated `public_id` string returned by the discovery endpoint. The target variant is derived from the price's `variant` association. - integer - string - `prorate` boolean, nullable — Optional override for proration. Accepts `true`, `false`, `"true"`, `"false"`, `"1"`, `"0"`, `1`, or `0`. When omitted, the in-app default is used: upgrades are prorated and applied immediately; downgrades are not prorated and take effect at the end of the current billing cycle. Forced to `false` for physical line items regardless of the value sent. Any other value returns 422. - `effective_time` 'now' | 'next_renewal' | 'null', nullable — Optional override for when the change takes effect. When omitted (or `null`, or an empty string), the in-app default is used: upgrades take effect now, downgrades at the next renewal. Any other value (e.g. `end_of_period` or a literal timestamp) returns 422. ## Response `200` OK - OrdersLineItemsChangeResponse — Result of a subscription line item variant/price change. The same envelope is returned for both preview and commit endpoints — the `preview` flag indicates which. `upcoming_invoice` is a snapshot of the upcoming-invoice impact of the change as quoted by the upstream payment platform. It is **informational** — the line item is mutated regardless of whether the quote succeeds. On commit, the quote is snapshotted just before the change is applied so consumers don't need a separate preview round-trip to know what their customer will be charged. Individual amount fields may be `null` if the upstream quote returned no data; `currency` and `next_invoice_date` fall back to the order's stored currency and renewal date in that case. - `orders_line_items_change` object - `preview` boolean — `true` for the preview endpoint, `false` for the commit endpoint. The remainder of the envelope is shaped identically; the flag lets clients render the same UI or write the same parsing code for both calls. - `upcoming_invoice` object — Snapshot of the upcoming-invoice impact of the change as quoted by the upstream payment platform. Populated on both preview and commit (commit snapshots a quote inside the change transaction so the response carries the same fields as preview). Informational only — the line item change is committed regardless of whether the quote succeeds. - `total_amount` string, nullable — Upcoming invoice total quoted by the payment platform. `null` if the quote returned no data. - `subtotal_amount` string, nullable — Upcoming invoice subtotal quoted by the payment platform. `null` if the quote returned no data. - `tax_amount` string, nullable — Upcoming invoice tax quoted by the payment platform. `null` if the quote returned no data. - `shipping_amount` string, nullable — Upcoming invoice shipping quoted by the payment platform. `null` if the quote returned no data. - `discount_amount` string, nullable — Upcoming invoice discount quoted by the payment platform. `null` if the quote returned no data. - `currency` string, nullable — Currency of the upcoming invoice quote. Falls back to the order's stored currency if the quote returned no data. - `next_invoice_date` string, date-time, nullable — Upcoming invoice date as quoted by the payment platform. Falls back to the order's stored renewal date if the quote returned no data. - `previous_line_item` OrdersLineItemAttributes — Line items - `id` integer — Line item ID - `public_id` string, nullable — Line item public ID - `order_id` integer — Order ID - `quantity` integer, nullable — Quantity - `prorated` string, nullable — Prorate invoice - `created_at` string, nullable — Added - `updated_at` string, nullable — Updated - `original_product` object — Product - `id` integer — ID - `public_id` string, nullable — Product public ID - `name` string — Product name - `products_price` ProductsPriceMinimal — Minimal price representation used wherever a price appears as a nested attribute (line items, upgrade/downgrade discovery). - `id` integer - `public_id` string, nullable - `name` string, nullable - `key` string, nullable - `amount` string, nullable - `currency` string, nullable - `duration` integer, nullable - `interval` string, nullable - `interval_count` integer, nullable - `products_variant` object, nullable — Product Variant - `id` integer — ID - `public_id` string, nullable — Variant public ID - `name` string — Name - `description` string, nullable — The description of the variant. The description of the **default variant** is the user-facing description of the `Product`. - `sku` string, nullable — SKU - `new_line_item` OrdersLineItemAttributes — Line items - `id` integer — Line item ID - `public_id` string, nullable — Line item public ID - `order_id` integer — Order ID - `quantity` integer, nullable — Quantity - `prorated` string, nullable — Prorate invoice - `created_at` string, nullable — Added - `updated_at` string, nullable — Updated - `original_product` object — Product - `id` integer — ID - `public_id` string, nullable — Product public ID - `name` string — Product name - `products_price` ProductsPriceMinimal — Minimal price representation used wherever a price appears as a nested attribute (line items, upgrade/downgrade discovery). - `id` integer - `public_id` string, nullable - `name` string, nullable - `key` string, nullable - `amount` string, nullable - `currency` string, nullable - `duration` integer, nullable - `interval` string, nullable - `interval_count` integer, nullable - `products_variant` object, nullable — Product Variant - `id` integer — ID - `public_id` string, nullable — Variant public ID - `name` string — Name - `description` string, nullable — The description of the variant. The description of the **default variant** is the user-facing description of the `Product`. - `sku` string, nullable — SKU ## Other responses - `401` — Unauthorized - `403` — Forbidden - a third-party platform acting on another team's workspace without trusted platform access. This check does not apply to first-party or own-account writes. - `404` — Not Found - `422` — Unprocessable Entity --- [API](https://skmtc.dev/myclickfunnels/apis/clickfunnels-api.md) · [All operations](https://skmtc.dev/myclickfunnels/apis/clickfunnels-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/myclickfunnels/clickfunnels-api/revisions/ae6313eaa176/schema)