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
preFulfillmentChangeOrderIdfor use in downstream credit memo or payment flows.
- 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, orOrderItemTaxLineItemSummary. - Add a new
OrderDeliveryGroupSummarywhen 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.
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.
Newcreates the record. Include areferenceIdso that other records in the same request can point to it.Updatemodifies an existing record. Identify the record by Salesforce ID and don’t include areferenceId.
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.
changeReasonis required and must be an active value from theOrderItemSummaryChange.Reasonpicklist.- 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.
referenceIdis valid only onNewrecords and must be unique within a request.- A new
OrderDeliveryGroupSummarymust include at least one newOrderItemSummaryassociated with it. - All related entities must belong to the order summary identified by orderSummaryId.
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
preFulfillmentChangeOrderIdasnull. - 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.
- Compute the desired end state in your integration: quantities, adjustment amounts, tax amounts, and totals.
- Build a
ChangeOrderSummaryInputRepresentationusingNewandUpdaterecords. Wire cross-references with@{referenceId}. Include a stablechangeOrdersReferenceNumberwhen the caller might retry the request. - Call
preview-change. Confirm thatsuccessistrueand thatchangeBalancesmatch your expected totals. - Call
submit-changewith the same payload. If the response returns apreFulfillmentChangeOrderId, pass the ID to your credit memo or payment flow.