Change Variant/Price
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.
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"
}
}
}