asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: improve commerce modules [3/n] (#9510)

Browse Source 
Improve and add docs for Order and Payment modules

[3/n]

Closes DOCS-966
Closes #9485
This commit is contained in:
Shahed Nasser
2024-10-14 10:20:35 +03:00
committed by GitHub
parent 74b286b701
commit 11120a8b7e
30 changed files with 662 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/order/claim/page.mdx
+7 -7
View File
@@ -10,7 +10,7 @@ In this document, you’ll learn about order claims.
When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
The [Claim data model](/references/order/models/Claim) represents a claim.
The [OrderClaim data model](/references/order/models/OrderClaim) represents a claim.
---
@@ -25,7 +25,7 @@ The `Claim` data model has a `type` property whose value indicates the type of t
## Old and Replacement Items
When the claim is created, a return is also created to handle receiving the old items from the customer.
When the claim is created, a return, represented by the [Return data model](/references/order/models/Return), is also created to handle receiving the old items from the customer.
<Note>
@@ -33,15 +33,15 @@ Learn more about returns in [this guide](../return/page.mdx).
</Note>
If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](/references/order/models/ClaimItem).
If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](/references/order/models/OrderClaimItem).
---
## Claim Shipping Methods
An exchange uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
A claim uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
The items returned from the customer are handled by the associated return.
The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](../return/page.mdx#return-shipping-methods).
---
@@ -49,10 +49,10 @@ The items returned from the customer are handled by the associated return.
If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
The [Transaction data model](/references/order/models/Transaction) represents the refunds made for the claim.
The [Transaction data model](/references/order/models/OrderTransaction) represents the refunds made for the claim.
---
## How Claims Impact an Order’s Version
When an exchange is created, the order’s version is incremented.
When a claim is confirmed, the order’s version is incremented.
www/apps/resources/app/commerce-modules/order/concepts/page.mdx
+5 -5
View File
@@ -14,7 +14,7 @@ The items purchased in the order are represented by the [OrderItem data model](/
### Item’s Product Details
The details of the purchased products are represented by the [LineItem data model](/references/order/models/LineItem). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
The details of the purchased products are represented by the [LineItem data model](/references/order/models/OrderLineItem). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
---
@@ -22,15 +22,15 @@ The details of the purchased products are represented by the [LineItem data mode
An order has one or more shipping methods used to handle item shipment.
Each shipping method is represented by the [ShippingMethod data model](/references/order/models/ShippingMethod) that holds its details. The shipping method is linked to the order through the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
Each shipping method is represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod) that holds its details. The shipping method is linked to the order through the [OrderShipping data model](/references/order/models/OrderShipping).
![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719570409/Medusa%20Resources/order-shipping-method_tkggvd.jpg)
### data Property
When fulfilling the order, you may use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
When fulfilling the order, you can use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
The `ShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
The `OrderShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
The Medusa application passes the `data` property to the Fulfillment Module when fulfilling items.
@@ -44,7 +44,7 @@ The order’s total amounts (including tax total, total after an item is returne
## Order Payments
Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [Transaction data model](/references/order/models/Transaction).
Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [OrderTransaction data model](/references/order/models/OrderTransaction).
An order can have multiple transactions. The sum of these transactions must be equal to the order summary’s total. Otherwise, there’s an outstanding amount.
www/apps/resources/app/commerce-modules/order/edit/page.mdx
+57
View File
@@ -0,0 +1,57 @@
export const metadata = {
title: `Order Edit`,
}
# {metadata.title}
In this document, you'll learn about order edits.
## What is an Order Edit?
A merchant can edit an order to add new items or change the quantity of existing items in the order.
An order edit is represented by the [OrderChange data model](/references/order/models/OrderChange).
The `OrderChange` data model is associated with any type of change, including a return or exchange. However, its `change_type` property distinguishes the type of change it's making.
In the case of an order edit, the `OrderChange`'s type is `edit`.
---
## Add Items in an Order Edit
When the merchant adds new items to the order in the order edit, the item is added as an [OrderItem](/references/order/models/OrderItem).
Also, an `OrderChangeAction` is created. The [OrderChangeAction data model](/references/order/models/OrderChangeAction) represents a change made by an `OrderChange`, such as an item added.
So, when an item is added, an `OrderChangeAction` is created with the type `ITEM_ADD`. In its `details` property, the item's ID, price, and quantity are stored.
---
## Update Items in an Order Edit
A merchant can update an existing item's quantity or price.
This change is added as an `OrderChangeAction` with the type `ITEM_UPDATE`. In its `details` property, the item's ID, new price, and new quantity are stored.
---
## Shipping Methods of New Items in the Edit
Adding new items to the order requires adding shipping methods for those items.
These shipping methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderItem). Also, an `OrderChangeAction` is created with the type `SHIPPING_ADD`
---
## How Order Edits Impact an Order’s Version
When an order edit is confirmed, the order’s version is incremented.
---
## Payments and Refunds for Order Edit Changes
Once the Order Edit is confirmed, any additional payment or refund required can be made on the original order.
This is determined by the comparison between the `OrderSummary` and the order's transactions, as mentioned in [this guide](../transactions/page.mdx#checking-outstanding-amount).
www/apps/resources/app/commerce-modules/order/exchange/page.mdx
+11 -9
View File
@@ -10,15 +10,17 @@ In this document, you’ll learn about order exchanges.
## What is an Exchange?
An exchange is the replacement of an item that the customer ordered with another. A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
An exchange is the replacement of an item that the customer ordered with another.
The [Exchange data model](/references/order/models/Exchange) represents an exchange.
A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
The [OrderExchange data model](/references/order/models/OrderExchange) represents an exchange.
---
## Returned and New Items
When the exchange is created, a return is created to handle receiving the items back from the customer.
When the exchange is created, a return, represented by the [Return data model](/references/order/models/Return), is created to handle receiving the items back from the customer.
<Note>
@@ -26,7 +28,7 @@ Learn more about returns in [this guide](../return/page.mdx).
</Note>
The [ExchangeItem data model](/references/order/models/ExchangeItem) represents the new items to be sent to the customer.
The [OrderExchangeItem data model](/references/order/models/OrderExchangeItem) represents the new items to be sent to the customer.
---
@@ -34,7 +36,7 @@ The [ExchangeItem data model](/references/order/models/ExchangeItem) represents
An exchange has shipping methods used to send the new items to the customer. They’re represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
The items returned from the customer are handled by the associated return.
The shipping methods for the returned items are associated with the exchange's return, as explained in [this guide](../return/page.mdx#return-shipping-methods).
---
@@ -58,7 +60,7 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
</Table.Cell>
<Table.Cell>
Merchant refunds the difference_due amount.
Merchant owes the customer a refund of the `difference_due` amount.
</Table.Cell>
</Table.Row>
@@ -70,7 +72,7 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
</Table.Cell>
<Table.Cell>
Merchant requires additional payment from the customer.
Merchant requires additional payment from the customer of the `difference_due` amount.
</Table.Cell>
</Table.Row>
@@ -89,10 +91,10 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
</Table.Body>
</Table>
Any payment or refund made is stored in the [Transaction data model](/references/order/models/Transaction).
Any payment or refund made is stored in the [Transaction data model](/references/order/models/OrderTransaction).
---
## How Exchanges Impact an Order’s Version
When an exchange is created, the order’s version is incremented.
When an exchange is confirmed, the order’s version is incremented.
www/apps/resources/app/commerce-modules/order/links-to-other-modules/page.mdx
+46
View File
@@ -0,0 +1,46 @@
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.
## 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.
![A diagram showcasing an example of how data models from the Cart and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728375735/Medusa%20Resources/cart-order_ijwmfs.jpg)
---
## Fulfillment Module
A fulfillment is created for an orders' items. Medusa defines a link between the `Fulfillment` and `Order` 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/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)
---
## 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.
![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
---
## Promotion Module
An order is associated with the promotion applied on it. Medusa defines a link between the `Order` and `Promotion` data models.
![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
www/apps/resources/app/commerce-modules/order/order-change/page.mdx
+204
View File
@@ -0,0 +1,204 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Order Change`,
}
# {metadata.title}
In this document, you'll learn about the Order Change data model and possible actions in it.
## OrderChange Data Model
The [OrderChange data model](/references/order/models/OrderChange) represents any kind of change to an order, such as a return, exchange, or edit.
Its `change_type` property indicates what the order change is created for:
1. `edit`: The order change is making edits to the order, as explained in [this guide](../edit/page.mdx).
2. `exchange`: The order change is associated with an exchange, which you can learn about in [this guide](../exchange/page.mdx).
3. `claim`: The order change is associated with a claim, which you can learn about in [this guide](../claim/page.mdx).
4. `return_request` or `return_receive`: The order change is associated with a return, which you can learn about in [this guide](../return/page.mdx).
Once the order change is confirmed, its changes are applied on the order.
---
## Order Change Actions
The actions to perform on the original order by a change, such as adding an item, are represented by the [OrderChangeAction data model](/references/order/models/OrderChangeAction).
The `OrderChangeAction` has an `action` property that indicates the type of action to perform on the order, and a `details` property that holds more details related to the action.
The following table lists the possible `action` values that Medusa uses and what `details` they carry.
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Action</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-2/4">Details</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`ITEM_ADD`
</Table.Cell>
<Table.Cell>
Add an item to the order.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the new item.
- `quantity`: The item's quantity.
- `unit_price`: The item's unit price.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`ITEM_UPDATE`
</Table.Cell>
<Table.Cell>
Update an item in the order.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The item's quantity.
- `unit_price`: The item's unit price.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`RETURN_ITEM`
</Table.Cell>
<Table.Cell>
Set an item to be returned.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to be returned.
- `reason_id`: The ID of the return reason.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`RECEIVE_RETURN_ITEM`
</Table.Cell>
<Table.Cell>
Mark a return item as received.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity received. This quantity is added to the inventory quantity of the item's variant when the return is confirmed.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`RECEIVE_DAMAGED_RETURN_ITEM`
</Table.Cell>
<Table.Cell>
Mark a return item that's damaged as received.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity received. This quantity isn't added to the item variant's inventory quantity, as the quantity is damaged.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`SHIPPING_ADD`
</Table.Cell>
<Table.Cell>
Add a shipping method for new or returned items.
</Table.Cell>
<Table.Cell>
No details added. The ID to the shipping method is added in the `reference_id` property of the action.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`SHIPPING_ADD`
</Table.Cell>
<Table.Cell>
Add a shipping method for new or returned items.
</Table.Cell>
<Table.Cell>
No details added. The ID to the shipping method is added in the `reference_id` property of the action.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`WRITE_OFF_ITEM`
</Table.Cell>
<Table.Cell>
Remove an item's quantity as part of the claim, without adding the quantity back to the item variant's inventory.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to write off.
- `reason`: The claim reason.
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx
+2
View File
@@ -10,6 +10,8 @@ In this document, you’ll learn how an order and its details are versioned.
Versioning means assigning a version number to a record, such as an order and its items. This is useful to view the different versions of the order following changes in its lifetime.
When changes are made on an order, such as an item is added or returned, the order's version changes.
---
## version Property
www/apps/resources/app/commerce-modules/order/page.mdx
+27 -29
View File
@@ -6,7 +6,7 @@ export const metadata = {
# {metadata.title}
The Order Module is the `@medusajs/medusa/order` NPM package that provides order-related features in your Medusa and Node.js applications.
The Order Module provides order-related features in your Medusa and Node.js applications.
## How to Use Order Module's Service
@@ -15,18 +15,32 @@ You can use the Order Module's main service by resolving from the Medusa contain
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const orderModuleService = container.resolve(
Modules.ORDER
)
const orders = await orderModuleService.listOrders()
})
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IOrderModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const orderModuleService: IOrderModuleService = req.scope.resolve(
const orderModuleService = req.scope.resolve(
Modules.ORDER
)
@@ -39,34 +53,17 @@ export async function GET(
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { IOrderModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function subscriberHandler({ container }: SubscriberArgs) {
const orderModuleService: IOrderModuleService = container.resolve(
const orderModuleService = container.resolve(
Modules.ORDER
)
const orders = await orderModuleService.listOrders()
}
```
</CodeTab>
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { IOrderModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const orderModuleService: IOrderModuleService = container.resolve(
Modules.ORDER
)
const orders = await orderModuleService.listOrders()
})
```
</CodeTab>
@@ -108,6 +105,7 @@ const draftOrder = await orderModuleService.createOrders({
currency_code: "usd",
// other details...
status: "draft",
is_draft_order: true,
})
```
@@ -116,14 +114,14 @@ const draftOrder = await orderModuleService.createOrders({
Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
```ts
const lineAdjustments = await orderModuleService.addLineItemAdjustments({
const lineAdjustments = await orderModuleService.createOrderLineItemAdjustments({
item_id: "cali_123",
code: "50OFF",
amount: 500,
})
const shippingAdjustments =
await orderModuleService.addShippingMethodAdjustments({
await orderModuleService.createOrderShippingMethodAdjustments({
shipping_method_id: "casm_123",
code: "FREESHIPPING",
amount: 1000,
www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx
+4 -4
View File
@@ -14,7 +14,7 @@ In this document, you’ll learn how a promotion is applied to an order’s item
An adjustment line indicates a change to a line item or a shipping method’s amount. It’s used to apply promotions or discounts on an order.
The [LineItemAdjustment data model](/references/order/models/LineItemAdjustment) represents changes on a line item, and the [ShippingMethodAdjustment data model](/references/order/models/ShippingMethodAdjustment) represents changes on a shipping method.
The [OrderLineItemAdjustment data model](/references/order/models/OrderLineItemAdjustment) represents changes on a line item, and the [OrderShippingMethodAdjustment data model](/references/order/models/OrderShippingMethodAdjustment) represents changes on a shipping method.
![A diagram showcasing the relation between an order, its items and shipping methods, and their adjustment lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712306017/Medusa%20Resources/order-adjustments_myflir.jpg)
@@ -30,7 +30,7 @@ The ID of the applied promotion is stored in the `promotion_id` property of the
## Discountable Option
The `LineItem` data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.
The `OrderLineItem` data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.
When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.
@@ -120,14 +120,14 @@ import {
// ...
await orderModuleService.setLineItemAdjustments(
await orderModuleService.setOrderLineItemAdjustments(
order.id,
actions.filter(
(action) => action.action === "addItemAdjustment"
) as AddItemAdjustmentAction[]
)
await orderModuleService.setShippingMethodAdjustments(
await orderModuleService.setOrderShippingMethodAdjustments(
order.id,
actions.filter(
(action) =>
www/apps/resources/app/commerce-modules/order/relations-to-other-modules/page.mdx
-63
View File
@@ -1,63 +0,0 @@
export const metadata = {
title: `Relations between Order Module and Other Modules`,
}
# {metadata.title}
This document showcases the link modules defined between the Order Module and other commerce modules.
## Customer Module
An order is associated with the customer that placed it. Medusa defines a link module that builds a relationship between the `Order` and `Customer` data models.
![A diagram showcasing an example of how data models from the Order and Customer modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716545470/Medusa%20Resources/customer-order_pkla6f.jpg)
---
## Fulfillment Module
A fulfillment is created for an orders' items. Medusa defines a link module that builds a relationship between the `Fulfillment` and `Order` 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/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)
---
## Payment Module
An order's payment is stored in a payment collection. Medusa defines a link module that builds a relationship between the `Order` and `PaymentCollection` data models.
![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
---
## Product Module
An order's line item is associated with the purchased product and its variant. Medusa defines a link module that builds a relationship between the `LineItem`, `Product`, and `ProductVariant` data models.
![A diagram showcasing an example of how data models from the Order and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716556100/Medusa%20Resources/order-product_l6ylte.jpg)
---
## Promotion Module
An order is associated with the promotion applied on it. Medusa defines a link module that builds a relationship between the `Order` and `Promotion` data models.
![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
---
## Region Module
An order is associated with the customer's region. Medusa defines a link module that builds a relationship between the `Order` and `Region` data models.
![A diagram showcasing an example of how data models from the Order and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555119/Medusa%20Resources/order-region_ihkp2u.jpg)
---
## Sales Channel Module
Orders can be scoped to a sales channel. Medusa defines a link module that builds a relationship between the `Order` and the `SalesChannel` data models.
![A diagram showcasing an example of how resources from the Order and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712315409/Medusa%20Resources/order-sales-channel_dy72gx.jpg)
This is useful for omnichannel purposes. Associating an order with a sales channel in turn ensures that associated products, inventory, and other details are also scoped to that sales channel.
www/apps/resources/app/commerce-modules/order/return/page.mdx
+10 -3
View File
@@ -8,9 +8,9 @@ In this document, you’ll learn about order returns.
## What is a Return?
A return is the return of items delivered to the customer back to the merchant. It is represented by the [Return data model](/references/order/models/Return).
A return is the return of items delivered from the customer back to the merchant. It is represented by the [Return data model](/references/order/models/Return).
A return is requested either by the customer or the merchant, supporting an automated Return Merchandise Authorization (RMA) flow.
A return is requested either by the customer from the storefront, or the merchant from the admin. Medusa supports an automated Return Merchandise Authorization (RMA) flow.
![Diagram showcasing the automated RMA flow.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719578128/Medusa%20Resources/return-rma_pzprwq.jpg)
@@ -22,19 +22,26 @@ Once the merchant receives the returned items, they mark the return as received.
The items to be returned are represented by the [ReturnItem data model](references/order/models/ReturnItem).
The `ReturnItem` model has two properties storing the item's quantity:
1. `received_quantity`: The quantity of the item that's received and can be added to the item's inventory quantity.
2. `damaged_quantity`: The quantity of the item that's damaged, meaning it can't be sold again or added to the item's inventory quantity.
---
## Return Shipping Methods
A return has shipping methods used to return the items to the merchant. The shipping methods are represented by the [OrderShippingMethod data model](references/order/models/OrderShippingMethod).
In the Medusa application, the shipping method for a return is created only from a shipping option, provided by the Fulfillment Module, that has the rule `is_return` enabled.
---
## Refund Payment
The `refund_amount` property of the `Return` data model holds the amount a merchant must refund the customer.
The [Transaction data model](references/order/models/Transaction) represents the refunds made for the return.
The [OrderTransaction data model](references/order/models/OrderTransaction) represents the refunds made for the return.
---
www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx
+4 -2
View File
@@ -14,7 +14,7 @@ In this document, you’ll learn about tax lines in an order.
A tax line indicates the tax rate of a line item or a shipping method.
The [LineItemTaxLine data model](/references/order/models/LineItemTaxLine) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](/references/order/models/ShippingMethodTaxLine) represents a shipping method’s tax line.
The [OrderLineItemTaxLine data model](/references/order/models/OrderLineItemTaxLine) represents a line item’s tax line, and the [OrderShippingMethodTaxLine data model](/references/order/models/OrderShippingMethodTaxLine) represents a shipping method’s tax line.
![A diagram showcasing the relation between orders, items and shipping methods, and tax lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307225/Medusa%20Resources/order-tax-lines_sixujd.jpg)
@@ -34,4 +34,6 @@ The following diagram is a simplified showcase of how a subtotal is calculated f
</Note>
![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
For example, if a line item's amount is `5000`, the tax rate is `10`, and `is_tax_inclusive` is enabled, the tax amount is 10% of `5000`, which is `500`. The item's unit price becomes `4500`.
www/apps/resources/app/commerce-modules/order/transactions/page.mdx
+6 -2
View File
@@ -10,10 +10,12 @@ In this document, you’ll learn about an order’s transactions and its use.
## What is a Transaction?
A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the [Transaction data model](/references/order/models/Transaction).
A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the [OrderTransaction data model](/references/order/models/OrderTransaction).
The transaction’s main purpose is to ensure a correct balance between paid and outstanding amounts.
Transactions are also associated with returns, claims, and exchanges if additional payment or refund is required.
---
## Checking Outstanding Amount
@@ -79,11 +81,13 @@ To check the outstanding amount of the order, its transaction amounts are summed
</Table.Body>
</Table>
---
## Transaction Reference
The Order Module doesn’t provide payment processing functionalities, so it doesn’t store payments that can be processed. Payment functionalities are provided by the [Payment Module](../../payment/page.mdx).
The `Transaction` data model has two properties that determine which data model and record holds the actual payment’s details:
The `OrderTransaction` data model has two properties that determine which data model and record holds the actual payment’s details:
- `reference`: indicates the table’s name in the database. For example, `payment` from the Payment Module.
- `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
www/apps/resources/app/commerce-modules/payment/examples/page.mdx
+24 -30
View File
@@ -13,16 +13,15 @@ In this guide, you’ll find common examples of how you can use the Payment Modu
<CodeTabs groupId="app-type">
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -75,16 +74,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -141,16 +139,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -195,16 +192,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -251,16 +247,15 @@ export async function POST(request: Request) {
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -305,16 +300,15 @@ export async function GET(request: Request) {
<CodeTabs groupId="app-type" isCodeCodeTabs={true}>
<CodeTab label="Medusa API Router" value="medusa">
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function POST(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
www/apps/resources/app/commerce-modules/payment/links-to-other-modules/page.mdx
+35
View File
@@ -0,0 +1,35 @@
export const metadata = {
title: `Links between Payment Module and Other Modules`,
}
# {metadata.title}
This document showcases the module links defined between the Payment Module and other commerce modules.
## Cart Module
The Cart Module provides cart-related features, but not payment processing.
Medusa defines a link between the `Cart` and `PaymentCollection` data models. A cart has a payment collection which holds all the authorized payment sessions and payments made related to the cart.
Learn more about this relation in [this documentation](../payment-collection/page.mdx#usage-with-the-cart-module).
---
## Order 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.
![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
---
## Region Module
You can specify for each region which payment providers are available. The Medusa application defines a link between the `PaymentProvider` and the `Region` data models.
![A diagram showcasing an example of how resources from the Payment and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711569520/Medusa%20Resources/payment-region_jyo2dz.jpg)
This increases the flexibility of your store. For example, you only show during checkout the payment providers associated with the cart's region.
www/apps/resources/app/commerce-modules/payment/module-options/page.mdx
+5 -3
View File
@@ -17,8 +17,8 @@ In this document, you'll learn about the options of the Payment Module.
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-1/4">Option</Table.HeaderCell>
<Table.HeaderCell className="w-2/4">Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
@@ -93,7 +93,9 @@ In this document, you'll learn about the options of the Payment Module.
</Table.Body>
</Table>
## providers
---
## providers Option
The `providers` option is an array of payment module providers.
www/apps/resources/app/commerce-modules/payment/page.mdx
+28 -31
View File
@@ -7,7 +7,7 @@ export const metadata = {
# {metadata.title}
The Payment Module is the `@medusajs/medusa/payment` NPM package that provides payment-related features in your Medusa and Node.js applications.
The Payment Module provides payment-related features in your Medusa and Node.js applications.
## How to Use Payment Module's Service
@@ -16,18 +16,34 @@ You can use the Payment Module's main service by resolving from the Medusa conta
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const paymentModuleService = container.resolve(
Modules.PAYMENT
)
const payment_collections =
await paymentModuleService.listPaymentCollections()
})
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const paymentModuleService: IPaymentModuleService = req.scope.resolve(
const paymentModuleService = req.scope.resolve(
Modules.PAYMENT
)
@@ -40,37 +56,18 @@ export async function GET(
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function subscriberHandler({ container }: SubscriberArgs) {
const paymentModuleService: IPaymentModuleService = container.resolve(
const paymentModuleService = container.resolve(
Modules.PAYMENT
)
const payment_collections =
await paymentModuleService.listPaymentCollections()
}
```
</CodeTab>
<CodeTab label="Workflow Step" value="workflow-step">
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { IPaymentModuleService } from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
const step1 = createStep("step-1", async (_, { container }) => {
const paymentModuleService: IPaymentModuleService = container.resolve(
Modules.PAYMENT
)
const payment_collections =
await paymentModuleService.listPaymentCollections()
})
```
</CodeTab>
@@ -84,7 +81,7 @@ const step1 = createStep("step-1", async (_, { container }) => {
The Payment Module provides payment functionalities that allow you to process payment of any resource, such as a cart.
All payment processing starts with creating a payment collection.
All payment processing starts with creating a payment collection, which carries information for authorized, captured, and refunded payments for a single resource.
```ts
const paymentCollection = await paymentModuleService.createPaymentCollections({
@@ -96,7 +93,7 @@ const paymentCollection = await paymentModuleService.createPaymentCollections({
### Authorize, Capture, and Refund Payment
The Payment Module provides essential features to receive and handle payments, including authorizing, capturing, and refunding payment.
Receive and handle payments, including authorizing, capturing, and refunding payment.
```ts
await paymentModuleService.capturePayment({
www/apps/resources/app/commerce-modules/payment/payment-collection/page.mdx
+9 -7
View File
@@ -4,7 +4,7 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn what a payment collection is and how to use it with the Cart Module.
In this document, you’ll learn what a payment collection is and how the Medusa application uses it with the Cart Module.
## What's a Payment Collection?
@@ -12,15 +12,17 @@ A payment collection stores payment details related to a resource, such as a car
Every purchase or request for payment starts with a payment collection. The collection holds details necessary to complete the payment, including:
- The payment sessions that represents the payment amount to authorize.
- The payments that are created when a payment session is authorized. They can be captured and refunded.
- The payment providers that handle the processing of each payment session, including the authorization, capture, and refund.
- The [payment sessions](../payment-session/page.mdx) that represents the payment amount to authorize.
- The [payments](../payment/page.mdx) that are created when a payment session is authorized. They can be captured and refunded.
- The [payment providers](../payment-provider/page.mdx) that handle the processing of each payment session, including the authorization, capture, and refund.
---
## Multiple Payments
The payment collection supports multiple payment sessions and payments. You can use this to accept payments in increments or split payments across payment providers.
The payment collection supports multiple payment sessions and payments.
You can use this to accept payments in increments or split payments across payment providers.
![Diagram showcasing how a payment collection can have multiple payment sessions and payments](https://res.cloudinary.com/dza7lstvk/image/upload/v1711554695/Medusa%20Resources/payment-collection-multiple-payments_oi3z3n.jpg)
@@ -30,8 +32,8 @@ The payment collection supports multiple payment sessions and payments. You can
The Cart Module provides cart management features. However, it doesn’t provide any features related to accepting payment.
With the Payment Module, you can create a payment collection for the cart and process the payment.
During checkout, the Medusa application links a cart to a payment collection, which will be used for further payment processing.
The Medusa application creates a link between the `PaymentCollection` and `Cart` data models. It also implements the payment flow during checkout as explained in [this documentation](../payment-flow/page.mdx).
It also implements the payment flow during checkout as explained in [this documentation](../payment-flow/page.mdx).
![Diagram showcasing the relation between the Payment and Cart modules](https://res.cloudinary.com/dza7lstvk/image/upload/v1711537849/Medusa%20Resources/cart-payment_ixziqm.jpg)
www/apps/resources/app/commerce-modules/payment/payment-flow/page.mdx
+42 -9
View File
@@ -4,7 +4,13 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn how to implement an accept-payment flow.
In this document, you’ll learn how to implement an accept-payment flow using the Payment Module's main service.
<Note title="Tip">
For a guide on how to implement this flow in the storefront, check out [this guide](../../../storefront-development/checkout/payment/page.mdx).
</Note>
## Flow Overview
@@ -14,7 +20,7 @@ In this document, you’ll learn how to implement an accept-payment flow.
## 1. Create a Payment Collection
The payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
A payment collection holds all details related to a resource’s payment operations. So, you start off by creating a payment collection.
For example:
@@ -27,14 +33,43 @@ const paymentCollection =
})
```
You can then link the payment collection to another resource, such as a cart in the Cart Module.
<Note>
<Note title="Tip">
Learn more about the `createPaymentCollections` method in [this reference](/references/payment/createPaymentCollections).
</Note>
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 the remote link
const remoteLink = container.resolve(
ContainerRegistrationKeys
)
remoteLink.create({
[Modules.CART]: {
cart_id: "cart_123"
},
[Modules.PAYMENT]: {
payment_collection_id: paymentCollection.id
}
})
```
<Note title="Tip">
Learn more about the remote link in [this documentation](!docs!/advanced-development/module-links/remote-link).
</Note>
---
## 2. Create Payment Sessions
@@ -61,8 +96,6 @@ const paymentSession =
)
```
You can also create payment sessions for every supported payment provider to allow customers to choose from them.
<Note>
Learn more about the `createPaymentSession` method in [this reference](/references/payment/createPaymentSession).
@@ -95,9 +128,9 @@ Learn more about the `authorizePaymentSession` method in [this reference](/refer
### Handling Additional Action
If the payment authorization isn’t successful, either because it requires additional action or for another reason, the method updates the payment session with the new status and throws an error.
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 there are required actions, handle them accordingly, then retry the authorization.
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.
For example:
www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
+8 -8
View File
@@ -10,7 +10,7 @@ In this document, you’ll learn what a payment module provider is.
## What's a Payment Module Provider?
A payment module provider registers a payment provider that handles payment processing. It can integrate third-party payment providers, such as Stripe.
A payment module provider registers a payment provider that handles payment processing in the Medusa application. It integrates third-party payment providers, such as Stripe.
To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.
@@ -24,20 +24,18 @@ After the payment session is authorized, the payment provider is associated with
## System Payment Provider
The Payment Module provides a `system` payment provider that acts as a placeholder payment provider. It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
The Payment Module provides a `system` payment provider that acts as a placeholder payment provider.
It doesn’t handle payment processing and delegates that to the merchant. It acts similarly to a cash-on-delivery (COD) payment method.
---
## How are Payment Providers Created?
A payment provider is a TypeScript or JavaScript class that extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`. It can then be exported as the main service of a module.
<Note title="Tip">
A payment provider is a module whose main service extends the `AbstractPaymentProvider` imported from `@medusajs/framework/utils`.
Refer to [this guide](/references/payment/provider) on how to create a payment provider for the Payment Module.
</Note>
---
## Configure Payment Providers
@@ -50,4 +48,6 @@ Learn more about this option in [this documentation](../module-options/page.mdx#
## PaymentProvider Data Model
When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists. This data model is used to reference a payment provider and determine whether it’s installed in the application.
When the Medusa application starts and registers the payment providers, it also creates a record of the `PaymentProvider` data model if none exists.
This data model is used to reference a payment provider and determine whether it’s installed in the application.
www/apps/resources/app/commerce-modules/payment/payment-provider/stripe/page.mdx
+10 -10
View File
@@ -12,14 +12,6 @@ export const metadata = {
In this document, you’ll learn about the Stripe Module Provider and how to install and use it in the Payment Module.
## Features
[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales.
These features are also available in a safe test environment, allowing for a concern-free development process.
---
## Register the Stripe Module Provider
<Prerequisites items={[
@@ -103,7 +95,7 @@ STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>
</Table.Cell>
<Table.Cell>
-
\-
</Table.Cell>
</Table.Row>
@@ -125,7 +117,7 @@ STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>
</Table.Cell>
<Table.Cell>
-
\-
</Table.Cell>
</Table.Row>
@@ -198,6 +190,8 @@ STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>
</Table.Body>
</Table>
---
## Use Provider
To use the Stripe provider, create a payment session for the provider:
@@ -217,3 +211,9 @@ const paymentSession =
}
)
```
---
## Useful Guides
- [Storefront guide: Add Stripe payment method during checkout](../../../../storefront-development/checkout/payment/stripe/page.mdx).
www/apps/resources/app/commerce-modules/payment/payment-session/page.mdx
+1 -1
View File
@@ -10,7 +10,7 @@ In this document, you’ll learn what a payment session is.
A payment session, represented by the [PaymentSession data model](/references/payment/modules/PaymentSession), is a payment amount to be authorized. It’s associated with a payment provider that handles authorizing it.
A payment collection can have multiple payment sessions. For example, during checkout, when a customer chooses between paying with Stripe or PayPal, each of these payment options is a payment session associated with a payment provider (Stripe or PayPal).
A payment collection can have multiple payment sessions. Using this feature, you can implement payment in installments or payments using multiple providers.
![Diagram showcasing how every payment session has a different payment provider](https://res.cloudinary.com/dza7lstvk/image/upload/v1711565056/Medusa%20Resources/payment-session-provider_guxzqt.jpg)
www/apps/resources/app/commerce-modules/payment/payment/page.mdx
+1 -1
View File
@@ -10,7 +10,7 @@ In this document, you’ll learn what a payment is and how it's created, capture
When a payment session is authorized, a payment, represented by the [Payment data model](/references/payment/models/Payment), is created. This payment can later be captured or refunded.
A payment carries along many of the data and relations of a payment session:
A payment carries many of the data and relations of a payment session:
- It belongs to the same payment collection.
- It’s associated with the same payment provider, which handles further payment processing.
www/apps/resources/app/commerce-modules/payment/relations-to-other-modules/page.mdx
-33
View File
@@ -1,33 +0,0 @@
export const metadata = {
title: `Relations between Payment Module and Other Modules`,
}
# {metadata.title}
This document showcases the link modules defined between the Payment Module and other commerce modules.
## Cart Module
The Payment Module can be used with the Cart Module to accept payment for the cart during checkout.
Learn more about this relation in [this documentation](../payment-collection/page.mdx#usage-with-the-cart-module).
---
## Order Module
An order's payment is stored in a payment collection. Medusa defines a link module that builds a relationship between the `Order` and `PaymentCollection` data models.
![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
---
## Region Module
You can specify for each region which payment providers are available. The Medusa application forms a relation between the `PaymentProvider` and the `Region` data models.
![A diagram showcasing an example of how resources from the Payment and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1711569520/Medusa%20Resources/payment-region_jyo2dz.jpg)
This increases the flexibility of your store.
For example, paired with other modules, such as the Cart Module, you only show during checkout the payment providers associated with the cart's region.
www/apps/resources/app/commerce-modules/payment/webhook-events/page.mdx
+5 -3
View File
@@ -8,15 +8,17 @@ In this document, you’ll learn how the Payment Module supports listening to we
## What's a Webhook Event?
A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status. This is useful in different cases such as when a payment is being processed asynchronously or when a request is interrupted.
A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.
This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.
---
## processEvent Method
The Payment Module’s main service (`IPaymentModuleService`) provides a [processEvent method](/references/payment/processEvent) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
The Payment Module’s main service has a [processEvent method](/references/payment/processEvent) used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.
Medusa implements a webhook listener at the `/hooks/payment/[provider]` API route, where `[provider]` is the ID of the provider (for example, `stripe`). You can use that webhook listener in your third-party payment provider's configurations.
Medusa implements a webhook listener route at the `/hooks/payment/[provider]` API route, where `[provider]` is the ID of the provider (for example, `stripe`). Use that webhook listener in your third-party payment provider's configurations.
![A diagram showcasing the steps of how the processEvent method words](https://res.cloudinary.com/dza7lstvk/image/upload/v1711567415/Medusa%20Resources/payment-webhook_seaocg.jpg)
www/apps/resources/generated/edit-dates.mjs
+23 -21
View File
@@ -37,29 +37,27 @@ export const generatedEditDates = {
"app/commerce-modules/inventory/page.mdx": "2024-10-08T15:02:50.635Z",
"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",
"app/commerce-modules/order/claim/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/concepts/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/exchange/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/order-versioning/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/promotion-adjustments/page.mdx": "2024-09-30T08:43:53.161Z",
"app/commerce-modules/order/relations-to-other-modules/page.mdx": "2024-05-29T11:08:06+00:00",
"app/commerce-modules/order/return/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/tax-lines/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/transactions/page.mdx": "2024-07-09T18:14:30+03:00",
"app/commerce-modules/order/page.mdx": "2024-09-30T08:43:53.161Z",
"app/commerce-modules/order/claim/page.mdx": "2024-10-09T10:11:12.090Z",
"app/commerce-modules/order/concepts/page.mdx": "2024-10-09T10:12:49.399Z",
"app/commerce-modules/order/exchange/page.mdx": "2024-10-09T10:15:52.698Z",
"app/commerce-modules/order/order-versioning/page.mdx": "2024-10-09T07:41:22.201Z",
"app/commerce-modules/order/promotion-adjustments/page.mdx": "2024-10-09T10:19:19.333Z",
"app/commerce-modules/order/return/page.mdx": "2024-10-09T10:19:40.731Z",
"app/commerce-modules/order/tax-lines/page.mdx": "2024-10-09T10:22:49.335Z",
"app/commerce-modules/order/transactions/page.mdx": "2024-10-09T10:23:36.485Z",
"app/commerce-modules/order/page.mdx": "2024-10-09T10:27:06.773Z",
"app/commerce-modules/payment/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/payment/_events/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/payment/examples/page.mdx": "2024-09-30T08:43:53.162Z",
"app/commerce-modules/payment/module-options/page.mdx": "2024-09-30T08:43:53.162Z",
"app/commerce-modules/payment/payment/page.mdx": "2024-06-26T07:55:59+00:00",
"app/commerce-modules/payment/payment-collection/page.mdx": "2024-05-29T11:08:06+00:00",
"app/commerce-modules/payment/payment-flow/page.mdx": "2024-05-29T11:08:06+00:00",
"app/commerce-modules/payment/payment-provider/stripe/page.mdx": "2024-09-30T08:43:53.163Z",
"app/commerce-modules/payment/payment-provider/page.mdx": "2024-09-30T08:43:53.163Z",
"app/commerce-modules/payment/payment-session/page.mdx": "2024-06-26T07:55:59+00:00",
"app/commerce-modules/payment/relations-to-other-modules/page.mdx": "2024-05-29T11:08:06+00:00",
"app/commerce-modules/payment/webhook-events/page.mdx": "2024-05-29T11:08:06+00:00",
"app/commerce-modules/payment/page.mdx": "2024-09-30T08:43:53.162Z",
"app/commerce-modules/payment/examples/page.mdx": "2024-10-09T10:50:04.128Z",
"app/commerce-modules/payment/module-options/page.mdx": "2024-10-09T10:49:26.079Z",
"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": "2024-10-09T11:18:53.332Z",
"app/commerce-modules/payment/payment-provider/stripe/page.mdx": "2024-10-09T11:09:27.471Z",
"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",
"app/commerce-modules/payment/webhook-events/page.mdx": "2024-10-09T11:11:05.413Z",
"app/commerce-modules/payment/page.mdx": "2024-10-09T10:39:37.362Z",
"app/commerce-modules/pricing/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/pricing/_events/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/pricing/concepts/page.mdx": "2024-07-01T16:34:13+00:00",
@@ -2235,6 +2233,10 @@ export const generatedEditDates = {
"app/commerce-modules/cart/links-to-other-modules/page.mdx": "2024-10-08T08:22:35.190Z",
"app/commerce-modules/auth/reset-password/page.mdx": "2024-09-25T09:36:26.592Z",
"app/storefront-development/customers/reset-password/page.mdx": "2024-09-25T10:21:46.647Z",
"app/commerce-modules/order/edit/page.mdx": "2024-10-09T08:50:05.334Z",
"app/commerce-modules/order/links-to-other-modules/page.mdx": "2024-10-09T11:23:05.488Z",
"app/commerce-modules/order/order-change/page.mdx": "2024-10-09T09:59:40.745Z",
"app/commerce-modules/payment/links-to-other-modules/page.mdx": "2024-10-09T11:23:02.023Z",
"app/commerce-modules/customer/extend/page.mdx": "2024-10-08T14:18:55.407Z",
"app/commerce-modules/fulfillment/links-to-other-modules/page.mdx": "2024-10-08T14:58:24.935Z",
"app/commerce-modules/inventory/links-to-other-modules/page.mdx": "2024-10-08T15:18:30.109Z"
www/apps/resources/generated/files-map.mjs
+16 -8
View File
@@ -291,10 +291,22 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/commerce-modules/order/concepts/page.mdx",
"pathname": "/commerce-modules/order/concepts"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/edit/page.mdx",
"pathname": "/commerce-modules/order/edit"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/exchange/page.mdx",
"pathname": "/commerce-modules/order/exchange"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/links-to-other-modules/page.mdx",
"pathname": "/commerce-modules/order/links-to-other-modules"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/order-change/page.mdx",
"pathname": "/commerce-modules/order/order-change"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx",
"pathname": "/commerce-modules/order/order-versioning"
@@ -307,10 +319,6 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx",
"pathname": "/commerce-modules/order/promotion-adjustments"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/relations-to-other-modules/page.mdx",
"pathname": "/commerce-modules/order/relations-to-other-modules"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/order/return/page.mdx",
"pathname": "/commerce-modules/order/return"
@@ -331,6 +339,10 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/commerce-modules/payment/examples/page.mdx",
"pathname": "/commerce-modules/payment/examples"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/payment/links-to-other-modules/page.mdx",
"pathname": "/commerce-modules/payment/links-to-other-modules"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/payment/module-options/page.mdx",
"pathname": "/commerce-modules/payment/module-options"
@@ -363,10 +375,6 @@ export const filesMap = [
"filePath": "/www/apps/resources/app/commerce-modules/payment/payment-session/page.mdx",
"pathname": "/commerce-modules/payment/payment-session"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/payment/relations-to-other-modules/page.mdx",
"pathname": "/commerce-modules/payment/relations-to-other-modules"
},
{
"filePath": "/www/apps/resources/app/commerce-modules/payment/webhook-events/page.mdx",
"pathname": "/commerce-modules/payment/webhook-events"
www/apps/resources/generated/sidebar.mjs
+37 -14
View File
@@ -2778,8 +2778,24 @@ export const generatedSidebar = [
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/order/relations-to-other-modules",
"title": "Relations to Other Modules",
"path": "/commerce-modules/order/edit",
"title": "Order Edit",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/order/order-change",
"title": "Order Change",
"children": []
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/order/links-to-other-modules",
"title": "Links to Other Modules",
"children": []
}
]
@@ -4110,16 +4126,7 @@ export const generatedSidebar = [
"type": "link",
"path": "/commerce-modules/payment/payment-provider",
"title": "Payment Provider Module",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/payment/payment-provider/stripe",
"title": "Stripe",
"children": []
}
]
"children": []
},
{
"loaded": true,
@@ -4133,8 +4140,8 @@ export const generatedSidebar = [
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/payment/relations-to-other-modules",
"title": "Relations to Other Modules",
"path": "/commerce-modules/payment/links-to-other-modules",
"title": "Links to Other Modules",
"children": []
}
]
@@ -4163,6 +4170,22 @@ export const generatedSidebar = [
}
]
},
{
"loaded": true,
"isPathHref": true,
"type": "sub-category",
"title": "Payment Providers",
"children": [
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/commerce-modules/payment/payment-provider/stripe",
"title": "Stripe",
"children": []
}
]
},
{
"loaded": true,
"isPathHref": true,
www/apps/resources/next.config.mjs
+10
View File
@@ -44,6 +44,16 @@ const nextConfig = {
basePath: process.env.NEXT_PUBLIC_BASE_PATH || "/v2/resources",
async redirects() {
return [
{
source: "/commerce-modules/order/relations-to-other-modules",
destination: "/commerce-modules/order/links-to-other-modules",
permanent: true,
},
{
source: "/commerce-modules/payment/relations-to-other-modules",
destination: "/commerce-modules/payment/links-to-other-modules",
permanent: true,
},
{
source: "/commerce-modules/api-key/relations-to-other-modules",
destination: "/commerce-modules/api-key/links-to-other-modules",
www/apps/resources/sidebar.mjs
+25 -11
View File
@@ -637,8 +637,18 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
{
type: "link",
path: "/commerce-modules/order/relations-to-other-modules",
title: "Relations to Other Modules",
path: "/commerce-modules/order/edit",
title: "Order Edit",
},
{
type: "link",
path: "/commerce-modules/order/order-change",
title: "Order Change",
},
{
type: "link",
path: "/commerce-modules/order/links-to-other-modules",
title: "Links to Other Modules",
},
],
},
@@ -723,13 +733,6 @@ export const sidebar = sidebarAttachHrefCommonOptions([
type: "link",
path: "/commerce-modules/payment/payment-provider",
title: "Payment Provider Module",
children: [
{
type: "link",
path: "/commerce-modules/payment/payment-provider/stripe",
title: "Stripe",
},
],
},
{
type: "link",
@@ -738,8 +741,8 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
{
type: "link",
path: "/commerce-modules/payment/relations-to-other-modules",
title: "Relations to Other Modules",
path: "/commerce-modules/payment/links-to-other-modules",
title: "Links to Other Modules",
},
],
},
@@ -759,6 +762,17 @@ export const sidebar = sidebarAttachHrefCommonOptions([
},
],
},
{
type: "sub-category",
title: "Payment Providers",
children: [
{
type: "link",
path: "/commerce-modules/payment/payment-provider/stripe",
title: "Stripe",
},
],
},
{
type: "sub-category",
title: "References",