Medusa Commerce Modules

https://docs.medusajs.com/resources/commerce-modules
Admin
Medusa Commerce Modules provide out-of-the-box features for various commerce domains, exposing them...
Tokens:251,686
Snippets:2,005
Trust Score:9.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Promotion Application Example 2 (JSON)

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/application-method/index.html

Demonstrates a promotion with 'once' allocation and 'max_quantity' of 2 applied to a cart. The promotion is applied to the item with the lowest price first until the max quantity is reached.

```json
{
  "cart": {
    "items": [
      {
        "id": "item_1",
        "price": 10,
        "quantity": 3 
      },
      {
        "id": "item_2",
        "price": 20,
        "quantity": 4 
      }
    ]
  }
}
```

--------------------------------

### Example Cart with Multiple Items and Item Level Max Quantity

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/application-method/index.html

Illustrates the item-level `max_quantity` restriction in Medusa's Promotion Module when `allocation` is 'each'. This example shows a cart with two different items, and the promotion is applied to one quantity of each, regardless of their original quantities.

```json
{
  "cart": {
    "items": [
      {
        "id": "item_1",
        "quantity": 2 // The promotion is applied to 1 of this item
      },
      {
        "id": "item_2",
        "quantity": 3 // The promotion is applied to 1 of this item
      }
    ]
  }
}
```

--------------------------------

### Execute Create Price Set Workflow in API Route

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/index.html

Demonstrates how to execute the `createPriceSetWorkflow` within a Medusa API route. This example shows a GET request handler that runs the workflow and sends the result back in the response.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createPriceSetWorkflow } from "../../workflows/create-price-set"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createPriceSetWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Example Cart with Item Level Max Quantity Restriction

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/application-method/index.html

Demonstrates how the `max_quantity` property in an Application Method restricts the promotion application at the item level when `allocation` is 'each'. It shows a cart with two items, where the promotion is applied to only one quantity of each.

```json
{
  "cart": {
    "items": [
      {
        "id": "item_1",
        "quantity": 2 // The promotion is applied to 1 of this item
      }
    ]
  }
}
```

--------------------------------

### Execute Customer Creation Workflow in API Route (Medusa JS)

Source: https://docs.medusajs.com/resources/commerce-modules/customer/index.html

Demonstrates how to execute the `createCustomerWorkflow` within a Medusa API route handler. This example shows a GET request that triggers the workflow and sends the result back to the client. It utilizes Medusa's request and response types for handling HTTP requests.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createCustomerWorkflow } from "../../workflows/create-customer"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createCustomerWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Example JSON Response for Translated Products

Source: https://docs.medusajs.com/resources/commerce-modules/translation/storefront

An example of the JSON response when retrieving products with French (France) translations. It shows translated `title` and `description` fields.

```json
{
  "products": [
    {
      "id": "prod_123",
      "title": "Produit Exemple",
      "description": "Ceci est une description en français.",
      // other product fields...
    },
    // other products...
  ]
}
```

--------------------------------

### Execute Create Store Workflow in Medusa Subscriber

Source: https://docs.medusajs.com/resources/commerce-modules/store/index.html

Shows how to trigger the `createStoreWorkflow` from a Medusa subscriber. This example is set up to run when a 'user.created' event is emitted, demonstrating event-driven workflow execution.

```typescript
import {
  type SubscriberConfig,
  type SubscriberArgs,
} from "@medusajs/framework"
import { createStoreWorkflow } from "../workflows/create-store"

export default async function handleUserCreated({
  event: { data },
  container,
}: SubscriberArgs<{ id: string }>) {
  const { result } = await createStoreWorkflow(container)
    .run()

  console.log(result)
}

export const config: SubscriberConfig = {
  event: "user.created",
}
```

--------------------------------

### Add Prices using Medusa Pricing Module

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/price-rules/index.html

Shows how to add prices to a price set using the Medusa pricing module. This example configures prices with rules for customer groups, similar to the workflow example.

