---
products:
  - order
  - pricing
  - product
  - stock location
---

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

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

# {metadata.title}

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

## Summary

The Fulfillment Module has the following links to other modules:

<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>
        [ShippingMethod](/references/cart/models/ShippingMethod) in [Cart Module](../../cart/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [ShippingOption](/references/fulfillment/models/ShippingOption)
      </Table.Cell>
      <Table.Cell>
        Read-only - has one
      </Table.Cell>
      <Table.Cell>
        [Learn more](#cart-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [Order](/references/order/models/Order) in [Order Module](../../order/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [Fulfillment](/references/fulfillment/models/Fulfillment)
      </Table.Cell>
      <Table.Cell>
        Stored - one-to-many
      </Table.Cell>
      <Table.Cell>
        [Learn more](#order-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [Return](/references/order/models/Return) in [Order Module](../../order/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [Fulfillment](/references/fulfillment/models/Fulfillment)
      </Table.Cell>
      <Table.Cell>
        Stored - one-to-many
      </Table.Cell>
      <Table.Cell>
        [Learn more](#order-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [PriceSet](/references/pricing/models/PriceSet) in [Pricing Module](../../pricing/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [ShippingOption](/references/fulfillment/models/ShippingOption)
      </Table.Cell>
      <Table.Cell>
        Stored - many-to-one
      </Table.Cell>
      <Table.Cell>
        [Learn more](#pricing-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [Product](/references/product/models/Product) in [Product Module](../../product/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [ShippingProfile](/references/fulfillment/models/ShippingProfile)
      </Table.Cell>
      <Table.Cell>
        Stored - many-to-one
      </Table.Cell>
      <Table.Cell>
        [Learn more](#product-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [StockLocation](/references/stock-location-next/models/StockLocation) in [Stock Location Module](../../stock-location/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [FulfillmentProvider](/references/fulfillment/models/FulfillmentProvider)
      </Table.Cell>
      <Table.Cell>
        Stored - one-to-many
      </Table.Cell>
      <Table.Cell>
        [Learn more](#stock-location-module)
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        [StockLocation](/references/stock-location-next/models/StockLocation) in [Stock Location Module](../../stock-location/page.mdx)
      </Table.Cell>
      <Table.Cell>
        [FulfillmentSet](/references/fulfillment/models/FulfillmentSet)
      </Table.Cell>
      <Table.Cell>
        Stored - one-to-many
      </Table.Cell>
      <Table.Cell>
        [Learn more](#stock-location-module)
      </Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

---

## Cart Module

Medusa defines a read-only link between the `ShippingMethod` data model of the [Cart Module](../../cart/page.mdx) and the `ShippingOption` data model. This means you can retrieve the details of a shipping method's shipping option, but you don't manage the links in a pivot table in the database. The shipping option of a shipping method is determined by the `shipping_option_id` property of the `ShippingMethod` data model.

This link allows you to retrieve the shipping option that a shipping method was created from.

<Note>

This read-only link was added in [Medusa v2.10.0](https://github.com/medusajs/medusa/releases/tag/v2.10.0)

</Note>

### Retrieve with Query

To retrieve the shipping option of a shipping method with [Query](!docs!/learn/fundamentals/module-links/query), pass `shipping_option.*` in `fields`:

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

```ts
const { data: shippingMethods } = await query.graph({
  entity: "shipping_method",
  fields: [
    "shipping_option.*",
  ],
})

// shippingMethods[0].shipping_option
```

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

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

// ...

const { data: shippingMethods } = useQueryGraphStep({
  entity: "shipping_method",
  fields: [
    "shipping_option.*",
  ],
})

// shippingMethods[0].shipping_option
```

  </CodeTab>
</CodeTabs>

---

## Order Module

The [Order Module](../../order/page.mdx) provides order-management functionalities.

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

![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)

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

![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399052/Medusa%20Resources/Social_Media_Graphics_2024_Order_Return_vetimk.jpg)

### Retrieve with Query

To retrieve the order of a fulfillment with [Query](!docs!/learn/fundamentals/module-links/query), pass `order.*` in `fields`:

<Note>

To retrieve the return, pass `return.*` in `fields`.

</Note>

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

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

// fulfillments.order
```

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

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

// ...

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

// fulfillments.order
```

  </CodeTab>
</CodeTabs>

### Manage with Link

To manage the order of a cart, use [Link](!docs!/learn/fundamentals/module-links/link):

<CodeTabs group="relation-link">
  <CodeTab label="link.create" value="method">

```ts
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">

```ts
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>

---

## Pricing Module

The Pricing Module provides features to store, manage, and retrieve the best prices in a specified context.

Medusa defines a link between the `PriceSet` and `ShippingOption` data models. A shipping option's price is stored as a price set.

![A diagram showcasing an example of how data models from the Pricing and Fulfillment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716561747/Medusa%20Resources/pricing-fulfillment_spywwa.jpg)

### Retrieve with Query

To retrieve the price set of a shipping option with [Query](!docs!/learn/fundamentals/module-links/query), pass `price_set.*` in `fields`:

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

```ts
const { data: shippingOptions } = await query.graph({
  entity: "shipping_option",
  fields: [
    "price_set_link.*",
  ],
})

// shippingOptions[0].price_set_link?.price_set_id
```

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

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

// ...

const { data: shippingOptions } = useQueryGraphStep({
  entity: "shipping_option",
  fields: [
    "price_set_link.*",
  ],
})

// shippingOptions[0].price_set_link?.price_set_id
```

  </CodeTab>
</CodeTabs>

### Manage with Link

To manage the price set of a shipping option, use [Link](!docs!/learn/fundamentals/module-links/link):

<CodeTabs group="relation-link">
  <CodeTab label="link.create" value="method">

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

// ...

await link.create({
  [Modules.FULFILLMENT]: {
    shipping_option_id: "so_123",
  },
  [Modules.PRICING]: {
    price_set_id: "pset_123",
  },
})
```

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

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

// ...

createRemoteLinkStep({
  [Modules.FULFILLMENT]: {
    shipping_option_id: "so_123",
  },
  [Modules.PRICING]: {
    price_set_id: "pset_123",
  },
})
```

  </CodeTab>
</CodeTabs>

---

## Product Module

Medusa defines a link between the `ShippingProfile` data model and the `Product` data model of the Product Module. Each product must belong to a shipping profile.

<Note>

This link is introduced in [Medusa v2.5.0](https://github.com/medusajs/medusa/releases/tag/v2.5.0).

</Note>

### Retrieve with Query

To retrieve the products of a shipping profile with [Query](!docs!/learn/fundamentals/module-links/query), pass `products.*` in `fields`:

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

```ts
const { data: shippingProfiles } = await query.graph({
  entity: "shipping_profile",
  fields: [
    "products.*",
  ],
})

// shippingProfiles[0].products
```

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

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

// ...

const { data: shippingProfiles } = useQueryGraphStep({
  entity: "shipping_profile",
  fields: [
    "products.*",
  ],
})

// shippingProfiles[0].products
```

  </CodeTab>
</CodeTabs>

### Manage with Link

To manage the shipping profile of a product, use [Link](!docs!/learn/fundamentals/module-links/link):

<CodeTabs group="relation-link">
  <CodeTab label="link.create" value="method">

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

// ...

await link.create({
  [Modules.PRODUCT]: {
    product_id: "prod_123",
  },
  [Modules.FULFILLMENT]: {
    shipping_profile_id: "sp_123",
  },
})
```

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

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

// ...

createRemoteLinkStep({
  [Modules.PRODUCT]: {
    product_id: "prod_123",
  },
  [Modules.FULFILLMENT]: {
    shipping_profile_id: "sp_123",
  },
})
```

  </CodeTab>
</CodeTabs>

---

## Stock Location Module

The Stock Location Module provides features to manage stock locations in a store.

Medusa defines a link between the `FulfillmentSet` and `StockLocation` data models. A fulfillment set can be conditioned to a specific stock location.

![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712567101/Medusa%20Resources/fulfillment-stock-location_nlkf7e.jpg)

Medusa also defines a link between the `FulfillmentProvider` and `StockLocation` data models to indicate the providers that can be used in a location.

![A diagram showcasing an example of how data models from the Fulfillment and Stock Location modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399492/Medusa%20Resources/fulfillment-provider-stock-location_b0mulo.jpg)

### Retrieve with Query

To retrieve the stock location of a fulfillment set with [Query](!docs!/learn/fundamentals/module-links/query), pass `location.*` in `fields`:

<Note>

To retrieve the stock location of a fulfillment provider, pass `locations.*` in `fields`.

</Note>

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

```ts
const { data: fulfillmentSets } = await query.graph({
  entity: "fulfillment_set",
  fields: [
    "location.*",
  ],
})

// fulfillmentSets[0].location
```

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

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

// ...

const { data: fulfillmentSets } = useQueryGraphStep({
  entity: "fulfillment_set",
  fields: [
    "location.*",
  ],
})

// fulfillmentSets[0].location
```

  </CodeTab>
</CodeTabs>

### Manage with Link

To manage the stock location of a fulfillment set, use [Link](!docs!/learn/fundamentals/module-links/link):

<CodeTabs group="relation-link">
  <CodeTab label="link.create" value="method">

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

// ...

await link.create({
  [Modules.STOCK_LOCATION]: {
    stock_location_id: "sloc_123",
  },
  [Modules.FULFILLMENT]: {
    fulfillment_set_id: "fset_123",
  },
})
```

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

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

// ...

createRemoteLinkStep({
  [Modules.STOCK_LOCATION]: {
    stock_location_id: "sloc_123",
  },
  [Modules.FULFILLMENT]: {
    fulfillment_set_id: "fset_123",
  },
})
```

  </CodeTab>
</CodeTabs>