Change Order Summary API

Use the Change Order Summary API to modify an order summary and its related entities in a single request. Add or update pre-fulfillment order item summaries, delivery groups, order-level adjustments, item-level adjustments, taxes, and custom fields. To use this API, your org needs the SalesforceOrderManagementGrowth license.

Required Editions
Available in: Enterprise, Unlimited, and Developer Editions

The Change Order Summary API is generally available in API version 66.0 and later. It sits between order placement and the cancel, return, adjust-item, and exchange APIs, and lets a single request carry many related changes atomically.

The API has two resources.

Order Summaries, Preview Change returns the financial impact of a change request without persisting it. Use this resource to validate a request and confirm totals before submitting.
Order Summaries, Submit Change persists the change. For financial changes, the response includes a preFulfillmentChangeOrderId for use in downstream credit memo or payment flows.

Use Cases

Correct data from imports and integrations, such as incorrect tax amounts or sales channel IDs.
Add an OrderItemSummary, with its adjustments and taxes, to a placed order.
Cancel a pre-fulfillment item by setting its quantity and amounts to zero. Canceled items remain on the order summary. They aren’t deleted.
Change quantity or price on a pre-fulfillment item, along with related taxes and adjustments, in one atomic call.
Add or update an OrderItemAdjustmentLineSummary, OrderAdjustmentGroupSummary, or OrderItemTaxLineItemSummary.
Add a new OrderDeliveryGroupSummary when adding an item that ships separately.
Move an item to a different delivery group by canceling it on the current group and adding an equivalent item on the target group in the same request.
Update non-financial fields such as delivery instructions, custom fields, and descriptions without generating a change order.

Because a request can carry many related changes at once, an integrating system, such as a point-of-sale (POS) terminal, can bundle a full edit session into one call.

Request Structure

Both resources accept a changeOrderSummaryInput request body that groups changes by entity type: order summary, order item summaries, delivery groups, adjustment groups, item adjustment lines, and item tax line items. For properties, nested representations, and full JSON examples, see either resource page (Order Summaries, Preview Change or Order Summaries, Submit Change in the Commerce Connect REST API Developer Guide).

Each nested record has a changeType.

New creates the record. Include a referenceId so that other records in the same request can point to it.
Update modifies an existing record. Identify the record by Salesforce ID and don’t include a referenceId.

When one new entity needs to point to another new entity in the same request, use the @{referenceId} syntax. For example, to add a new order item summary with a new adjustment and a new tax line, assign the item a referenceId of newItem1, then set the adjustment’s and tax line’s parent field to @{newItem1}.

The API doesn’t calculate financial values. Your integration supplies the end-state amounts, and the API persists them verbatim. Each request must reflect the complete picture of the change: if you change an item’s quantity, also send the updated totalLineAmount, tax amounts, and adjustment amounts. Totals aren’t derived from child records.

Additional request requirements:

A request must contain at least one change and no more than 100. Each nested entity change counts individually.
changeReason is required and must be an active value from the OrderItemSummaryChange.Reason picklist.
You can modify only order item summaries whose quantities are entirely in pre-fulfillment status. For items in fulfillment, use the returns or exchanges APIs.
referenceId is valid only on New records and must be unique within a request.
A new OrderDeliveryGroupSummary must include at least one new OrderItemSummary associated with it.
All related entities must belong to the order summary identified by orderSummaryId.

Change Orders

The API records financial changes through a ChangeOrder, which anchors downstream invoice and credit memo activity. The API determines whether the request requires a change order based on its contents.

No change order. The API applies requests that only update non-financial fields directly to the order summary and its related entities. The response returns preFulfillmentChangeOrderId as null.
One pre-fulfillment change order. Requests that affect financials, including new items, quantity or price changes, and new or updated adjustments or taxes, produce a single pre-fulfillment change order. The response returns its ID in preFulfillmentChangeOrderId.

Every request is transactional. If any part fails, the API doesn’t persist any of the changes.

To make retries safe, set changeOrdersReferenceNumber to give a change a stable external identifier, such as a case number or POS transaction ID. If a change order with that reference number already exists on the order summary, the API rejects the request with a validation error.

Recommended Flow

Compute the desired end state in your integration: quantities, adjustment amounts, tax amounts, and totals.
Build a ChangeOrderSummaryInputRepresentation using New and Update records. Wire cross-references with @{referenceId}. Include a stable changeOrdersReferenceNumber when the caller might retry the request.
Call preview-change. Confirm that success is true and that changeBalances match your expected totals.
Call submit-change with the same payload. If the response returns a preFulfillmentChangeOrderId, pass the ID to your credit memo or payment flow.