```typescript
const priceSet = await pricingModule.addPrices({
  priceSetId: "pset_shipping_456",
  prices: [
    // regular express shipping
    {
      currency_code: "usd",
      amount: 20,
      rules: {},
    },
    // VIP customer express shipping
    {
      currency_code: "usd",
      amount: 15,
      rules: {
        "customer.groups.id": [
          {
            operator: "in",
            value: ["cusgrp_vip123"],
          },
        ],
      },
    },
    // B2B customer express shipping
    {
      currency_code: "usd",
      amount: 13,
      rules: {
        "customer.groups.id": [
          {
            operator: "in",
            value: ["cusgrp_b2b789"],
          },
        ],
      },
    },
  ],
})
```

--------------------------------

### Create Promotion with Rules using Promotion Module Service

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/concepts/index.html

Illustrates creating a promotion with rules directly using the Promotion Module's service. This example restricts a 50% discount promotion to customers in the 'cusgrp_123' group. It utilizes the createPromotions method and defines the promotion details including its rules.

```typescript
const promotions = await promotionModuleService.createPromotions([
  {
    code: "50OFF",
    type: "standard",
    status: "active",
    application_method: {
      type: "percentage",
      target_type: "items",
      value: 50,
    },
    rules: [
      {
        attribute: "customer.group.id",
        operator: "eq",
        values: [
          "cusgrp_123",
        ],
      },
    ],
  },
])
```

--------------------------------

### Execute Workflow from API Route (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/translation/custom-data-models

TypeScript example showing how to execute the `handlePostsWorkflow` from a custom API route (`GET /store/posts`). It passes the request locale (`req.locale`) as input to the workflow.

```typescript
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { handlePostsWorkflow } from "../../workflows/handle-posts"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await handlePostsWorkflow(req.scope)
    .run({
      input: {
        locale: req.locale,
      },
    })

  res.json(result)
}
```

--------------------------------

### Retrieve Translated Data in API Routes (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/translation/custom-data-models

TypeScript example for a custom API route (`GET /store/posts`) that retrieves translated post titles. It accesses the request locale from `req.locale` and passes it to the query object.

```typescript
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve("query")

  const { data: posts } = await query.graph(
    {
      entity: "post",
      fields: ["id", "title"],
    },
    {
      locale: req.locale,
    }
  )

  res.json({ posts })
}
```

--------------------------------

### Create Product with Multi-Part Variants (JavaScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit

This workflow step creates a product and its variants, linking them to previously created inventory items. It uses `transform` to format inventory item IDs for the product variant and then employs `createProductsWorkflow` to define the product structure, including variants, prices, and options. Dependencies include the framework's workflow SDK and Medusa core flows.

```javascript
import {
  // ...
  transform,
} from "@medusajs/framework/workflows-sdk"
import {
  // ...
  createProductsWorkflow,
} from "@medusajs/medusa/core-flows"

export const createMultiPartProductsWorkflow = createWorkflow(
  "create-multi-part-products",
  () => {
    // ...

    const inventoryItemIds = transform({
      inventoryItems,
    }, (data) => {
      return data.inventoryItems.map((inventoryItem) => {
        return {
          inventory_item_id: inventoryItem.id,
          // can also specify required_quantity
        }
      })
    })

    const products = createProductsWorkflow.runAsStep({
      input: {
        products: [
          {
            title: "Bicycle",
            variants: [
              {
                title: "Bicycle - Small",
                prices: [
                  {
                    amount: 100,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                inventory_items: inventoryItemIds,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
            shipping_profile_id: "sp_123",
          },
        ],
      },
    })
  }
)
```

--------------------------------

### Example Cart with Cart Level Max Quantity Restriction (Once Allocation)

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/application-method/index.html

Shows how the `max_quantity` property limits the total number of items receiving a promotion when `allocation` is 'once'. In this example, with `max_quantity` set to 2, the promotion is applied to the two items with the lowest prices in the cart.

```json
{
  "cart": {
    "items": [
      {
        "id": "item_1",
        "price": 10,
        "quantity": 1 // The promotion is applied to this item
      },
      {
        "id": "item_2",
        "price": 20,
        "quantity": 1 // The promotion is applied to this item
      },
      {
        "id": "item_3",
        "price": 30,
        "quantity": 1 // The promotion is NOT applied to this item
      }
    ]
  }
}
```

