ContextQMD
Back to Medusa

{metadata.title}

www/apps/resources/app/commerce-modules/loyalty/links-to-other-modules/page.mdx

2.14.28.6 KB
Original Source

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

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

{metadata.title}

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

<Prerequisites items={[ { text: "Loyalty Plugin Installed", link: "../page.mdx#1-install-the-loyalty-plugin", } ]} />

Summary

The Loyalty 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> [Cart](/references/cart/models/Cart) in [Cart Module](../../cart/page.mdx) </Table.Cell> <Table.Cell> `GiftCard` in [Loyalty Module](../page.mdx) </Table.Cell> <Table.Cell> Stored - many-to-many </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> `GiftCard` in [Loyalty Module](../page.mdx) </Table.Cell> <Table.Cell> Stored - many-to-many </Table.Cell> <Table.Cell> [Learn more](#order-module) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `GiftCard` in [Loyalty Module](../page.mdx) </Table.Cell> <Table.Cell> [OrderLineItem](/references/order/models/OrderLineItem) in [Order Module](../../order/page.mdx) </Table.Cell> <Table.Cell> Read-only </Table.Cell> <Table.Cell> [Learn more](#gift-card-and-order-line-item) </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `GiftCard` in [Loyalty Module](../page.mdx) </Table.Cell> <Table.Cell> `StoreCreditAccount` in [Store Credit Module](../../store-credit/page.mdx) </Table.Cell> <Table.Cell> Stored - many-to-one </Table.Cell> <Table.Cell> [Learn more](#store-credit-module) </Table.Cell> </Table.Row> </Table.Body> </Table>

Cart Module

When a customer applies a gift card during checkout, Medusa defines a link between the Cart and GiftCard data models.

This allows you to retrieve the gift cards applied on a cart.

Retrieve with Query

To retrieve the gift cards of a cart with Query, pass gift_cards.* in fields:

<CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">
ts
const { data: carts } = await query.graph({
  entity: "cart",
  fields: [
    "gift_cards.*",
  ],
})

// carts[0].gift_cards
</CodeTab> <CodeTab label="useQueryGraphStep" value="step">
ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

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

// carts[0].gift_cards
</CodeTab> </CodeTabs>

To manage the gift cards of a cart, use Link:

<CodeTabs group="relation-link"> <CodeTab label="link.create" value="method">
ts
import { Modules } from "@medusajs/framework/utils"

// ...

await link.create({
  [Modules.CART]: {
    cart_id: "cart_123",
  },
  loyalty: {
    gift_card_id: "gcard_123",
  },
})
</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">
ts
import { Modules } from "@medusajs/framework/utils"
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  [Modules.CART]: {
    cart_id: "cart_123",
  },
  loyalty: {
    gift_card_id: "gcard_123",
  },
})
</CodeTab> </CodeTabs>

Order Module

Order and Gift Cards

When a customer places an order that includes gift cards, Medusa defines a link between the Order and GiftCard data models.

This allows you to retrieve the gift cards applied on an order.

Retrieve with Query

To retrieve the gift cards of an order with Query, pass gift_cards.* in fields:

<CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">
ts
const { data: orders } = await query.graph({
  entity: "order",
  fields: [
    "gift_cards.*",
  ],
})

// orders[0].gift_cards
</CodeTab> <CodeTab label="useQueryGraphStep" value="step">
ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

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

// orders[0].gift_cards
</CodeTab> </CodeTabs>

Manage with Link

To manage the gift cards of an order, use 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",
  },
  loyalty: {
    gift_card_id: "gcard_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",
  },
  loyalty: {
    gift_card_id: "gcard_123",
  },
})
</CodeTab> </CodeTabs>

Gift Card and Order Line Item

Medusa defines a read-only link between the GiftCard data model and the Order Module's OrderLineItem data model. This means you can retrieve the order line item where the gift card was purchased, but you don't manage the links in a pivot table in the database. The line item of a gift card is determined by the line_item_id property of the GiftCard data model.

Retrieve with Query

To retrieve the order line item of a gift card with Query, pass line_item.* in fields:

<CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">
ts
const { data: giftCards } = await query.graph({
  entity: "gift_card",
  fields: [
    "line_item.*",
  ],
})

// giftCards[0].line_item
</CodeTab> <CodeTab label="useQueryGraphStep" value="step">
ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: giftCards } = useQueryGraphStep({
  entity: "gift_card",
  fields: [
    "line_item.*",
  ],
})

// giftCards[0].line_item
</CodeTab> </CodeTabs>

Store Credit Module

Medusa defines a link between the GiftCard and StoreCreditAccount from the Store Credit Module. This link is created when a gift card is created (alongside its store credit account) or when a gift card is redeemed.

This allows you to retrieve the store credit account associated with a gift card.

Retrieve with Query

To retrieve the store credit account of a gift card with Query, pass store_credit_account.* in fields:

<CodeTabs group="relation-query"> <CodeTab label="query.graph" value="method">
ts
const { data: giftCards } = await query.graph({
  entity: "gift_card",
  fields: [
    "store_credit_account.*",
  ],
})

// giftCards[0].store_credit_account
</CodeTab> <CodeTab label="useQueryGraphStep" value="step">
ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"

// ...

const { data: giftCards } = useQueryGraphStep({
  entity: "gift_card",
  fields: [
    "store_credit_account.*",
  ],
})

// giftCards[0].store_credit_account
</CodeTab> </CodeTabs>

To manage the store credit account of a gift card, use Link:

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

await link.create({
  loyalty: {
    gift_card_id: "gcard_123",
  },
  store_credit: {
    store_credit_account_id: "sc_acc_123",
  },
})
</CodeTab> <CodeTab label="createRemoteLinkStep" value="step">
ts
import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"

// ...

createRemoteLinkStep({
  loyalty: {
    gift_card_id: "gcard_123",
  },
  store_credit: {
    store_credit_account_id: "sc_acc_123",
  },
})
</CodeTab> </CodeTabs>