import { CodeTabs, CodeTab, Table } from "docs-ui"

export const metadata = { title: Links between Order Module and Other Modules, }

{metadata.title}

This document showcases the module links defined between the Order Module and other Commerce Modules.

Summary

The Order Module has the following links to other modules:

Read-only links are used to query data across modules, but the relations aren't stored in a pivot table in the database.

</Note> <Table> <Table.Header> <Table.Row> <Table.HeaderCell> First Data Model </Table.HeaderCell> <Table.HeaderCell> Second Data Model </Table.HeaderCell> <Table.HeaderCell> Type </Table.HeaderCell> <Table.HeaderCell> Description </Table.HeaderCell> </Table.Row> </Table.Header> <Table.Body> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [Customer](/references/customer/models/Customer) in [Customer Module](../../customer/page.mdx) </Table.Cell> <Table.Cell> Read-only - has one </Table.Cell> <Table.Cell> [Learn more](#customer-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [Cart](/references/cart/models/Cart) in [Cart Module](../../cart/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-one </Table.Cell> <Table.Cell> [Learn more](#cart-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [Fulfillment](/references/fulfillment/models/Fulfillment) in [Fulfillment Module](../../fulfillment/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-many </Table.Cell> <Table.Cell> [Learn more](#fulfillment-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Return](/references/order/models/Return) </Table.Cell> <Table.Cell> [Fulfillment](/references/fulfillment/models/Fulfillment) in [Fulfillment Module](../../fulfillment/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-many </Table.Cell> <Table.Cell> [Learn more](#fulfillment-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [PaymentCollection](/references/payment/models/PaymentCollection) in [Payment Module](../../payment/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-many </Table.Cell> <Table.Cell> [Learn more](#payment-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [OrderClaim](/references/order/models/OrderClaim) </Table.Cell> <Table.Cell> [PaymentCollection](/references/payment/models/PaymentCollection) in [Payment Module](../../payment/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-many </Table.Cell> <Table.Cell> [Learn more](#payment-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [OrderExchange](/references/order/models/OrderExchange) </Table.Cell> <Table.Cell> [PaymentCollection](/references/payment/models/PaymentCollection) in [Payment Module](../../payment/page.mdx) </Table.Cell> <Table.Cell> Stored - one-to-many </Table.Cell> <Table.Cell> [Learn more](#payment-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [OrderLineItem](/references/order/models/OrderLineItem) </Table.Cell> <Table.Cell> [Product](/references/product/models/Product) in [Product Module](../../product/page.mdx) </Table.Cell> <Table.Cell> Read-only - has many </Table.Cell> <Table.Cell> [Learn more](#product-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [Promotion](/references/promotion/models/Promotion) in [Promotion Module](../../promotion/page.mdx) </Table.Cell> <Table.Cell> Stored - many-to-many </Table.Cell> <Table.Cell> [Learn more](#promotion-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [Region](/references/region/models/Region) in [Region Module](../../region/page.mdx) </Table.Cell> <Table.Cell> Read-only - has one </Table.Cell> <Table.Cell> [Learn more](#region-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> [Order](/references/order/models/Order) </Table.Cell> <Table.Cell> [SalesChannel](/references/sales-channel/models/SalesChannel) in [Sales Channel Module](../../sales-channel/page.mdx) </Table.Cell> <Table.Cell> Read-only - has one </Table.Cell> <Table.Cell> [Learn more](#sales-channel-module) </Table.Cell> </Table.Row> </Table.Body> </Table>

Customer Module

Medusa defines a read-only link between the Order data model and the Customer Module's Customer data model. This means you can retrieve the details of an order's customer, but you don't manage the links in a pivot table in the database. The customer of an order is determined by the customer_id property of the Order data model.

Retrieve with Query

To retrieve the customer of an order with Query, pass customer.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "customer.*",
  ],
})

// orders[0].customer

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "customer.*",
  ],
})

// orders[0].customer

</CodeTab> </CodeTabs>

Cart Module

The Cart Module provides cart-management features.

Medusa defines a link between the Order and Cart data models. The order is linked to the cart used for the purchased.

Retrieve with Query

To retrieve the cart of an order with Query, pass cart.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "cart.*",
  ],
})

// orders[0].cart

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "cart.*",
  ],
})

// orders[0].cart

</CodeTab> </CodeTabs>

Manage with Link

To manage the cart of an order, use Link:

import { Modules } from "@medusajs/framework/utils"

// ...

await link.create({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.CART]: {
    cart_id: "cart_123",
  },
})

</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">

import { Modules } from "@medusajs/framework/utils"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.CART]: {
    cart_id: "cart_123",
  },
})

</CodeTab> </CodeTabs>

Fulfillment Module

A fulfillment is created for an orders' items. Medusa defines a link between the Fulfillment and Order data models.