--------------------------------

### Create Individual Products for Bundle (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit/index.html

This workflow step uses the `createProductsWorkflow` to create the individual products that will form a bundle. It ensures that inventory management is enabled for the variants of these products, which is a prerequisite for creating inventory kits later. The input includes product details like title, shipping profile, variants with prices, and options.

```typescript
import {
  createWorkflow,
} from "@medusajs/framework/workflows-sdk"
import {
  createProductsWorkflow,
} from "@medusajs/medusa/core-flows"

export const createBundledProducts = createWorkflow(
  "create-bundled-products",
  () => {
    const products = createProductsWorkflow.runAsStep({
      input: {
        products: [
          {
            title: "Shirt",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Shirt",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
          {
            title: "Pants",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Pants",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
          {
            title: "Shoes",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Shoes",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
        ],
      },
    })

    // TODO re-retrieve with inventory
  }
)

```

--------------------------------

### Create Promotion with Rules using createPromotionsWorkflow

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/concepts/index.html

Demonstrates how to create a promotion with specific rules using Medusa's createPromotionsWorkflow. This example restricts the promotion to customers belonging to a specific customer group ('cusgrp_123'). It requires the Medusa container and defines the promotion's code, type, status, application method, and rules.

```typescript
const { result } = await createPromotionsWorkflow(container)
  .run({
    input: {
      promotionsData: [{
        code: "10OFF",
        type: "standard",
        status: "active",
        application_method: {
          type: "percentage",
          target_type: "items",
          allocation: "across",
          value: 10,
          currency_code: "usd",
        },
        rules: [
          {
            attribute: "customer.group.id",
            operator: "eq",
            values: [
              "cusgrp_123",
            ],
          },
        ],
      }],
    },
  })
```

--------------------------------

### Create Individual Products for a Bundle (JavaScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit

This workflow step uses the `createProductsWorkflow` to create the individual products that will be part of a bundled product. It ensures that each variant of these products has inventory management enabled.

```javascript
import {
  createWorkflow,
} from "@medusajs/framework/workflows-sdk"
import {
  createProductsWorkflow,
} from "@medusajs/medusa/core-flows"

export const createBundledProducts = createWorkflow(
  "create-bundled-products",
  () => {
    const products = createProductsWorkflow.runAsStep({
      input: {
        products: [
          {
            title: "Shirt",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Shirt",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
          {
            title: "Pants",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Pants",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
          {
            title: "Shoes",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Shoes",
                prices: [
                  {
                    amount: 10,
                    currency_code: "usd",
                  },
                ],
                options: {
                  "Default Option": "Default Variant",
                },
                manage_inventory: true,
              },
            ],
            options: [
              {
                title: "Default Option",
                values: ["Default Variant"],
              },
            ],
          },
        ],
      },
    })

    // TODO re-retrieve with inventory
  }
)
```

--------------------------------

### Order Summary Totals Example - JSON

Source: https://docs.medusajs.com/resources/commerce-modules/order/transactions/index.html

This JSON snippet illustrates the structure of the `totals` property within an Order Summary, detailing the total and subtotal amounts for an order. It serves as a basis for calculating outstanding payment amounts.

```json
{
  "totals": {
    "total": 30,
    "subtotal": 30,
    "// ...": "other total details"
  }
}
```

--------------------------------

### Create Bundled Product (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit/index.html

This final workflow step creates the bundled product itself. It uses `createProductsWorkflow` and specifies the bundled product's details, including its variants. The key aspect here is that the variant's inventory will be managed via an inventory kit, which would be constructed using the `inventoryItemIds` retrieved in the previous step (though the exact construction of the inventory kit is omitted in this snippet).

```typescript
export const createBundledProducts = createWorkflow(
  "create-bundled-products",
  () => {
    // ...
    const bundledProduct = createProductsWorkflow.runAsStep({
      input: {
        products: [
          {
            title: "Bundled Clothes",
            shipping_profile_id: "sp_123",
            variants: [
              {
                title: "Bundle",
                prices: [
                  {

```

