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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser
2024-12-26 10:32:16 +02:00
committed by GitHub
parent c8f9938865
commit ebca8fed28
112 changed files with 9465 additions and 7731 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/order/links-to-other-modules/page.mdx
+32 -32
View File
@@ -47,8 +47,8 @@ To retrieve the customer of an order with [Query](!docs!/learn/fundamentals/modu
const { data: orders } = await query.graph({
entity: "order",
fields: [
"customer.*"
]
"customer.*",
],
})
// orders.customer
@@ -65,8 +65,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"customer.*"
]
"customer.*",
],
})
// orders.customer
@@ -96,8 +96,8 @@ To retrieve the cart of an order with [Query](!docs!/learn/fundamentals/module-l
const { data: orders } = await query.graph({
entity: "order",
fields: [
"cart.*"
]
"cart.*",
],
})
// orders.cart
@@ -114,8 +114,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"cart.*"
]
"cart.*",
],
})
// orders.cart
@@ -197,8 +197,8 @@ To retrieve the fulfillments of a return, pass `fulfillments.*` in `fields`.
const { data: orders } = await query.graph({
entity: "order",
fields: [
"fulfillments.*"
]
"fulfillments.*",
],
})
// orders.fulfillments
@@ -215,8 +215,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"fulfillments.*"
]
"fulfillments.*",
],
})
// orders.fulfillments
@@ -290,8 +290,8 @@ To retrieve the payment collections of an order, order exchange, or order claim
const { data: orders } = await query.graph({
entity: "order",
fields: [
"payment_collections.*"
]
"payment_collections.*",
],
})
// orders.payment_collections
@@ -308,8 +308,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"payment_collections.*"
]
"payment_collections.*",
],
})
// orders.payment_collections
@@ -388,8 +388,8 @@ To retrieve the product, pass `product.*` in `fields`.
const { data: lineItems } = await query.graph({
entity: "order_line_item",
fields: [
"variant.*"
]
"variant.*",
],
})
// lineItems.variant
@@ -406,8 +406,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: lineItems } = useQueryGraphStep({
entity: "order_line_item",
fields: [
"variant.*"
]
"variant.*",
],
})
// lineItems.variant
@@ -435,8 +435,8 @@ To retrieve the promotion applied on an order with [Query](!docs!/learn/fundamen
const { data: orders } = await query.graph({
entity: "order",
fields: [
"promotion.*"
]
"promotion.*",
],
})
// orders.promotion
@@ -453,8 +453,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"promotion.*"
]
"promotion.*",
],
})
// orders.promotion
@@ -524,8 +524,8 @@ To retrieve the region of an order with [Query](!docs!/learn/fundamentals/module
const { data: orders } = await query.graph({
entity: "order",
fields: [
"region.*"
]
"region.*",
],
})
// orders.region
@@ -542,8 +542,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"region.*"
]
"region.*",
],
})
// orders.region
@@ -569,8 +569,8 @@ To retrieve the sales channel of an order with [Query](!docs!/learn/fundamentals
const { data: orders } = await query.graph({
entity: "order",
fields: [
"sales_channel.*"
]
"sales_channel.*",
],
})
// orders.sales_channel
@@ -587,8 +587,8 @@ import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
const { data: orders } = useQueryGraphStep({
entity: "order",
fields: [
"sales_channel.*"
]
"sales_channel.*",
],
})
// orders.sales_channel
www/apps/resources/app/commerce-modules/order/page.mdx
+135 -104
View File
@@ -6,138 +6,169 @@ export const metadata = {
# {metadata.title}
The Order Module provides order-related features in your Medusa and Node.js applications.
In this section of the documentation, you will find resources to learn more about the Order Module and how to use it in your application.
## How to Use Order Module's Service
Medusa has order related features available out-of-the-box through the Order Module. A [module](!docs!/learn/fundamentals/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Order Module.
You can use the Order Module's main service by resolving from the Medusa container the resource `Modules.ORDER`.
<Note>
Learn more about why modules are isolated in [this documentation](!docs!/learn/fundamentals/modules/isolation).
</Note>
## Order Features
- [Order Management](./concepts/page.mdx): Store and manage your orders to retrieve, create, cancel, and perform other operations.
- Draft Orders: Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
- [Apply Promotion Adjustments](./promotion-adjustments/page.mdx): Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
- [Apply Tax Lines](./tax-lines/page.mdx): Apply tax lines to an order's line items and shipping methods.
- [Returns](./return/page.mdx), [Edits](./edit/page.mdx), [Exchanges](./exchange/page.mdx), and [Claims](./claim/page.mdx): Make [changes](./order-change/page.mdx) to an order to edit, return, or exchange its items, with [version-based control](./order-versioning/page.mdx) over the order's timeline.
---
## How to Use the Order Module
In your Medusa application, you build flows around commerce modules. A flow is built as a [Workflow](!docs!/learn/fundamentals/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs/medusa/core-flows` package.
For example:
<CodeTabs groupId="resource-type">
<CodeTab label="Workflow Step" value="workflow-step">
export const highlights = [
["12", "Modules.ORDER", "Resolve the module in a step."]
]
```ts title="src/workflows/hello-world/step1.ts"
import { createStep } from "@medusajs/framework/workflows-sdk"
```ts title="src/workflows/create-draft-order.ts" highlights={highlights}
import {
createWorkflow,
WorkflowResponse,
createStep,
StepResponse,
} 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()
})
const createDraftOrderStep = createStep(
"create-order",
async ({}, { container }) => {
const orderModuleService = container.resolve(Modules.ORDER)
const draftOrder = await orderModuleService.createOrders({
currency_code: "usd",
items: [
{
title: "Shirt",
quantity: 1,
unit_price: 3000,
},
],
shipping_methods: [
{
name: "Express shipping",
amount: 3000,
},
],
status: "draft",
})
return new StepResponse({ draftOrder }, draftOrder.id)
},
async (draftOrderId, { container }) => {
if (!draftOrderId) {
return
}
const orderModuleService = container.resolve(Modules.ORDER)
await orderModuleService.deleteOrders([draftOrderId])
}
)
export const createDraftOrderWorkflow = createWorkflow(
"create-draft-order",
() => {
const { draftOrder } = createDraftOrderStep()
return new WorkflowResponse({
draftOrder,
})
}
)
```
</CodeTab>
<CodeTab label="API Route" value="api-route">
You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:
```ts title="src/api/store/custom/route.ts"
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { Modules } from "@medusajs/framework/utils"
<CodeTabs group="resource-types">
<CodeTab label="API Route" value="api-route">
```ts title="src/api/workflow/route.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import type {
MedusaRequest,
MedusaResponse,
} from "@medusajs/framework/http"
import { createDraftOrderWorkflow } from "../../workflows/create-draft-order"
export async function GET(
req: MedusaRequest,
res: MedusaResponse
): Promise<void> {
const orderModuleService = req.scope.resolve(
Modules.ORDER
)
) {
const { result } = await createDraftOrderWorkflow(req.scope)
.run()
res.json({
orders: await orderModuleService.listOrders(),
})
res.send(result)
}
```
</CodeTab>
<CodeTab label="Subscriber" value="subscribers">
<CodeTab label="Subscriber" value="subscriber">
```ts title="src/subscribers/user-created.ts" highlights={[["11"], ["12"]]} collapsibleLines="1-6" expandButtonLabel="Show Imports"
import {
type SubscriberConfig,
type SubscriberArgs,
} from "@medusajs/framework"
import { createDraftOrderWorkflow } from "../workflows/create-draft-order"
```ts title="src/subscribers/custom-handler.ts"
import { SubscriberArgs } from "@medusajs/framework"
import { Modules } from "@medusajs/framework/utils"
export default async function handleUserCreated({
event: { data },
container,
}: SubscriberArgs<{ id: string }>) {
const { result } = await createDraftOrderWorkflow(container)
.run()
export default async function subscriberHandler({ container }: SubscriberArgs) {
const orderModuleService = container.resolve(
Modules.ORDER
)
console.log(result)
}
const orders = await orderModuleService.listOrders()
export const config: SubscriberConfig = {
event: "user.created",
}
```
</CodeTab>
<CodeTab label="Scheduled Job" value="scheduled-job">
```ts title="src/jobs/run-daily.ts" highlights={[["7"], ["8"]]}
import { MedusaContainer } from "@medusajs/framework/types"
import { createDraftOrderWorkflow } from "../workflows/create-draft-order"
export default async function myCustomJob(
container: MedusaContainer
) {
const { result } = await createDraftOrderWorkflow(container)
.run()
console.log(result)
}
export const config = {
name: "run-once-a-day",
schedule: `0 0 * * *`,
}
```
</CodeTab>
</CodeTabs>
Learn more about workflows in [this documentation](!docs!/learn/fundamentals/workflows).
---
## Features
### Order Management
Store and manage your orders to retrieve, create, cancel, and perform other operations.
```ts
const order = await orderModuleService.createOrders({
currency_code: "usd",
items: [
{
title: "Shirt",
quantity: 1,
unit_price: 3000,
},
],
shipping_methods: [
{
name: "Express shipping",
amount: 3000,
},
],
})
```
### Draft Orders
Allow merchants to create orders on behalf of their customers as draft orders that later are transformed to regular orders.
```ts
const draftOrder = await orderModuleService.createOrders({
currency_code: "usd",
// other details...
status: "draft",
is_draft_order: true,
})
```
### Apply Promotions
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.createOrderLineItemAdjustments({
item_id: "cali_123",
code: "50OFF",
amount: 500,
})
const shippingAdjustments =
await orderModuleService.createOrderShippingMethodAdjustments({
shipping_method_id: "casm_123",
code: "FREESHIPPING",
amount: 1000,
})
```
### Returns, Exchanges, and Claims
Return or exchange items, with version-based control over the order's timeline.
```ts
const orderReturn = await orderModuleService.createReturn({
order_id: "order_123",
items: [{
id: "orditem_123",
quantity: 1,
}],
})
```
<CommerceModuleSections name="Order" />