A fulfillment is also created for a return's items. So, Medusa defines a link between the Fulfillment and Return data models.

Retrieve with Query

To retrieve the fulfillments of an order with Query, pass fulfillments.* in fields:

<Note>

To retrieve the fulfillments of a return, pass fulfillments.* in fields.

</Note> <CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "fulfillments.*",
  ],
})

// orders[0].fulfillments

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "fulfillments.*",
  ],
})

// orders[0].fulfillments

</CodeTab> </CodeTabs>

Manage with Link

To manage the fulfillments of an order, use Link:

import { Modules } from "@medusajs/framework/utils"

// ...

await link.create({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.FULFILLMENT]: {
    fulfillment_id: "ful_123",
  },
})

</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">

import { Modules } from "@medusajs/framework/utils"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.FULFILLMENT]: {
    fulfillment_id: "ful_123",
  },
})

</CodeTab> </CodeTabs>

Payment Module

An order's payment details are stored in a payment collection. This also applies for claims and exchanges.

So, Medusa defines links between the PaymentCollection data model and the Order, OrderClaim, and OrderExchange data models.

Retrieve with Query

To retrieve the payment collections of an order, order exchange, or order claim with Query, pass payment_collections.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "payment_collections.*",
  ],
})

// orders[0].payment_collections

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "payment_collections.*",
  ],
})

// orders[0].payment_collections

</CodeTab> </CodeTabs>

Manage with Link

To manage the payment collections of an order, use Link:

import { Modules } from "@medusajs/framework/utils"

// ...

await link.create({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.PAYMENT]: {
    payment_collection_id: "paycol_123",
  },
})

</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">

import { Modules } from "@medusajs/framework/utils"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.PAYMENT]: {
    payment_collection_id: "paycol_123",
  },
})

</CodeTab> </CodeTabs>

Product Module

Medusa defines read-only links between:

the OrderLineItem data model and the Product Module's Product data model. This means you can retrieve the details of a line item's product, but you don't manage the links in a pivot table in the database. The product of a line item is determined by the product_id property of the OrderLineItem data model.
the OrderLineItem data model and the Product Module's ProductVariant data model. This means you can retrieve the details of a line item's variant, but you don't manage the links in a pivot table in the database. The variant of a line item is determined by the variant_id property of the OrderLineItem data model.

Retrieve with Query

To retrieve the variant of a line item with Query, pass variant.* in fields:

<Note>

To retrieve the product, pass product.* in fields.

</Note> <CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">

const { data: lineItems } = await query.graph({
  entity: "order_line_item",
  fields: [
    "variant.*",
  ],
})

// lineItems.variant

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: lineItems } = useQueryGraphStep({
  entity: "order_line_item",
  fields: [
    "variant.*",
  ],
})

// lineItems.variant

</CodeTab> </CodeTabs>

Promotion Module

An order is associated with the promotion applied on it. Medusa defines a link between the Order and Promotion data models.

Retrieve with Query

To retrieve the promotion applied on an order with Query, pass promotion.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "promotions.*",
  ],
})

// orders[0].promotions

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "promotions.*",
  ],
})

// orders[0].promotions

</CodeTab> </CodeTabs>

Manage with Link

To manage the promotion of an order, use Link:

import { Modules } from "@medusajs/framework/utils"

// ...

await link.create({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.PROMOTION]: {
    promotion_id: "promo_123",
  },
})

</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">

import { Modules } from "@medusajs/framework/utils"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  [Modules.ORDER]: {
    order_id: "order_123",
  },
  [Modules.PROMOTION]: {
    promotion_id: "promo_123",
  },
})

</CodeTab> </CodeTabs>

Region Module

Medusa defines a read-only link between the Order data model and the Region Module's Region data model. This means you can retrieve the details of an order's region, but you don't manage the links in a pivot table in the database. The region of an order is determined by the region_id property of the Order data model.

Retrieve with Query

To retrieve the region of an order with Query, pass region.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "region.*",
  ],
})

// orders[0].region

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "region.*",
  ],
})

// orders[0].region

</CodeTab> </CodeTabs>

Sales Channel Module

Medusa defines a read-only link between the Order data model and the Sales Channel Module's SalesChannel data model. This means you can retrieve the details of an order's sales channel, but you don't manage the links in a pivot table in the database. The sales channel of an order is determined by the sales_channel_id property of the Order data model.

Retrieve with Query

To retrieve the sales channel of an order with Query, pass sales_channel.* in fields:

const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "sales_channel.*",
  ],
})

// orders[0].sales_channel

</CodeTab> <CodeTab label="useQueryGraphStep" value="step">

import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: orders } = useQueryGraphStep({
  entity: "order",
  fields: [
    "sales_channel.*",
  ],
})

// orders[0].sales_channel

</CodeTab> </CodeTabs>