--------------------------------

### Retrieve Products with Inventory Items (JavaScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit

This step retrieves the previously created products, specifically fetching their variants and associated inventory items. This data is then transformed to extract the inventory item IDs needed for creating the bundled product.

```javascript
import {
  // ...
  transform,
} from "@medusajs/framework/workflows-sdk"
import {
  useQueryGraphStep,
} from "@medusajs/medusa/core-flows"

export const createBundledProducts = createWorkflow(
  "create-bundled-products",
  () => {
    // ...
    const productIds = transform({
      products,
    }, (data) => data.products.map((product) => product.id))

    // @ts-ignore
    const { data: productsWithInventory } = useQueryGraphStep({
      entity: "product",
      fields: [
        "variants.*",
        "variants.inventory_items.*",
      ],
      filters: {
        id: productIds,
      },
    })

    const inventoryItemIds = transform({
      productsWithInventory,
    }, (data) => {
      return data.productsWithInventory.map((product) => {
        return {
          inventory_item_id: product.variants[0].inventory_items?.[0]?.inventory_item_id,
        }
      })
    })

    // create bundled product
  }
)
```

--------------------------------

### Test Draft Orders Plugin with Yarn, PNPM, or NPM

Source: https://docs.medusajs.com/resources/commerce-modules/order/draft-orders

Commands to start the Medusa application in development mode after installing and configuring the Draft Orders Plugin. This allows you to access the 'Drafts' section in the Medusa Admin.

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
npm run dev
```

--------------------------------

### Compute Promotion Actions for Order Items and Shipping

Source: https://docs.medusajs.com/resources/commerce-modules/order/promotion-adjustments

This code snippet demonstrates how to retrieve an order, extract line item and shipping method adjustments, and then use the `computeActions` method from the Promotion Module's service to calculate applicable promotion actions. It requires the Order and Promotion modules to be installed and configured.

```javascript
const order = await orderModuleService.retrieveOrder("ord_123", {
  relations: [
    "items.item.adjustments",
    "shipping_methods.shipping_method.adjustments",
  ],
})

const lineItemAdjustments: ComputeActionItemLine[] = []
order.items.forEach((item) => {
  const filteredAdjustments = item.adjustments?.filter(
    (adjustment) => adjustment.code !== undefined
  ) as unknown as ComputeActionAdjustmentLine[]
  if (filteredAdjustments.length) {
    lineItemAdjustments.push({
      ...item,
      ...item.detail,
      adjustments: filteredAdjustments,
    })
  }
})

const shippingMethodAdjustments: ComputeActionShippingLine[] = []
order.shipping_methods.forEach((shippingMethod) => {
  const filteredAdjustments =
    shippingMethod.adjustments?.filter(
      (adjustment) => adjustment.code !== undefined
    ) as unknown as ComputeActionAdjustmentLine[]
  if (filteredAdjustments.length) {
    shippingMethodAdjustments.push({
      ...shippingMethod,
      adjustments: filteredAdjustments,
    })
  }
})

const actions = await promotionModuleService.computeActions(
  ["promo_123"],
  {
    items: lineItemAdjustments,
    shipping_methods: shippingMethodAdjustments,
    currency_code: "usd",
  }
)
```

--------------------------------

### Get Variant Availability using Store Route Sales Channel Scope (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/product/guides/variant-inventory

This snippet demonstrates how to retrieve variant inventory availability by using the sales channel scope available in store API routes. It accesses the `publishable_key_context.sales_channel_ids` from the request object to determine the relevant sales channel. This method is suitable for API routes starting with `/store` and requires a publishable API key in the request header.

```typescript
import { MedusaStoreRequest, MedusaResponse } from "@medusajs/framework/http"
import { getVariantAvailability } from "@medusajs/framework/utils"

