Order Change

In this document, you’ll learn how to make changes to an order, such as return or exchange an item.

What's an Order Change?

An order change is modifying the order’s items for business purposes. For example, when a customer requests to return an item, or when you suggest exchanging an item with another.

Order changes are represented by the OrderChange data model.

---

Order Change Actions

An order change can have multiple underlying actions. For example, to exchange an item, you have to:

• Mark an item as returned.
• Arrange to receive the item from the customer.
• Add the new item to be sent to the customer.
• Fulfill the item and send it to the customer.

Each of these actions is represented by the OrderChangeAction data model.

Action Name

The action attribute of the OrderChangeAction holds the name of the action to perform. Based on the action, additional details are stored in the details object attribute of the data model.

Action Name	Description	Expected details
ITEM_ADD	Adds a new item to the order.	quantity: The quantity of the item to add. unit_price: The price of the item. reference_id: The ID of the item to add. For example: { quantity: 1; unit_price: 1000; reference_id: "orditem_123" }
ITEM_REMOVE	Removes an item from the order.	quantity: The quantity of the item to remove. unit_price: The price of the item. reference_id: The ID of the item to remove. For example: { quantity: 1; unit_price: 1000; reference_id: "orditem_123" }
WRITE_OFF_ITEM	Removes a quantity of an item.	quantity: The quantity to remove of the item. reference_id: The ID of the item to remove its quantity. { quantity: 1; reference_id: "orditem_123"}
RETURN_ITEM	Request a return of an item.	quantity: The quantity to return of the item. reference_id: The ID of the item to return. { quantity: 1; reference_id: "orditem_123"}
RECEIVE_RETURN_ITEM	Mark as received an item whose return was previously requested.	quantity: The quantity received of the item. reference_id: The ID of the item to mark its return as received. { quantity: 1; reference_id: "orditem_123"}
RECEIVE_DAMAGED_RETURN_ITEM	Mark as received an item whose return was previously requested, but consider the items damaged. This changes the order item’s return_dismissed_quantity attribute rather than its return_received_quantity attribute.	quantity: The quantity received of the item. reference_id: The ID of the item to mark its return as received. { quantity: 1; reference_id: "orditem_123"}
CANCEL_RETURN	Cancel a previously requested return of an item.	quantity: The quantity to cancel its return request. unit_price: The price of the item. reference_id: The ID of the item to cancel its return request. { quantity: 1; unit_price: 1000; reference_id: "orditem_123"}
SHIPPING_ADD	Add a shipping method to an item.	amount: The amount of the shipping. reference_id: The ID of the shipping method to add. { amount: 1000; reference_id: "orditem_123"}
SHIP_ITEM	Mark a quantity of an item as shipped. This modifies the shipped_quantity attribute of an order item.	quantity: The quantity of the item to ship. reference_id: The ID of the item to mark its specified quantity as shipped. { quantity: 1; reference_id: "ordli_123"}
FULFILL_ITEM	Mark a quantity of an item as fulfilled. This modifies the fulfilled_quantity attribute of an order item.	quantity: The quantity of the item to ship. reference_id: The ID of the item to mark its specified quantity as shipped. { quantity: 1; reference_id: "ordli_123"}
CANCEL	Cancel the order change.	Doesn’t expect any data.

Action Chaining

Actions are chained one after the other, similar to the example in the earlier section. This also allows you to cancel or undo some actions.

For example, if you request an order return with RETURN_ITEM action, you can later cancel it with the CANCEL_RETURN action.

The actions are ordered by the ordering attribute of the OrderChangeAction data model.

Action Amount

The OrderChangeAction data model has an amount attribute that indicates a change in the order’s amount that this action incurs.

---

Order Change Confirmation

The OrderChange data model has a status attribute that indicates its current status. By default, it’s pending. At this point, the order change’s actions aren’t applied to the order yet.

To apply these changes to the order, you must confirm the order change. When the order change is confirmed:

• The status of the order change is changed to confirmed.
• The order’s items are changed based on the order change’s actions. For example, an item is added, or an existing item’s quantity is changed.
• The order summary is modified to reflect new changes.

Note

If there are changes to the order’s total amount due to refunding or capturing payment, they must be added as transactions first. Otherwise, they won’t be accounted for when modifying the order summary