diff --git a/www/apps/book/app/learn/page.mdx b/www/apps/book/app/learn/page.mdx index 0e3a35e0c1..85f91bbd22 100644 --- a/www/apps/book/app/learn/page.mdx +++ b/www/apps/book/app/learn/page.mdx @@ -17,7 +17,7 @@ Medusa ships with three main tools: When you install Medusa, you get a fully fledged commerce platform with all the features you need to get off the ground. However, unlike other platforms, Medusa is built with customization in mind. You don't need to build hacky workarounds that are difficult to maintain and scale. Your efforts go into building features that brings your business's vision to life. ---- +--- ## Who should use Medusa @@ -84,6 +84,10 @@ This documentation is split into the following sections: To get started, check out the [Installation chapter](./installation/page.mdx). +### Using with LLM Editors + +This documentation provides an [llms.txt](https://docs.medusajs.com/llms.txt) file to support LLM editors such as Cursor. Add the documentation to the list of supported documentation in your LLM editor to access the documentation directly from your editor and benefit from code generation. + --- ## Useful Links diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 8ab72c334e..b3b1b9136f 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -2,7 +2,7 @@ export const generatedEditDates = { "app/learn/fundamentals/scheduled-jobs/page.mdx": "2024-12-09T10:51:40.570Z", "app/learn/fundamentals/workflows/page.mdx": "2024-12-09T14:45:17.837Z", "app/learn/deployment/page.mdx": "2024-11-25T14:32:44.949Z", - "app/learn/page.mdx": "2024-11-28T14:17:53.023Z", + "app/learn/page.mdx": "2025-01-08T10:49:58.879Z", "app/learn/fundamentals/modules/commerce-modules/page.mdx": "2024-12-09T10:46:29.339Z", "app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2024-12-04T07:37:59.823Z", "app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z", diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index 3c67016984..b4f31c19df 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -198,8 +198,8 @@ export const sidebar = numberSidebarItems( }, { type: "link", - path: "/learn/fundamentals/module-links/remote-link", - title: "Remote Link", + path: "/learn/fundamentals/module-links/link", + title: "Link", }, { type: "link", diff --git a/www/apps/resources/app/architectural-modules/cache/page.mdx b/www/apps/resources/app/architectural-modules/cache/page.mdx index 30e1c1a99e..7230b9bf5e 100644 --- a/www/apps/resources/app/architectural-modules/cache/page.mdx +++ b/www/apps/resources/app/architectural-modules/cache/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `Cache Modules`, @@ -18,7 +18,26 @@ By default, Medusa uses the In-Memory Cache Module. This module uses a plain Jav This is useful for development. However, for production, it's highly recommended to use other Cache Modules, such as the Redis Cache Module. - + --- diff --git a/www/apps/resources/app/architectural-modules/event/page.mdx b/www/apps/resources/app/architectural-modules/event/page.mdx index 5e9b3d7ffd..37242fa3f9 100644 --- a/www/apps/resources/app/architectural-modules/event/page.mdx +++ b/www/apps/resources/app/architectural-modules/event/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `Event Modules`, @@ -18,7 +18,26 @@ By default, Medusa uses the Local Event Module. This module uses Node’s EventE This is useful for development. However, for production, it’s highly recommended to use other Event Modules, Redis Event Module. - + --- diff --git a/www/apps/resources/app/architectural-modules/file/page.mdx b/www/apps/resources/app/architectural-modules/file/page.mdx index e7021c554e..b34559d601 100644 --- a/www/apps/resources/app/architectural-modules/file/page.mdx +++ b/www/apps/resources/app/architectural-modules/file/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `File Module Providers`, @@ -14,7 +14,26 @@ By default, Medusa uses the Local File Module. This module uploads files to the This is useful for development. However, for production, it’s highly recommended to use other File Modules, such as the S3 Module. - + --- diff --git a/www/apps/resources/app/architectural-modules/notification/page.mdx b/www/apps/resources/app/architectural-modules/notification/page.mdx index 2ebfb2c12d..5d207975d3 100644 --- a/www/apps/resources/app/architectural-modules/notification/page.mdx +++ b/www/apps/resources/app/architectural-modules/notification/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `Notification Module Providers`, @@ -18,7 +18,26 @@ By default, Medusa uses the Local Notification Module which only simulates sendi Medusa provides other Notification Modules that actually send notifications, such as the SendGrid Notification Module Provider. - + --- diff --git a/www/apps/resources/app/architectural-modules/page.mdx b/www/apps/resources/app/architectural-modules/page.mdx index d5d27a60ab..8033b72121 100644 --- a/www/apps/resources/app/architectural-modules/page.mdx +++ b/www/apps/resources/app/architectural-modules/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs, CardList } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `Architectural Modules`, diff --git a/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx b/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx index d050bb87e3..30e4e183e2 100644 --- a/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx +++ b/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx @@ -1,4 +1,4 @@ -import { ChildDocs } from "docs-ui" +import { CardList } from "docs-ui" export const metadata = { title: `Workflow Engine Modules`, @@ -10,4 +10,23 @@ Workflow engine modules handle tracking and recording the transactions and statu Medusa uses the In-Memory Workflow Engine Module by default. For production purposes, it's recommended to use the Redis Engine Module instead. - + \ No newline at end of file diff --git a/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/page.mdx b/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/page.mdx index a146eb652a..ade03742aa 100644 --- a/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/page.mdx +++ b/www/apps/resources/app/commerce-modules/inventory/inventory-in-flows/page.mdx @@ -10,6 +10,12 @@ This document explains how the Inventory Module is used within the Medusa applic When a product variant is created and its `manage_inventory` property's value is `true`, the Medusa application creates an inventory item associated with that product variant. + + +This flow is implemented within the [createProductVariantsWorkflow](/references/medusa-workflows/createProductVariantsWorkflow) + + + ![A diagram showcasing how the Inventory Module is used in the product variant creation form](https://res.cloudinary.com/dza7lstvk/image/upload/v1709661511/Medusa%20Resources/inventory-product-create_khz2hk.jpg) --- @@ -18,6 +24,12 @@ When a product variant is created and its `manage_inventory` property's value is When a product variant with `manage_inventory` set to `true` is added to cart, the Medusa application checks whether there's sufficient stocked quantity. If not, an error is thrown and the product variant won't be added to the cart. + + +This flow is implemented within the [addToCartWorkflow](/references/medusa-workflows/addToCartWorkflow) + + + ![A diagram showcasing how the Inventory Module is used in the add to cart flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709711645/Medusa%20Resources/inventory-cart-flow_achwq9.jpg) --- @@ -26,6 +38,12 @@ When a product variant with `manage_inventory` set to `true` is added to cart, t When an order is placed, the Medusa application creates a reservation item for each product variant with `manage_inventory` set to `true`. + + +This flow is implemented within the [completeCartWorkflow](/references/medusa-workflows/completeCartWorkflow) + + + ![A diagram showcasing how the Inventory Module is used in the order placed flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712005/Medusa%20Resources/inventory-order-placed_qdxqdn.jpg) --- @@ -38,6 +56,12 @@ When an item in an order is fulfilled and the associated variant has its `manage - Resets the `reserved_quantity` to `0`. - Deletes the associated reservation item. + + +This flow is implemented within the [createOrderFulfillmentWorkflow](/references/medusa-workflows/createOrderFulfillmentWorkflow) + + + ![A diagram showcasing how the Inventory Module is used in the order fulfillment flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712390/Medusa%20Resources/inventory-order-fulfillment_o9wdxh.jpg) --- @@ -46,6 +70,12 @@ When an item in an order is fulfilled and the associated variant has its `manage When an item in an order is returned and the associated variant has its `manage_inventory` property set to `true`, the Medusa application increments the `stocked_quantity` of the inventory item's level with the returned quantity. + + +This flow is implemented within the [confirmReturnReceiveWorkflow](/references/medusa-workflows/confirmReturnReceiveWorkflow) + + + ![A diagram showcasing how the Inventory Module is used in the order return flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1709712457/Medusa%20Resources/inventory-order-return_ihftyk.jpg) ### Dismissed Returned Items diff --git a/www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx b/www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx index 845cfbbf35..bc9adecf1c 100644 --- a/www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx +++ b/www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx @@ -1,10 +1,18 @@ +import { CodeTabs, CodeTab } from "docs-ui" + export const metadata = { title: `Accept Payment Flow`, } # {metadata.title} -In this document, you’ll learn how to implement an accept-payment flow using the Payment Module's main service. +In this document, you’ll learn how to implement an accept-payment flow using workflows or the Payment Module's main service. + + + +It's highly recommended to use Medusa's workflows to implement this flow. Use the Payment Module's main service for more complex cases. + + @@ -24,6 +32,25 @@ A payment collection holds all details related to a resource’s payment operati For example: + + + +```ts +import { createPaymentCollectionForCartWorkflow } from "@medusajs/medusa/core-flows"; + +// ... + +await createPaymentCollectionForCartWorkflow(req.scope) + .run({ + input: { + cart_id: "cart_123" + } + }) +``` + + + + ```ts const paymentCollection = await paymentModuleService.createPaymentCollections({ @@ -33,42 +60,8 @@ const paymentCollection = }) ``` - - -Learn more about the `createPaymentCollections` method in [this reference](/references/payment/createPaymentCollections). - - - -Then, create a link between the payment collection and the resource it's storing payment details for, such as a cart in the Cart Module: - -```ts -import { - ContainerRegistrationKeys, - Modules, -} from "@medusajs/framework/utils" - -// ... - -// resolve Link -const link = container.resolve( - ContainerRegistrationKeys.LINK -) - -link.create({ - [Modules.CART]: { - cart_id: "cart_123", - }, - [Modules.PAYMENT]: { - payment_collection_id: paymentCollection.id, - }, -}) -``` - - - -Learn more about Link in [this documentation](!docs!/learn/fundamentals/module-links/link). - - + + --- @@ -80,6 +73,26 @@ So, after creating the payment collection, create at least one payment session f For example: + + + +```ts +import { createPaymentSessionsWorkflow } from "@medusajs/medusa/core-flows"; + +// ... + +const { result: paymentSesion } = await createPaymentSessionsWorkflow(req.scope) + .run({ + input: { + payment_collection_id: "paycol_123", + provider_id: "stripe", + } + }) +``` + + + + ```ts const paymentSession = await paymentModuleService.createPaymentSession( @@ -96,11 +109,8 @@ const paymentSession = ) ``` - - -Learn more about the `createPaymentSession` method in [this reference](/references/payment/createPaymentSession). - - + + --- @@ -110,24 +120,43 @@ Once the customer chooses a payment session, start the authorization process. Th For example: + + + ```ts -const payment = - await paymentModuleService.authorizePaymentSession( - paymentSession.id, - {} - ) +import { authorizePaymentSessionStep } from "@medusajs/medusa/core-flows"; + +// ... + +authorizePaymentSessionStep({ + id: "payses_123", + context: {} +}) ``` + + + +```ts +const payment = authorizePaymentSessionStep({ + id: "payses_123", + context: {} +}) +``` + + + + When the payment authorization is successful, a payment is created and returned. +### Handling Additional Action + -Learn more about the `authorizePaymentSession` method in [this reference](/references/payment/authorizePaymentSession). +If you used the `authorizePaymentSessionStep`, you don't need to implement this logic as it's implemented in the step. -### Handling Additional Action - If the payment authorization isn’t successful, whether because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error. In that case, you can catch that error and, if the session's `status` property is `requires_more`, handle the additional action, then retry the authorization. @@ -162,7 +191,10 @@ try { The payment flow is complete once the payment session is authorized and the payment is created. -You can then use the payment to capture the amount using the [capturePayment method](/references/payment/capturePayment). You can also refund captured amounts using the [refundPayment method](/references/payment/refundPayment). +You can then: + +- Capture the payment either using the [capturePaymentWorkflow](/references/medusa-workflows/capturePaymentWorkflow) or [capturePayment method](/references/payment/capturePayment). +- Refund captured amounts using the [refundPaymentWorkflow](/references/medusa-workflows/refundPaymentWorkflow) or [refundPayment method](/references/payment/refundPayment). diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index e2856b7419..0a1e592e68 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -29,7 +29,7 @@ export const generatedEditDates = { "app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/inventory/_events/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/inventory/concepts/page.mdx": "2024-10-08T15:11:27.634Z", - "app/commerce-modules/inventory/inventory-in-flows/page.mdx": "2024-10-08T15:14:07.327Z", + "app/commerce-modules/inventory/inventory-in-flows/page.mdx": "2025-01-08T12:21:12.157Z", "app/commerce-modules/inventory/page.mdx": "2024-12-25T15:55:02.850Z", "app/commerce-modules/order/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/order/_events/page.mdx": "2024-07-03T19:27:13+03:00", @@ -47,7 +47,7 @@ export const generatedEditDates = { "app/commerce-modules/payment/module-options/page.mdx": "2024-10-15T12:51:40.574Z", "app/commerce-modules/payment/payment/page.mdx": "2024-10-09T10:59:08.463Z", "app/commerce-modules/payment/payment-collection/page.mdx": "2024-10-09T10:56:49.510Z", - "app/commerce-modules/payment/payment-flow/page.mdx": "2025-01-06T11:19:35.592Z", + "app/commerce-modules/payment/payment-flow/page.mdx": "2025-01-08T12:51:39.100Z", "app/commerce-modules/payment/payment-provider/stripe/page.mdx": "2024-12-16T13:21:03.554Z", "app/commerce-modules/payment/payment-provider/page.mdx": "2024-10-09T11:07:27.269Z", "app/commerce-modules/payment/payment-session/page.mdx": "2024-10-09T10:58:00.960Z", @@ -197,13 +197,13 @@ export const generatedEditDates = { "app/commerce-modules/auth/auth-identity-and-actor-types/page.mdx": "2025-01-07T09:02:27.235Z", "app/commerce-modules/api-key/page.mdx": "2024-12-25T15:55:02.846Z", "app/commerce-modules/auth/create-actor-type/page.mdx": "2024-12-25T13:26:27.176Z", - "app/architectural-modules/page.mdx": "2024-12-11T10:33:53.064Z", + "app/architectural-modules/page.mdx": "2025-01-08T12:13:50.333Z", "app/architectural-modules/workflow-engine/redis/page.mdx": "2024-10-15T12:50:59.507Z", "app/architectural-modules/notification/sendgrid/page.mdx": "2024-10-15T12:51:25.569Z", "app/commerce-modules/api-key/concepts/page.mdx": "2024-10-07T13:59:37.529Z", - "app/architectural-modules/workflow-engine/page.mdx": "2024-05-28T13:25:03+03:00", + "app/architectural-modules/workflow-engine/page.mdx": "2025-01-08T12:16:04.157Z", "app/_events-reference/page.mdx": "2024-07-03T19:27:13+03:00", - "app/architectural-modules/cache/page.mdx": "2024-05-28T13:25:03+03:00", + "app/architectural-modules/cache/page.mdx": "2025-01-08T12:14:37.925Z", "app/architectural-modules/file/s3/page.mdx": "2024-10-15T12:51:14.315Z", "app/commerce-modules/api-key/_events/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/api-key/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", @@ -215,11 +215,11 @@ export const generatedEditDates = { "app/architectural-modules/notification/local/page.mdx": "2024-10-15T12:51:21.284Z", "app/architectural-modules/file/local/page.mdx": "2024-10-16T15:48:42.839Z", "app/architectural-modules/notification/send-notification/page.mdx": "2024-09-30T08:43:53.151Z", - "app/architectural-modules/file/page.mdx": "2024-12-11T10:27:50.510Z", - "app/architectural-modules/event/page.mdx": "2024-05-28T13:25:03+03:00", + "app/architectural-modules/file/page.mdx": "2025-01-08T12:15:19.981Z", + "app/architectural-modules/event/page.mdx": "2025-01-08T12:15:08.454Z", "app/architectural-modules/cache/create/page.mdx": "2024-10-16T08:51:35.074Z", "app/admin-widget-injection-zones/page.mdx": "2024-12-24T08:48:36.154Z", - "app/architectural-modules/notification/page.mdx": "2024-12-11T10:29:47.317Z", + "app/architectural-modules/notification/page.mdx": "2025-01-08T12:15:40.159Z", "app/architectural-modules/event/create/page.mdx": "2024-12-09T14:46:40.248Z", "references/core_flows/Order/functions/core_flows.Order.orderEditUpdateItemQuantityValidationStep/page.mdx": "2024-08-20T00:10:58.913Z", "references/core_flows/Order/functions/core_flows.Order.orderEditUpdateItemQuantityWorkflow/page.mdx": "2024-08-20T00:10:58.949Z",