export async function GET(
  req: MedusaStoreRequest,
  res: MedusaResponse
) {
  const query = req.scope.resolve("query")
  const sales_channel_ids = req.publishable_key_context.sales_channel_ids

  const availability = await getVariantAvailability(query, {
    variant_ids: ["variant_123"],
    sales_channel_id: sales_channel_ids[0],
  })

  res.json({
    availability,
  })
}
```

--------------------------------

### Pass Locale via Query Parameter or Header (cURL)

Source: https://docs.medusajs.com/resources/commerce-modules/translation/custom-data-models

Example cURL commands demonstrating how to pass the locale to API requests using either the `locale` query parameter or the `x-medusa-locale` header. Requires a publishable API key.

```bash
curl "http://localhost:9000/store/posts?locale=fr-FR" \
-H 'x-publishable-api-key: {your_publishable_api_key}'
```

--------------------------------

### Create and Use Price List for Pricing (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation/index.html

Demonstrates creating a price list with specific rules and prices, and then calculating prices using this price list in conjunction with a price set. This involves the pricing module service.

```typescript
const priceList = pricingModuleService.createPriceLists([{
  title: "Summer Price List",
  description: "Price list for summer sale",
  starts_at: Date.parse("01/10/2023").toString(),
  ends_at: Date.parse("31/10/2023").toString(),
  rules: {
    region_id: ['region_123', 'region_456'],
  },
  type: "sale",
  prices: [
    {
      amount: 2,
      currency_code: "eur",
      price_set_id: priceSet.id,
    },
    {
      amount: 1.5,
      currency_code: "usd",
      price_set_id: priceSet.id,
    }
  ],
}]);

const price = await pricingModuleService.calculatePrices(
  { id: [priceSet.id] },
  {
    context: {
      currency_code: "eur",
      region_id: "reg_123",
      city: "krakow"
    }
  }
)
```

--------------------------------

### Retrieve Products with Inventory Items (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit/index.html

This workflow step retrieves the previously created products, specifically fetching their variants and associated inventory items. This is crucial for gathering the necessary inventory item IDs required to construct the inventory kits for the bundled product. It uses a `useQueryGraphStep` with specific fields to ensure inventory data is included.

```typescript
import {
  transform,
} from "@medusajs/framework/workflows-sdk"
import {
  useQueryGraphStep,
} from "@medusajs/medusa/core-flows"

export const createBundledProducts = createWorkflow(
  "create-bundled-products",
  () => {
    // ...
    const productIds = transform({
      products,
    }, (data) => data.products.map((product) => product.id))

    // @ts-ignore
    const { data: productsWithInventory } = useQueryGraphStep({
      entity: "product",
      fields: [
        "variants.*",
        "variants.inventory_items.*",
      ],
      filters: {
        id: productIds,
      },
    })

    const inventoryItemIds = transform({
      productsWithInventory,
    }, (data) => {
      return data.productsWithInventory.map((product) => {
        return {
          inventory_item_id: product.variants[0].inventory_items?.[0]?.inventory_item_id,
        }
      })
    })

    // create bundled product
  }
)

```

--------------------------------

### Calculate Price with Partial Match Rules (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation/index.html

Calculates a price using partial rule matching, for example, matching a region ID and a city that might not be an exact match for all rules. This function is part of the pricing module service.

```typescript
const price = await pricingModuleService.calculatePrices(
  { id: [priceSet.id] },
  {
    context: {
      currency_code: "eur",
      region_id: "reg_123",
      city: "krakow"
    }
  }
)
```

--------------------------------

### Promotion Rule Example for Specific Customer ID

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/concepts/index.html

Presents a JSON object defining a promotion with a rule that restricts its application to a specific customer ID ('cus_123'). This demonstrates how promotion rules are structured, including the attribute to match, the operator (e.g., 'eq' for equals), and the values to compare against.

```json
{
  "code": "10OFF",
  "type": "standard",
  "status": "active",
  "application_method": {
    "type": "percentage",
    "target_type": "items",
    "allocation": "across",
    "value": 10,
    "currency_code": "usd"
  },
  "rules": [
    {
      "attribute": "customer_id",
      "operator": "eq",
      "values": [
        "cus_123"
      ]
    }
  ]
}
```

--------------------------------

### Compute Promotion Actions for Cart Items and Shipping Methods (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/cart/promotions

This snippet demonstrates how to retrieve a cart, extract adjustments from its line items and shipping methods, and then use the `computeActions` method from the promotion module service to calculate applicable promotion actions. It requires the `cartModuleService` and `promotionModuleService` to be available.

```typescript
import {
  ComputeActionItemLine,
  ComputeActionAdjustmentLine,
  ComputeActionShippingLine,
} from "@medusajs/medusa/dist/types/promotion";

