[Order]
[What it does] Changes the supplier product and/or fulfillment Variant used by one order item. It can switch suppliers, select another product or Variant from the same supplier, or change only the fulfillment Variant while keeping the supplier and product unchanged. This edit affects the current order only: it does not change the buyer's original sales-channel SKU/Variant or the product's long-term Mapping.
[When to use] Use when the current supplier product or Variant is unavailable, out of stock, mispriced, cannot ship, or when the user explicitly chooses a different fulfillment Variant for this order.
[When not to use] To change the permanent product Mapping used by future orders, use apply_product_mapping. To change the buyer-facing sales-channel SKU/Variant, use the sales-channel workflow. The current supplier row must still be unplaced, cancelled, or failed; placed, in-progress, paid, shipped, fulfilled, or otherwise locked rows cannot be edited.
[How to use] Read the exact order and item with get_order, including its current supplier row and fulfillment Variant. Resolve and validate the selected supplier product, fulfillment Variant, stock, price, destination support, and freight. Pass exactly one of supplier_product_id and supplier_product_url; supplier_platform_id is required with either input. Before writing, show the old and new supplier, supplier product, fulfillment Variant name and ID, product price, freight, stock, and net cost change; label unavailable comparison values as unavailable rather than guessing. Obtain the user's explicit confirmation and their explicit allow_future_mapping_override choice. true allows a later product-level Mapping update to replace this order's manual fulfillment selection; false keeps the manual selection fixed against later Mapping updates. This choice does not modify the buyer's original SKU/Variant or immediately change product-level Mapping. If the write outcome is unknown, re-read get_order and the Orders page; never automatically retry.
[Side effects] Changes the supplier product, fulfillment Variant, and applicable freight used for this order item, which can change fulfillment cost and delivery details. It does not change the buyer's original sales-channel SKU/Variant or immediately modify product-level Mapping.
[Confirmation] Required, never skippable: show the complete old-versus-new fulfillment comparison and obtain the Mapping-override choice before calling.