openapi: 3.2.0 info: title: ClickFunnels Orders::Line Items::Change API termsOfService: https://www.clickfunnels.com/terms-of-service contact: name: ClickFunnels API Team url: https://developers.myclickfunnels.com x-logo: url: https://statics.myclickfunnels.com/image/1126065/file/31edf05760fafe41a82f16a668ab251f.png description: 'The ClickFunnels REST API that powers webhooks, native integrations, and Zapier lets you manage your ClickFunnels data, automate your workflows, and recreate ClickFunnels functionality in your own apps. ' license: name: MIT url: https://opensource.org/licenses/MIT version: 2.0.0 servers: - url: https://{subdomain}.myclickfunnels.com/api/v2 description: ClickFunnels API variables: subdomain: default: myworkspace security: - BearerAuth: [] tags: - name: Orders::LineItems::Change description: '> Preview and commit variant/price changes on existing subscription line items. A self-serve flow for switching the variant or price on a subscription line item. The surface has three endpoints — discovery (`Products::Prices::ChangeOption`) tells you which targets are allowed; this resource is the actual change. `POST` to `…/changes` to preview the upcoming invoice (`preview: true`); `POST` to `…/changes/perform` to commit (`preview: false`). The response envelope is identical between preview and commit and only the `preview` flag flips. Allowed transitions are constrained by merchant-configured upgrade/downgrade option rows. See the discovery endpoint for sourcing legal `products_price_id` targets. See the [Subscription Changes Skill](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md) for the full flow — [preview](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#step-2---preview-the-change) and [commit](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#step-3---commit-the-change). ' paths: /orders/line_items/{line_item_id}/changes: post: tags: - Orders::LineItems::Change summary: Preview Variant/Price Change description: '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. See [Step 2 - Preview the change](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#step-2---preview-the-change) in the [Subscription Changes Skill](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md), and [Step 1 - Discover what''s allowed](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#step-1---discover-whats-allowed) for sourcing a legal target. ' operationId: previewOrdersLineItemsChange parameters: - $ref: '#/components/parameters/line_item_id' requestBody: description: Variant and price target for the preview required: true content: application/json: schema: $ref: '#/components/schemas/OrdersLineItemsChangeRequest' example: orders_line_items_change: products_price_id: 24 prorate: true effective_time: now responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrdersLineItemsChangeResponse' example: orders_line_items_change: preview: true upcoming_invoice: total_amount: '35.83' subtotal_amount: '35.83' tax_amount: '0.00' shipping_amount: '0.00' discount_amount: '0.00' currency: USD next_invoice_date: '2026-05-14T03:49:45Z' previous_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: {} products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null new_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: {} products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '403': description: 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. content: application/json: schema: type: object properties: error: type: string example: error: 'Forbidden: This endpoint is restricted to trusted developer platforms. Apply for trusted platform access at https://developers.myclickfunnels.com or contact support.' '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string example: error: The target variant and price combination is not an allowed upgrade or downgrade for this subscription. /orders/line_items/{line_item_id}/changes/perform: post: tags: - Orders::LineItems::Change summary: Change Variant/Price description: 'Commits a variant/price change for a subscription line item. The change must be configured as an allowed upgrade or downgrade option on the source variant. By default, upgrades take effect immediately and are prorated; downgrades take effect at the next renewal and are not prorated. Both behaviours can be overridden via `prorate` and `effective_time`. 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). Source allowed `products_price_id` targets from `GET /products/prices/{price_id}/change_options`, and preview the impact via `POST /orders/line_items/{line_item_id}/changes` before committing here. The response envelope is the same as preview, with `preview: false` — the amount fields and `next_invoice_date` carry the upstream invoice quote snapshotted just before the commit was applied. 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. See [Step 3 - Commit the change](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#step-3---commit-the-change) in the [Subscription Changes Skill](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md), plus [Eligibility](https://accounts.myclickfunnels.com/.well-known/subscription-changes/skill.md#eligibility) for which orders can be changed this way. ' operationId: performOrdersLineItemsChange parameters: - $ref: '#/components/parameters/line_item_id' requestBody: description: Target variant and price plus optional proration and timing overrides required: true content: application/json: schema: $ref: '#/components/schemas/OrdersLineItemsChangeRequest' example: orders_line_items_change: products_price_id: 24 prorate: true effective_time: now responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrdersLineItemsChangeResponse' example: orders_line_items_change: preview: true upcoming_invoice: total_amount: '35.83' subtotal_amount: '35.83' tax_amount: '0.00' shipping_amount: '0.00' discount_amount: '0.00' currency: USD next_invoice_date: '2026-05-14T03:49:45Z' previous_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: id: 15 public_id: AbC123 name: Sample Product products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null new_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: id: 15 public_id: AbC123 name: Sample Product products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '403': description: 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. content: application/json: schema: type: object properties: error: type: string example: error: 'Forbidden: This endpoint is restricted to trusted developer platforms. Apply for trusted platform access at https://developers.myclickfunnels.com or contact support.' '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string example: error: The target variant and price combination is not an allowed upgrade or downgrade for this subscription. components: schemas: OrdersLineItemsChangeRequest: type: object title: Line Item Change Request description: Parameters to preview or commit a subscription line item variant/price change required: - orders_line_items_change properties: orders_line_items_change: type: object required: - products_price_id properties: products_price_id: oneOf: - type: integer - type: string description: '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. ' prorate: type: - boolean - 'null' description: '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: type: - string - 'null' enum: - now - next_renewal - null description: '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. ' example: orders_line_items_change: products_price_id: 24 prorate: true effective_time: now OrdersLineItemsChangeResponse: type: object title: Line Item Change description: '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. ' properties: orders_line_items_change: type: object properties: preview: type: boolean description: '`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: type: object description: '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. ' properties: total_amount: type: - string - 'null' description: Upcoming invoice total quoted by the payment platform. `null` if the quote returned no data. subtotal_amount: type: - string - 'null' description: Upcoming invoice subtotal quoted by the payment platform. `null` if the quote returned no data. tax_amount: type: - string - 'null' description: Upcoming invoice tax quoted by the payment platform. `null` if the quote returned no data. shipping_amount: type: - string - 'null' description: Upcoming invoice shipping quoted by the payment platform. `null` if the quote returned no data. discount_amount: type: - string - 'null' description: Upcoming invoice discount quoted by the payment platform. `null` if the quote returned no data. currency: type: - string - 'null' description: 'Currency of the upcoming invoice quote. Falls back to the order''s stored currency if the quote returned no data. ' next_invoice_date: type: - string - 'null' format: date-time description: '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: allOf: - $ref: '#/components/schemas/OrdersLineItemAttributes' description: 'The line item as it was before the change — same `id` as the current line item, but with `products_price` and `products_variant` reflecting the pre-change target. ' new_line_item: allOf: - $ref: '#/components/schemas/OrdersLineItemAttributes' description: 'The line item as it would be after the change (preview) or as it now is after the change (commit) — same `id` as the current line item, with `products_price` and `products_variant` reflecting the target. ' example: orders_line_items_change: preview: true upcoming_invoice: total_amount: '35.83' subtotal_amount: '35.83' tax_amount: '0.00' shipping_amount: '0.00' discount_amount: '0.00' currency: USD next_invoice_date: '2026-05-14T03:49:45Z' previous_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: id: 15 public_id: AbC123 name: Sample Product products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null new_line_item: id: 9 public_id: yZaBcD order_id: 7 quantity: 1 prorated: null created_at: '2025-01-01T00:00:00.000Z' updated_at: '2025-01-01T00:00:00.000Z' original_product: id: 15 public_id: AbC123 name: Sample Product products_price: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 products_variant: null OrdersLineItemAttributes: type: object title: Line items description: Line items properties: id: type: integer description: Line item ID public_id: type: - string - 'null' description: Line item public ID order_id: type: integer description: Order ID quantity: type: - integer - 'null' description: Quantity prorated: type: - string - 'null' description: Prorate invoice created_at: type: - string - 'null' description: Added updated_at: type: - string - 'null' description: Updated original_product: type: object title: Product description: Product properties: id: type: integer description: ID public_id: type: - string - 'null' description: Product public ID name: type: string description: Product name products_price: $ref: '#/components/schemas/ProductsPriceMinimal' products_variant: type: - object - 'null' title: Product Variant description: Product Variant properties: id: type: integer description: ID public_id: type: - string - 'null' description: Variant public ID name: type: string description: Name description: type: - string - 'null' description: The description of the variant. The description of the **default variant** is the user-facing description of the `Product`. sku: type: - string - 'null' description: SKU example: id: 674 public_id: GjPVnN order_id: 22642 quantity: 2 prorated: null created_at: '2026-01-10T20:15:01.536Z' updated_at: '2026-01-10T20:15:01.536Z' original_product: id: 6512 public_id: YRnzRY name: Seinfeld In Your Pocket - Comedy Joke Machine (Black Premium) products_price: id: 22229 public_id: YqEWxY name: Seinfeld In Your Pocket - Comedy Joke Machine (Black Premium) key: null amount: '198.00' currency: usd duration: null interval: null interval_count: null products_variant: id: 22228 public_id: JdknyN name: Seinfeld In Your Pocket - Comedy Joke Machine (Black Premium) description: null sku: SIYP-BLACK-PREMIUM-001 required: - created_at - id - order_id - original_product - products_price - products_variant - prorated - public_id - quantity - updated_at ProductsPriceMinimal: type: object title: Products Price (Minimal) description: 'Minimal price representation used wherever a price appears as a nested attribute (line items, upgrade/downgrade discovery). ' properties: id: type: integer public_id: type: - string - 'null' name: type: - string - 'null' key: type: - string - 'null' amount: type: - string - 'null' currency: type: - string - 'null' duration: type: - integer - 'null' interval: type: - string - 'null' interval_count: type: - integer - 'null' example: id: 24 public_id: aBcDeF name: Pro Monthly key: pro_monthly_2024 amount: '20.00' currency: USD duration: null interval: months interval_count: 1 parameters: line_item_id: name: line_item_id in: path required: true description: 'The id of the subscription line item. Accepts either the integer database id or the obfuscated `public_id` string returned by line-item endpoints. ' schema: oneOf: - type: integer - type: string securitySchemes: BearerAuth: type: http scheme: bearer externalDocs: description: More in-depth guides and further resources url: https://developers.myclickfunnels.com