// retrieve the cart
const cart = await cartModuleService.retrieveCart("cart_123", {
  relations: [
    "items.adjustments",
    "shipping_methods.adjustments",
  ],
});

// retrieve line item adjustments
const lineItemAdjustments: ComputeActionItemLine[] = [];
cart.items.forEach((item) => {
  const filteredAdjustments = item.adjustments?.filter(
    (adjustment) => adjustment.code !== undefined
  ) as unknown as ComputeActionAdjustmentLine[];
  if (filteredAdjustments.length) {
    lineItemAdjustments.push({
      ...item,
      adjustments: filteredAdjustments,
    });
  }
});

// retrieve shipping method adjustments
const shippingMethodAdjustments: ComputeActionShippingLine[] = [];
cart.shipping_methods.forEach((shippingMethod) => {
  const filteredAdjustments =
    shippingMethod.adjustments?.filter(
      (adjustment) => adjustment.code !== undefined
    ) as unknown as ComputeActionAdjustmentLine[];
  if (filteredAdjustments.length) {
    shippingMethodAdjustments.push({
      ...shippingMethod,
      adjustments: filteredAdjustments,
    });
  }
});

// compute actions
const actions = await promotionModuleService.computeActions(
  ["promo_123"],
  {
    items: lineItemAdjustments,
    shipping_methods: shippingMethodAdjustments,
  }
);
```

--------------------------------

### Execute Payment Collection Workflow in API Route - TypeScript

Source: https://docs.medusajs.com/resources/commerce-modules/payment

Demonstrates how to execute the 'create-payment-collection' workflow within a MedusaJS API route. It imports the workflow and runs it using the request scope, sending the result back in the response. This example is for a GET request handler.

```typescript
import { createPaymentCollectionWorkflow } from "../../workflows/create-payment-collection"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createPaymentCollectionWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Configure and Create Bundled Product in MedusaJS

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit/index.html

This code snippet demonstrates the configuration for creating a bundled product in MedusaJS. It includes defining product variants, pricing, options, and associating inventory items. The configuration is then used to create the bundled product using a workflow.

```javascript
medusa.product.create(
      {
        title: "Bundled Product",
        subtitle: "A bundle of awesome products",
        description: "Includes multiple products in one convenient package.",
        is_giftcard: false,
        discountable: true,
        type: {
          value: "bundle",
        },
        tags: [
          {
            value: "bundle",
          },
        ],
        images: [
          "https://example.com/bundle-image.jpg",
        ],
        variants: [
          {
            title: "Default Variant",
            sku: "BUNDLE-DEFAULT",
            allow_backorder: false,
            manage_inventory: true,
            weight: 1000,
            length: 20,
            width: 20,
            height: 10,
            metadata: {
              bundle: true,
            },
            prices: [
              {
                amount: 5000,
                currency_code: "usd",
              },
            ],
            options: {
              "Default Option": "Default Variant",
            },
            inventory_items: inventoryItemIds,
          },
        ],
        options: [
          {
            title: "Default Option",
            values: ["Default Variant"],
          },
        ],
      }
    ).config({ name: "create-bundled-product" })
```

--------------------------------

### Execute Inventory Creation Workflow via API Route in TypeScript

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/index.html

Demonstrates how to execute the `createInventoryItemWorkflow` within a Medusa API route. This example shows the GET request handler that runs the workflow and sends the result back to the client. It requires `@medusajs/framework/http` for request and response types.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createInventoryItemWorkflow } from "../../workflows/create-inventory-item"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createInventoryItemWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Execute Authentication Workflow in API Route (JavaScript)

Source: https://docs.medusajs.com/resources/commerce-modules/auth/index.html

