# Order Edits Order Edits allow you to make financial changes to the purchase agreement after the Order has been placed. Order Edits are entities which can hold one or more proposed financial changes to an Order. Before being applied, the Order Edit can be previewed to understand how the changes will affect an Order. If no financial aspect of an Order should be changed, you can directly update the Order using update actions and the [Update Order](/api/projects/orders.md#update-order) endpoint. For more information, see [Update an Order](/api/carts-orders-overview.md#update-an-order). A maximum of **100000** OrderEdits can exist per [Project](/api/projects/project.md). This is a soft limit that can be increased per Project after a performance impact review. See [Limit increase guidance](/api/limit-increase-guidance.md#resource-count-limits). ## Representations Representations are JSON objects submitted or received as payload to API requests or responses. #### OrderEdit [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEdit). ##### OrderEditDraft [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditDraft). ##### OrderEditPagedQueryResponse [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditPagedQueryResponse). #### OrderEditResult Indicates the current state of an Order Edit. The `result` field cannot be queried when the state is [PreviewSuccess](/api/projects/order-edits.md#orderedit-previewsuccess) or [PreviewFailure](/api/projects/order-edits.md#orderedit-previewfailure) as these results are dynamically generated. ##### OrderEdit NotProcessed [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditNotProcessed). ##### OrderEdit PreviewSuccess [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditPreviewSuccess). If Reference Expansion is used on the `resource` field, a race condition can occur if the Order is updated after the preview is calculated but before `resource` is expanded. In that case, the preview is based on an older version of the Order. This rare case can be detected when the `messagePayloads` contains an [OrderEditApplied](/urn?urn=ctp%3Aapi%3Atype%3AOrderEditApplied) Message with a different Order version than the expanded Order in `excerptBeforeEdit`. ##### OrderEdit PreviewFailure [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditPreviewFailure). ##### OrderEdit Applied [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditApplied). #### OrderExcerpt [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderExcerpt). #### OrderMessagePayload An [Order Message](/api/projects/messages/cart-order-messages.md#order-messages) payload without the common [Message](/urn?urn=ctp%3Aapi%3Atype%3AMessage) fields apart from the Message `type`. ## Get OrderEdit ### Get OrderEdit by ID [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/\{id}:GET). ### Get OrderEdit by Key [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/key=\{key}:GET). ## Query OrderEdits [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits:GET). ## Check if OrderEdit exists ### Check if OrderEdit exists by ID [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/\{id}:HEAD). ### Check if OrderEdit exists by Key [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/key=\{key}:HEAD). ### Check if OrderEdit exists by Query Predicate [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits:HEAD). ## Create OrderEdit [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits:POST). ## Update OrderEdit The `stagedActions` field cannot be updated if the Order Edit `result` is [OrderEdit Applied](/api/projects/order-edits.md#orderedit-applied). ### Update OrderEdit by ID [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/\{id}:POST). ### Update OrderEdit by Key [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/key=\{key}:POST). ## Update actions #### Set Key [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditSetKeyAction). #### Set StagedActions [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditSetStagedActionsAction). #### Add StagedAction [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditAddStagedActionAction). #### Set Comment [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditSetCommentAction). #### Set Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditSetCustomTypeAction). #### Set CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:OrderEditSetCustomFieldAction). ## StagedOrderUpdateActions If Embedded or Standalone Prices have changed since an Order was created, editing the Order will apply the updated prices to all Line Items—even if the edit does not directly modify the prices. If one or more Line Items do not contain an Embedded Price or Standalone Price that matches the Line Item price selection criteria of the Order, they are removed during Order Edit operations. This scenario can occur when: - You use the [Create Order by Import](/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Forders%2Fimport%3APOST) endpoint. This is because the endpoint does not validate prices during the Order creation process. When the Order is later modified using an Order Edit, the invalid prices are detected, and the corresponding Line Items are removed. - The price used in the Order is deleted, and no other matching price exists. You can stage the following update actions to an OrderEdit: #### on Order ##### Set Order Number [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetOrderNumberAction). ##### Set Purchase Order Number [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetPurchaseOrderNumberAction). ##### Set Business Unit [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetBusinessUnitAction). ##### Set Customer ID [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomerIdAction). ##### Set Customer Email [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomerEmailAction). ##### Set Customer Group [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomerGroupAction). ##### Add LineItem [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddLineItemAction). ##### Remove LineItem [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveLineItemAction). ##### Add CustomLineItem [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddCustomLineItemAction). ##### Remove CustomLineItem [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveCustomLineItemAction). ##### Add Shopping List [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddShoppingListAction). ##### Set Order Total Tax [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetOrderTotalTaxAction). ##### Change TaxMode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeTaxModeAction). ##### Change Price RoundingMode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangePriceRoundingModeAction). ##### Change Tax RoundingMode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeTaxRoundingModeAction). ##### Change TaxCalculationMode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeTaxCalculationModeAction). ##### Add DiscountCode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddDiscountCodeAction). ##### Remove DiscountCode [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveDiscountCodeAction). ##### Set DirectDiscounts [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDirectDiscountsAction). ##### Add Payment [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddPaymentAction). ##### Remove Payment [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemovePaymentAction). ##### Change PaymentState [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangePaymentStateAction). ##### Set Billing Address [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetBillingAddressAction). ##### Set Shipping Address [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingAddressAction). ##### Add ItemShippingAddress [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddItemShippingAddressAction). ##### Remove ItemShippingAddress [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveItemShippingAddressAction). ##### Update ItemShippingAddress [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderUpdateItemShippingAddressAction). ##### Set ShippingAddress and ShippingMethod [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingAddressAndShippingMethodAction). ##### Set ShippingAddress and Custom ShippingMethod [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingAddressAndCustomShippingMethodAction). ##### Set ShippingMethod [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingMethodAction). ##### Set Custom ShippingMethod [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomShippingMethodAction). ##### Set ShippingRateInput [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingRateInputAction). ##### Add Delivery [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddDeliveryAction). ##### Remove Delivery [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveDeliveryAction). ##### Change ShipmentState [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeShipmentStateAction). ##### Add ReturnInfo [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddReturnInfoAction). ##### Set ReturnInfo [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetReturnInfoAction). ##### Set ReturnShipmentState [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetReturnShipmentStateAction). ##### Set ReturnPaymentState [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetReturnPaymentStateAction). ##### Change OrderState [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeOrderStateAction). ##### Transition State [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderTransitionStateAction). ##### Update SyncInfo [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderUpdateSyncInfoAction). ##### Set Locale [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLocaleAction). ##### Set Country [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCountryAction). ##### Set Store [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetStoreAction). ##### Set Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomTypeAction). ##### Set CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomFieldAction). #### on Line Item ##### Change LineItem Quantity [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeLineItemQuantityAction). ##### Set LineItem TaxRate [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemTaxRateAction). ##### Set LineItem TaxAmount [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemTaxAmountAction). ##### Set LineItem Price [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemPriceAction). ##### Set LineItem TotalPrice [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemTotalPriceAction). ##### Set LineItem DistributionChannel [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemDistributionChannelAction). ##### Set LineItem ShippingDetails [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemShippingDetailsAction). ##### Set LineItem Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemCustomTypeAction). ##### Set LineItem CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetLineItemCustomFieldAction). ##### Transition LineItem State [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderTransitionLineItemStateAction). ##### Import LineItem State [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderImportLineItemStateAction). #### on Custom Line Item ##### Change CustomLineItem Quantity [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeCustomLineItemQuantityAction). ##### Set CustomLineItem TaxRate [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomLineItemTaxRateAction). ##### Set CustomLineItem TaxAmount [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomLineItemTaxAmountAction). ##### Change CustomLineItem Money [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderChangeCustomLineItemMoneyAction). ##### Set CustomLineItem ShippingDetails [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomLineItemShippingDetailsAction). ##### Set CustomLineItem Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomLineItemCustomTypeAction). ##### Set CustomLineItem CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetCustomLineItemCustomFieldAction). ##### Transition CustomLineItem State [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderTransitionCustomLineItemStateAction). ##### Import CustomLineItem State [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderImportCustomLineItemStateAction). #### on Billing Address ##### Set Billing Address Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetBillingAddressCustomTypeAction). ##### Set Billing Address CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetBillingAddressCustomFieldAction). #### on Shipping Address ##### Set Shipping Address Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingAddressCustomTypeAction). ##### Set Shipping Address CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingAddressCustomFieldAction). #### on ItemShipping Address ##### Set ItemShipping Address Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetItemShippingAddressCustomTypeAction). ##### Set ItemShipping Address CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetItemShippingAddressCustomFieldAction). #### on Shipping Method ##### Set ShippingMethod TaxAmount [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingMethodTaxAmountAction). ##### Set ShippingMethod TaxRate [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingMethodTaxRateAction). #### on Shipping ##### Set Shipping Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingCustomTypeAction). ##### Set Shipping CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetShippingCustomFieldAction). #### on Delivery ##### Set Delivery Address [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryAddressAction). ##### Add Parcel to Delivery [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderAddParcelToDeliveryAction). ##### Remove Parcel from Delivery [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderRemoveParcelFromDeliveryAction). ##### Set Delivery Items [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryItemsAction). ##### Set Delivery Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryCustomTypeAction). ##### Set Delivery CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryCustomFieldAction). #### on Delivery Address ##### Set Delivery Address Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryAddressCustomTypeAction). ##### Set Delivery Address CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetDeliveryAddressCustomFieldAction). #### on Parcel ##### Set Parcel Measurements [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetParcelMeasurementsAction). ##### Set Parcel Tracking Data [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetParcelTrackingDataAction). ##### Set Parcel Items [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetParcelItemsAction). ##### Set Parcel Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetParcelCustomTypeAction). ##### Set Parcel CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetParcelCustomFieldAction). #### on ReturnItem ##### Set ReturnItem Custom Type [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetReturnItemCustomTypeAction). ##### Set ReturnItem CustomField [type definition](/api/projects/order-edits.md?urn=ctp:api:type:StagedOrderSetReturnItemCustomFieldAction). ## Apply OrderEdit The `stagedActions` field cannot be updated if the Order Edit `result` is [OrderEdit Applied](/api/projects/order-edits.md#orderedit-applied). [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/\{id}/apply:POST). ## Delete OrderEdit ### Delete OrderEdit by ID Deleting an OrderEdit does not affect the related Order. [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/\{id}:DELETE). ### Delete OrderEdit by Key Deleting an Order Edit does not affect the related Order. [endpoint definition](/api/projects/order-edits.md?urn=ctp:api:endpoint:/\{projectKey}/orders/edits/key=\{key}:DELETE). ## Related pages - [Area overview page with navigation](/api.md) - [Previous page: Shopping Lists](/api/projects/shoppingLists.md) - [Next page: Order Import](/api/projects/orders-import.md)