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

docs: docs for next release (#13303)

Browse Source 
* added draft order plugin docs

* fix vale error

* added note about draft order being optional

* add new shipping option - shipping method link

* update user guides

* generate

* fix github icon

* changes to shipping option type

* document logger

* reorder list

* fixes

* fixes
This commit is contained in:
Shahed Nasser
2025-08-28 18:49:07 +03:00
committed by GitHub
parent 94effdcda7
commit d510639193
55 changed files with 1653 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/cart/links-to-other-modules/page.mdx
+65
View File
@@ -61,6 +61,20 @@ Read-only links are used to query data across modules, but the relations aren't
[Learn more](#customer-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[ShippingMethod](/references/cart/models/ShippingMethod)
</Table.Cell>
<Table.Cell>
[ShippingOption](/references/fulfillment/models/ShippingOption) in [Fulfillment Module](../../fulfillment/page.mdx)
</Table.Cell>
<Table.Cell>
Read-only - has one
</Table.Cell>
<Table.Cell>
[Learn more](#fulfillment-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Order](/references/order/models/Order) in [Order Module](../../order/page.mdx)
@@ -211,6 +225,57 @@ const { data: carts } = useQueryGraphStep({
---
## Fulfillment Module
Medusa defines a read-only link between the `ShippingMethod` data model and the [Fulfillment Module](../../fulfillment/page.mdx)'s `ShippingOption` data model. This means you can retrieve the details of a shipping method's shipping option, but you don't manage the links in a pivot table in the database. The shipping option of a shipping method is determined by the `shipping_option_id` property of the `ShippingMethod` data model.
This link allows you to retrieve the shipping option that a shipping method was created from.
<Note>
This read-only link was added in [Medusa v2.10.0](https://github.com/medusajs/medusa/releases/tag/v2.10.0)
</Note>
### Retrieve with Query
To retrieve the shipping option of a shipping method with [Query](!docs!/learn/fundamentals/module-links/query), pass `shipping_option.*` in `fields`:
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: shippingMethods } = await query.graph({
entity: "shipping_method",
fields: [
"shipping_option.*",
],
})
// shippingMethods[0].shipping_option
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: shippingMethods } = useQueryGraphStep({
entity: "shipping_method",
fields: [
"shipping_option.*",
],
})
// shippingMethods[0].shipping_option
```
</CodeTab>
</CodeTabs>
## Order Module
The [Order Module](../../order/page.mdx) provides order-management features.
www/apps/resources/app/commerce-modules/fulfillment/links-to-other-modules/page.mdx
+67
View File
@@ -38,6 +38,20 @@ The Fulfillment Module has the following links to other modules:
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
[ShippingMethod](/references/cart/models/ShippingMethod) in [Cart Module](../../cart/page.mdx)
</Table.Cell>
<Table.Cell>
[ShippingOption](/references/fulfillment/models/ShippingOption)
</Table.Cell>
<Table.Cell>
Read-only - has one
</Table.Cell>
<Table.Cell>
[Learn more](#cart-module)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
[Order](/references/order/models/Order) in [Order Module](../../order/page.mdx)
@@ -127,6 +141,59 @@ The Fulfillment Module has the following links to other modules:
---
## Cart Module
Medusa defines a read-only link between the `ShippingMethod` data model of the [Cart Module](../../cart/page.mdx) and the `ShippingOption` data model. This means you can retrieve the details of a shipping method's shipping option, but you don't manage the links in a pivot table in the database. The shipping option of a shipping method is determined by the `shipping_option_id` property of the `ShippingMethod` data model.
This link allows you to retrieve the shipping option that a shipping method was created from.
<Note>
This read-only link was added in [Medusa v2.10.0](https://github.com/medusajs/medusa/releases/tag/v2.10.0)
</Note>
### Retrieve with Query
To retrieve the shipping option of a shipping method with [Query](!docs!/learn/fundamentals/module-links/query), pass `shipping_option.*` in `fields`:
<CodeTabs group="relation-query">
<CodeTab label="query.graph" value="method">
```ts
const { data: shippingMethods } = await query.graph({
entity: "shipping_method",
fields: [
"shipping_option.*",
],
})
// shippingMethods[0].shipping_option
```
</CodeTab>
<CodeTab label="useQueryGraphStep" value="step">
```ts
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
// ...
const { data: shippingMethods } = useQueryGraphStep({
entity: "shipping_method",
fields: [
"shipping_option.*",
],
})
// shippingMethods[0].shipping_option
```
</CodeTab>
</CodeTabs>
---
## Order Module
The [Order Module](../../order/page.mdx) provides order-management functionalities.
www/apps/resources/app/commerce-modules/fulfillment/shipping-option/page.mdx
+17 -15
View File
@@ -6,11 +6,11 @@ export const metadata = {
In this document, you’ll learn about shipping options and their rules.
## What’s a Shipping Option?
## What is a Shipping Option?
A shipping option is a way of shipping an item. Each fulfillment provider provides a set of shipping options. For example, a provider may provide a shipping option for express shipping and another for standard shipping.
A shipping option is a way of shipping an item. Each fulfillment provider offers a set of shipping options. For example, a provider may offer a shipping option for express shipping and another for standard shipping.
When the customer places their order, they choose a shipping option to be used to fulfill their items.
When the customer places an order, they choose a shipping option to fulfill their items.
A shipping option is represented by the [ShippingOption data model](/references/fulfillment/models/ShippingOption).
@@ -18,17 +18,17 @@ A shipping option is represented by the [ShippingOption data model](/references/
## Service Zone Restrictions
A shipping option is restricted by a service zone, limiting the locations a shipping option be used in.
A shipping option is restricted by a service zone, which limits the locations where the shipping option can be used.
For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
For example, a fulfillment provider may have a shipping option that can be used in the United States and another in Canada.
![A diagram showcasing the relation between shipping options and service zones.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712330831/Medusa%20Resources/shipping-option-service-zone_pobh6k.jpg)
Service zones can be more restrictive, such as restricting to certain cities or province codes.
Service zones can be more restrictive, such as limiting to certain cities or province codes.
<Note title="Tip">
The province code is always in lower-case and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
The province code is always in lowercase and in [ISO 3166-2 format](https://en.wikipedia.org/wiki/ISO_3166-2).
</Note>
@@ -38,15 +38,15 @@ The province code is always in lower-case and in [ISO 3166-2 format](https://en.
## Shipping Option Rules
You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
You can restrict shipping options by custom rules, such as the item’s weight or the customer group.
<Note title="Tip">
You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart's total. Learn more in the Pricing Module's [Price Rules](../../pricing/price-rules/page.mdx#how-to-set-rules-on-a-price) guide.
You can also restrict a shipping option's price based on specific conditions. For example, you can make a shipping option's price free based on the cart total. Learn more in the Pricing Module's [Price Rules](../../pricing/price-rules/page.mdx#how-to-set-rules-on-a-price) guide.
</Note>
These rules are represented by the [ShippingOptionRule data model](/references/fulfillment/models/ShippingOptionRule). Its properties define the custom rule:
These rules are represented by the [ShippingOptionRule data model](/references/fulfillment/models/ShippingOptionRule). Its properties define the custom rules:
- `attribute`: The name of a property or table that the rule applies to. For example, `customer_group`.
- `operator`: The operator used in the condition. For example:
@@ -62,16 +62,18 @@ A shipping option can have multiple rules. For example, you can add rules to a s
---
## Shipping Profile and Types
## Shipping Profiles and Types
A shipping option belongs to a type. For example, a shipping option’s type may be `express`, while another `standard`. The type is represented by the [ShippingOptionType data model](/references/fulfillment/models/ShippingOptionType).
A shipping option belongs to a type and a profile.
A shipping option also belongs to a shipping profile, as each shipping profile defines the type of items to be shipped in a similar manner.
A shipping option type defines a group of shipping options with shared shipping characteristics. For example, a shipping option’s type may be `express`, while another may be `standard`. The type is represented by the [ShippingOptionType data model](/references/fulfillment/models/ShippingOptionType).
A shipping profile defines a group of items (such as products) that are shipped in a similar manner. For example, the "Standard" shipping profile applies to all products, whereas the "Digital" shipping profile applies to digital products. Shipping profiles are represented by the [ShippingProfile data model](/references/fulfillment/models/ShippingProfile).
---
## data Property
When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order-creation process.
When fulfilling an item, you might use a third-party fulfillment provider that requires additional custom data to be passed along from the checkout or order creation process.
The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant later when creating and processing a fulfillment.
The `ShippingOption` data model has a `data` property. It's an object that stores custom data relevant for creating and processing a fulfillment later.
www/apps/resources/app/commerce-modules/order/draft-orders/page.mdx
+112
View File
@@ -0,0 +1,112 @@
import { Prerequisites } from "docs-ui"
export const metadata = {
title: `Draft Orders Plugin`,
}
# {metadata.title}
In this guide, you'll learn about the Draft Orders Plugin and its features.
<Note>
The Draft Orders Plugin was initially only available to Cloud users during its early access phase. It is now available for all Medusa users.
</Note>
## What is the Draft Orders Plugin?
The Draft Orders Plugin is a Medusa plugin that allows admin users to create and manage draft orders on behalf of customers from the Medusa Admin.
The Medusa application already has the foundation to support draft orders, including data models and API routes. This plugin adds a user interface for managing draft orders in the Medusa Admin dashboard.
The Draft Orders Plugin is especially useful for handling customer support scenarios or when a customer places an order offline, such as over the phone or in-store.
### Features
- [Create draft orders from the Medusa Admin.](!user-guide!/orders/draft-orders/create)
- [Manage items in a draft order, allowing admin users to add, update, or remove items](!user-guide!/orders/draft-orders/manage#manage-draft-orders-items).
- [Add shipping methods to draft orders.](!user-guide!/orders/draft-orders/manage#manage-draft-orders-shipping-methods).
- [Associate existing customers with draft orders.](!user-guide!/orders/draft-orders/manage#manage-draft-orders-customer-details).
- [Convert draft orders to regular orders.](!user-guide!/orders/draft-orders/manage#convert-draft-order-to-regular-order).
---
## Install the Draft Orders Plugin
The Draft Orders Plugin is available in all Medusa applications starting v2.10.0.
For earlier versions, you can install the plugin manually.
<Prerequisites
items={[
{
text: "Medusa application >= v2.4.0",
link: "!docs!/learn/installation"
}
]}
/>
To install the Draft Orders Plugin:
1. Run the following command in your Medusa application's directory:
```bash npm2yarn
npm install @medusajs/draft-order
```
2. Add the plugin to your `medusa-config.ts` file:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
plugins: [
{
resolve: "@medusajs/draft-order",
options: {},
},
],
})
```
### Test the Draft Orders Plugin
To test the Draft Orders Plugin, start the Medusa application with the following command:
```bash npm2yarn
npm run dev
```
If you open the Medusa Admin at `localhost:9000/app` and log in, you'll find an "Orders -> Drafts" sidebar item.
---
## Draft Orders User Guides
To learn how to use the draft order features in the Medusa Admin, refer to the [Draft Orders](!user-guide!/orders/draft-orders) user guides.
---
## How Draft Orders Work
A draft order is stored in the database as a regular order. It is represented by the [Order data model](/references/order/models/Order) with the following properties:
- `status`: Set to `draft` to indicate that the order is a draft.
- `is_draft_order`: Set to `true` to indicate that the order is a draft order.
So, the same [order concepts](../concepts/page.mdx) apply to draft orders as well.
### Editing Draft Orders
Similar to regular orders, draft orders can be [edited](../edit/page.mdx), allowing admin users to add, update, or remove items, as well as add shipping methods.
When the order edit is confirmed on the draft order, the changes are applied directly to the draft order and its [version](../order-versioning/page.mdx) is incremented.
### Converting Draft Orders to Regular Orders
Once a draft order is finalized and ready for processing, it can be converted to a regular order. This involves:
- Changing its `status` property to `pending`.
- Changing its `is_draft_order` property to `false`.
Admin users can then manage the order like any other regular order, including processing payments and fulfilling items.
www/apps/resources/app/commerce-modules/order/page.mdx
+1 -1
View File
@@ -29,7 +29,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
## 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.
- [Draft Orders](./draft-orders/page.mdx): 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.