This JavaScript code demonstrates how to execute the `authenticateUserWorkflow` within a Medusa API route. It imports the necessary types from `@medusajs/framework/http` and the workflow itself. The `GET` request handler runs the workflow and sends the result back in the response. This example assumes the workflow is defined in `../../workflows/authenticate-user`.

```javascript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { authenticateUserWorkflow } from "../../workflows/authenticate-user"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await authenticateUserWorkflow(req.scope)
    .run({
      req,
    })

  res.send(result)
}
```

--------------------------------

### Start Medusa Application

Source: https://docs.medusajs.com/resources/commerce-modules/translation/custom-data-models/index.html

Command to start the Medusa application for development. This is a prerequisite for accessing Medusa Admin and testing API routes.

```bash
npm run dev
```

--------------------------------

### Create Inventory Items for Multi-Part Products (JavaScript)

Source: https://docs.medusajs.com/resources/commerce-modules/inventory/inventory-kit

This workflow step creates inventory items required for a multi-part product. It first queries for a stock location and then uses the `createInventoryItemsWorkflow` to generate the items with specified SKUs, titles, and stock levels at the retrieved location. Dependencies include core Medusa workflows and the framework's workflow SDK.

```javascript
import {
  createInventoryItemsWorkflow,
  useQueryGraphStep,
} from "@medusajs/medusa/core-flows"
import { createWorkflow } from "@medusajs/framework/workflows-sdk"

export const createMultiPartProductsWorkflow = createWorkflow(
  "create-multi-part-products",
  () => {
    // Alternatively, you can create a stock location
    const { data: stockLocations } = useQueryGraphStep({
      entity: "stock_location",
      fields: ["*"],
      filters: {
        name: "European Warehouse",
      },
    })

    const inventoryItems = createInventoryItemsWorkflow.runAsStep({
      input: {
        items: [
          {
            sku: "FRAME",
            title: "Frame",
            location_levels: [
              {
                stocked_quantity: 100,
                location_id: stockLocations[0].id,
              },
            ],
          },
          {
            sku: "WHEEL",
            title: "Wheel",
            location_levels: [
              {
                stocked_quantity: 100,
                location_id: stockLocations[0].id,
              },
            ],
          },
          {
            sku: "SEAT",
            title: "Seat",
            location_levels: [
              {
                stocked_quantity: 100,
                location_id: stockLocations[0].id,
              },
            ],
          },
        ],
      },
    })

    // TODO create the product
  }
)
```

--------------------------------

### Execute Promotion Workflow in API Route (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/index.html

An example of an API route handler in TypeScript that executes the `createPromotionWorkflow`. It retrieves the workflow result and sends it back in the response. This demonstrates how to trigger workflows from API endpoints.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createPromotionWorkflow } from "../../workflows/create-cart"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createPromotionWorkflow(req.scope)
    .run() 

  res.send(result)
}
```

--------------------------------

### Apply Promotion to Item Quantity (JSON)

Source: https://docs.medusajs.com/resources/commerce-modules/promotion/application-method

Illustrates a promotion with 'allocation: once' and 'max_quantity: 2' applied to an item with a quantity of 3. The promotion is applied to 2 units of this item, reaching the max_quantity limit.

```json
{
  "cart": {
    "items": [
      {
        "id": "item_1",
        "price": 10,
        "quantity": 3 // The promotion is applied to 2 of this item
      },
      {
        "id": "item_2",
        "price": 20,
        "quantity": 4 // The promotion is NOT applied to this item
      }
    ]
  }
}
```

--------------------------------

### Install Draft Orders Plugin (npm/yarn)

Source: https://docs.medusajs.com/resources/commerce-modules/order/draft-orders/index.html

Command to install the Draft Orders Plugin using npm or yarn. This is a prerequisite for using the plugin in your Medusa application.

```bash
npm install @medusajs/draft-order
```

```bash
yarn add @medusajs/draft-order
```

--------------------------------

### Execute Create Store Workflow in Medusa API Route

Source: https://docs.medusajs.com/resources/commerce-modules/store/index.html

Demonstrates how to execute the `createStoreWorkflow` within a Medusa API route handler. This example shows how to access the request scope, run the workflow, and send the result back in the response.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createStoreWorkflow } from "../../workflows/create-store"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createStoreWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Start Medusa Application for Testing

Source: https://docs.medusajs.com/resources/commerce-modules/order/draft-orders/index.html

Command to start the Medusa application in development mode. This allows you to test the Draft Orders Plugin's functionality in the Medusa Admin.

```bash
npm run dev
```

```bash
yarn dev
```

--------------------------------

### Calculate Prices with Context (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation/index.html

Demonstrates how to use the `calculatePrices` method from the Pricing Module service to retrieve prices for a given price set ID and a specific context, such as currency code and region ID.

```typescript
const price = await pricingModuleService.calculatePrices(
  { id: [priceSetId] },
  {
    context: {
      currency_code: "eur",
      region_id: "reg_123",
    },
  }
)
```

--------------------------------

### Start Medusa Development Server

Source: https://docs.medusajs.com/resources/commerce-modules/order/custom-display-id

Starts the Medusa development server after applying configuration changes and migrations. This command is used to run the application locally and observe the effects of the customizations.

```bash
yarn dev
```

--------------------------------

### POST /auth/{actor_type}/{auth_provider}/reset-password

Source: https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route

Generates a password reset token for a user. This token can then be used to send a notification to the user, guiding them through the password reset process.

```APIDOC
## POST /auth/{actor_type}/{auth_provider}/reset-password

