Order Versioning

In this document, you’ll learn how orders and their details are versioned.

What is Order Versioning?#

Versioning means assigning a version number to a record, such as an order and its items. This is useful for viewing the different versions of an order following changes throughout its lifetime.

When changes are confirmed on an order, such as when an item is added or returned, the order's version changes.

version Property#

The Order and OrderSummary data models have a version property that indicates the current version. By default, its value is 1.

Other order-related data models, such as OrderItem, also have a version property, but it indicates the version to which the record belongs.

How the Version Changes#

When the order is changed, such as when an item is exchanged, Medusa updates the order's version and its related data:

1. The version of the order and its summary is incremented.
2. Related order data that have a version property, such as OrderItem, are duplicated. The duplicated item has the new version, while the original item retains the previous version.

When the order is retrieved, only the related data with the same version is returned.

Retrieve Versioned Item Details#

An order's item is stored across two data models:

• The OrderLineItem data model holds the item's original details, such as its title and the price at the time of purchase. This record is not versioned.
• The OrderItem data model links the line item to an order version. It holds the versioned quantity, unit_price, compare_at_unit_price, and metadata of the item in that version.

When an order edit, claim, exchange, or return changes an item's quantity, price, or metadata, the Order Module writes the new values to the OrderItem record of the new version. The OrderLineItem record keeps its original values.

Retrieved Item Shape#

When you retrieve an order, the Order Module merges both records into each item of the items property. The item's quantity, unit_price, compare_at_unit_price, and metadata hold the values of the order's current version, and the remaining properties come from the line item.

The merged item also has the following properties:

• detail: the OrderItem record of the current version. Use properties like detail.unit_price and detail.metadata to read the versioned values directly.
• line_item_metadata: the metadata of the OrderLineItem record, which is the metadata set when the item was first added to the order.

For example, retrieve an order's versioned item details using Query:

Code
1const { data: orders } = await query.graph({2  entity: "order",3  fields: [4    "items.unit_price",5    "items.metadata",6    "items.detail.unit_price",7    "items.detail.metadata",8    "items.line_item_metadata",9  ],10  filters: {11    id: orderId,12  },13})