Preview Variant/Price Change
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
The id of the subscription line item. Accepts either the integer database id or the obfuscated public_id string returned by line-item endpoints.
Request body
Example request
{
"orders_line_items_change": {
"products_price_id": 24,
"prorate": true,
"effective_time": "now"
}
}Response
OK
Example response
{
"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"
},
"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"
}
}
}