### Description
Generates a password reset token for a user, emitting the `auth.password_reset` event.

### Method
POST

### Endpoint
/auth/{actor_type}/{auth_provider}/reset-password

### Path Parameters
- **actor_type** (string) - Required - The actor type of the user (e.g., `customer`).
- **auth_provider** (string) - Required - The authentication provider (e.g., `emailpass`).

### Headers
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **identifier** (string) - Required - The user's identifier for the specified auth provider (e.g., email for `emailpass`).

### Request Example
```bash
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/reset-password \
-H 'Content-Type: application/json' \
--data-raw '{
  "identifier": "Whitney_Schultz@gmail.com"
}'
```

### Response
#### Success Response (201)
No specific fields are detailed, but a 201 status code indicates success.
```

--------------------------------

### Execute API Key Creation Workflow in API Route (TypeScript)

Source: https://docs.medusajs.com/resources/commerce-modules/api-key/index.html

Demonstrates how to execute the `createApiKeyWorkflow` within a Medusa API route handler. This example shows how to run the workflow and send the resulting API key data back as a response. It requires Medusa's HTTP types for request and response handling.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { createApiKeyWorkflow } from "../../workflows/create-api-key"

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result } = await createApiKeyWorkflow(req.scope)
    .run()

  res.send(result)
}
```

--------------------------------

### Login Route cURL Example

Source: https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route/index.html

Example using cURL to send a POST request to the Medusa Login Route for authentication. It includes the endpoint, content type, and a sample request body with an email.

```bash
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
-H 'Content-Type: application/json' \
--data-raw '{
  "email": "Whitney_Schultz@gmail.com"
  // ...
}'
```

--------------------------------

### Create Products with Tiered Pricing using Medusa Workflows

Source: https://docs.medusajs.com/resources/commerce-modules/pricing/price-rules/index.html

Demonstrates how to create products with multiple price tiers using the `createProductsWorkflow`. This workflow allows defining base prices and discounted prices based on quantity.

```typescript
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"

// ...

const { result } = await createProductsWorkflow(container)
  .run({
    input: {
      products: [{
        title: "Premium T-Shirt",
        variants: [{
          title: "Small / Black",
          prices: [
            // default price
            {
              amount: 20,
              currency_code: "usd",
            },
            // buy 5 or more, get a small discount
            {
              amount: 18,
              currency_code: "usd",
              min_quantity: 5,
              max_quantity: 9,
            },
            // buy 10 or more, get a bigger discount
            {
              amount: 15,
              currency_code: "usd",
              min_quantity: 10,
            },
          ],
        }],
      }],
    },
  })
```
Tokens:
Raw