Update Order
Updates an existing order. The fields that can be modified depend on the current state of the order and the updateMode used.
Update Modes
| Mode | Value | Description |
|---|---|---|
ApplyToOriginal | (default) | Applies changes directly to the order. For accepted orders, the order must pass editability checks or the call will be rejected (except for ExternalId on partial orders). |
ApplyToDraft | ApplyToDraft | Applies changes to a draft copy of the order. The original order is not modified. A draft is automatically created if one does not exist. The draft has Status=Pending and passes editability checks, so all editable fields can be set on the draft. |
ApplyAndCommit | ApplyAndCommit | Applies changes to the draft and then commits the draft back to the original order. For accepted orders, this creates new shipments from the draft order items. |
Editability Rules
An order is considered not editable when any of the following are true:
- The order has been accepted (
AcceptedDateis set, meaning shipments have been created). - The order status is not one of:
Pending,PendingReview, orPendingShipment. - The order is a partial/split order in a non-
Pending/non-PendingShipmentstatus.
When the order is not editable and updateMode=ApplyToOriginal, the API will return a 403 Forbidden error, except for the ExternalId field on partial orders (see below).
When updateMode=ApplyToDraft, the changes are applied to the draft copy which is always in Pending status, so the editability restriction does not block the update.
Fields Updated by UpdateOrder
Always Updated (Regardless of Order Status)
These fields are copied from the request body to the order on every call, whether the order is pre-acceptance or post-acceptance (when using draft mode):
| Field | Notes |
|---|---|
Email | Overwrites the existing value. |
SourceDevice | Overwrites the existing value. |
AcceptsMarketing | Only updated if the incoming value is non-null; otherwise the existing value is preserved. |
VisitId | Overwrites the existing value. |
WebSessionId | Overwrites the existing value. |
CustomerInteractionType | Overwrites the existing value. |
ShopperNotes | Overwrites the existing value. |
AlternateContact | Overwrites the existing value. |
ShipmentCreationOffset | Validated: must be -1 or a positive integer from 1 to 7200. |
ParentOrderId | Validated: cannot be set to the order’s own ID; the referenced parent order must exist. |
ExternalId | Can be set or changed, but cannot be cleared once set. If the incoming value is null or empty, the existing value is preserved. |
FulfillmentInfo | Updated via SetFulfillmentInfoAsync if a non-null value is provided. |
Conditionally Updated
| Field | Condition | Notes |
|---|---|---|
UserId | Only if CustomerAccountId is null and UserId is currently blank on the order. | Once set, UserId cannot be changed via this API. |
CustomerAccountId | Only if CustomerAccountId is currently null on the order. | Once set, CustomerAccountId cannot be changed via this API. If not yet set and the caller is not an anonymous shopper, a customer account is created or looked up automatically. |
DutyAmount | Only if the order is in a modifiable status (not Completed, Cancelled, Null, or Abandoned). | If the order is in a terminal status and the incoming DutyAmount differs from the existing value, a cannotUpdateDutyAmount validation error is thrown. If the duty total changes, the pricing pipeline is re-executed. |
BillingInfo | Only if the order has not been accepted (HasBeenAccepted = false). | Ignored on accepted orders. Use the dedicated Set Billing Info API instead. |
IPAddress | Only for offline orders (Type = Offline). | For online orders, the IP address is set from the client request automatically (pre-submission only). |
OriginalCartId | Only for offline orders, and only if a non-empty value is provided. | Used for cart takeover scenarios. |
Post-Acceptance Discount Exclusions
When the order has been accepted, the API supports updating discount exclusions on existing order-level and shipping-level discounts:
OrderDiscounts— each discount’s exclusion flag can be toggled viaUpdateDiscountExclusion.ShippingDiscounts— each discount’s exclusion flag can be toggled viaUpdateDiscountExclusion.
If any discount exclusion is changed, the pricing pipeline is re-executed to recalculate totals.
This is the only pricing-related modification available on accepted orders through this endpoint (outside of draft mode).
ExternalId on Non-Editable Partial Orders
As a special case, if the order fails editability checks (e.g., it is a partial/split order that has been accepted) but the request body includes a non-empty ExternalId, the ExternalId is updated and the order is saved immediately. No other fields are modified and no pricing pipeline is executed. This is the only field that bypasses the editability restriction outside of draft mode.
Draft Mode Behavior (ApplyToDraft / ApplyAndCommit)
When updateMode=ApplyToDraft:
- The system retrieves or creates a draft copy of the order. The draft is a separate embedded document with
Status=PendingandIsDraft=true. - All field updates listed above are applied to the draft, not the original order.
- The draft is persisted. The original order is unchanged.
- The draft is returned in the response.
When updateMode=ApplyAndCommit:
- The same field updates are applied to the draft.
- After updates, the system calls
CreateShipmentsFromDraftOrder, which:- Validates the order is in draft mode and has items.
- Splits the draft order into shipments via the fulfillment routing engine.
- Evaluates and updates the rollup status on the original order.
- Adds a
PostSubmitItemsAddedchange message to the original order. - Clears the draft from the original order.
- The updated original order (with new shipments) is returned.
Pricing Pipeline
The update order pricing pipeline is re-executed when:
DutyAmountchanges (and the order is in a modifiable status).- A discount exclusion is toggled on an accepted order.
When the pipeline runs, it recalculates order totals, taxes, and applied discounts.
Summary: What Can You Update on an Accepted Order with Shipments?
Directly (updateMode=ApplyToOriginal)
| Updatable | Field |
|---|---|
| Yes | Email |
| Yes | SourceDevice |
| Yes | AcceptsMarketing |
| Yes | VisitId |
| Yes | WebSessionId |
| Yes | CustomerInteractionType |
| Yes | ShopperNotes |
| Yes | AlternateContact |
| Yes | ShipmentCreationOffset |
| Yes | ParentOrderId |
| Yes | ExternalId (set/change only, not clear) |
| Yes | FulfillmentInfo |
| Yes | DutyAmount (if order is not in terminal status) |
| Yes | OrderDiscounts / ShippingDiscounts (exclusion flag only) |
| No | BillingInfo (ignored after acceptance; use Set Billing Info) |
| No | UserId (locked once set) |
| No | CustomerAccountId (locked once set) |
| No | IPAddress (online orders only, pre-submission only) |
| No | Items (use draft mode or the dedicated Order Items API) |
Via Draft Mode (updateMode=ApplyToDraft then ApplyAndCommit)
All of the above fields, plus the ability to modify items on the draft and commit them as new shipments on the original order.
Query Parameters
Body
All properties of the order to place.
Order form.
Shipment information, which includes the shipping address, price, estimated delivery date, tracking information, method (for example, Ground, Overnight, or Pick-up), carrier (for example, USPS, UPS, FedEx), and current status (for example, Not Shipped, In Transit, Delayed, or Returned To Sender).
Payment transaction associated with this order. It is the entire payment interchange between the merchant who is forwarding the customer's payment information and the payment service who is authorizing and capturing payment. Payment can be either by credit card, check, or PayPal.
Refunds associated with this order. A refund is a single exchange of money from merchant to customer that either encapsulates a refund to a credit card or an issuance of a store credit. Refunds does not reduce the 'amount collected' on an order and it is possible for refunds to exceed the total order amount.
Response
OK
Order form.
Shipment information, which includes the shipping address, price, estimated delivery date, tracking information, method (for example, Ground, Overnight, or Pick-up), carrier (for example, USPS, UPS, FedEx), and current status (for example, Not Shipped, In Transit, Delayed, or Returned To Sender).
Payment transaction associated with this order. It is the entire payment interchange between the merchant who is forwarding the customer's payment information and the payment service who is authorizing and capturing payment. Payment can be either by credit card, check, or PayPal.
Refunds associated with this order. A refund is a single exchange of money from merchant to customer that either encapsulates a refund to a credit card or an issuance of a store credit. Refunds does not reduce the 'amount collected' on an order and it is possible for refunds to exceed the total order amount.