chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
224ebb2154
commit
4fe28f5a95
6187 files changed
+601447
-598226
No files matched your search
@@ -0,0 +1,50 @@
|
||||
export const metadata = {
|
||||
title: `Fulfillment Concepts`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about some basic fulfillment concepts.
|
||||
|
||||
## Fulfillment Set
|
||||
|
||||
A fulfillment set is a general form or way of fulfillment. For example, shipping is a form of fulfillment, and pick-up is another form of fulfillment. Each of these can be created as fulfillment sets.
|
||||
|
||||
A fulfillment set is represented by the `FulfillmentSet` data model. All other configurations, options, and management features are related to a fulfillment set, in one way or another. So, the first step when using the Fulfillment Module is to create a fulfillment set.
|
||||
|
||||
```ts
|
||||
const fulfillmentSets = await fulfillmentModuleService.create(
|
||||
[
|
||||
{
|
||||
name: "Shipping",
|
||||
type: "shipping",
|
||||
},
|
||||
{
|
||||
name: "Pick-up",
|
||||
type: "pick-up",
|
||||
},
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Zone
|
||||
|
||||
A service zone is a collection of geographical zones or areas. It’s used to restrict available shipping options to a defined set of locations.
|
||||
|
||||
A service zone is represented by the `ServiceZone` data model. It’s associated with a fulfillment set, as each service zone is specific to a form of fulfillment. For example, if a customer chooses to pick up items, you can restrict the available shipping options based on their location.
|
||||
|
||||
A fulfillment set can have multiple service zones, each restricting different locations.
|
||||
|
||||
|
||||
|
||||
A service zone can have multiple geographical zones, each represented by the `GeoZone` data model. It holds location-related details to narrow down supported areas, such as country, city, or province code.
|
||||
|
||||
---
|
||||
|
||||
## Shipping Profile
|
||||
|
||||
A shipping profile defines a type of items that are shipped in a similar manner. For example, a `default` shipping profile is used for all item types, but the `digital` shipping profile is used for digital items that aren’t shipped and delivered conventionally.
|
||||
|
||||
A shipping profile is represented by the `ShippingProfile` data model. It only defines the profile’s details, but it’s associated with the shipping options available for the item type.
|
||||
@@ -0,0 +1,25 @@
|
||||
export const metadata = {
|
||||
title: `Fulfillment Provider`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn what a fulfillment provider is.
|
||||
|
||||
## What’s a Fulfillment Provider?
|
||||
|
||||
A fulfillment provider implements the functionality of fulfilling items, typically using a third-party integration. It’s represented by the `FulfillmentProvider` data model.
|
||||
|
||||
---
|
||||
|
||||
## How to Create a Fulfillment Provider?
|
||||
|
||||
A fulfillment provider is a TypeScript or JavaScript class that extends the `AbstractFulfillmentProviderService` class imported from `@medusajs/utils`. You can create it part of your Medusa application codebase, in a plugin, or in a provider module.
|
||||
|
||||
---
|
||||
|
||||
## Configure Fulfillment Providers
|
||||
|
||||
The Fulfillment Module accepts a `providers` option that allows you to register providers in your application. When the Medusa application starts, it registers these modules and adds records of the `FulfillmentProvider` for them.
|
||||
|
||||
Learn more about the `providers` option in [this documentation](../module-options/page.mdx).
|
||||
@@ -0,0 +1,55 @@
|
||||
export const metadata = {
|
||||
title: `Item Fulfillment`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about the concepts of item fulfillment.
|
||||
|
||||
## Fulfillment Data Model
|
||||
|
||||
A fulfillment is the shipping and delivery of one or more items to the customer. It’s represented by the `Fulfillment` data model.
|
||||
|
||||
---
|
||||
|
||||
## Fulfillment Processing
|
||||
|
||||
A fulfillment is associated with a fulfillment provider that handles all its processing, such as creating a shipment for the fulfillment’s items.
|
||||
|
||||
The fulfillment is also associated with a shipping option of that provider, which determines how the item is shipped.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## data Field
|
||||
|
||||
The `Fulfillment` data model has a `data` field that holds any necessary data for the third-party fulfillment provider to process the fulfillment.
|
||||
|
||||
For example, the `data` field can hold the ID of the fulfillment in the third-party provider. The associated fulfillment provider then uses it whenever it retrieves the fulfillment’s details.
|
||||
|
||||
---
|
||||
|
||||
## Fulfillment Items
|
||||
|
||||
A fulfillment is used to fulfill one or more items. Each item is represented by the `FulfillmentItem` data model.
|
||||
|
||||
The fulfillment item holds details relevant to fulfilling the item, such as barcode, SKU, and quantity to fulfill.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Fulfillment Label
|
||||
|
||||
Once a shipment is created for the fulfillment, you can store its tracking number, URL, or other related details as a label, represented by the `FulfillmentLabel` data model.
|
||||
|
||||
---
|
||||
|
||||
## Fulfillment Status
|
||||
|
||||
The `Fulfillment` data model has three fields to keep track of the current status of the fulfillment:
|
||||
|
||||
- `packed_at`: The date the fulfillment was packed. If set, then the fulfillment has been packed.
|
||||
- `shipped_at`: The date the fulfillment was shipped. If set, then the fulfillment has been shipped.
|
||||
- `delivered_at`: The date the fulfillment was delivered. If set, then the fulfillment has been delivered.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
sidebar_label: "Module Options"
|
||||
---
|
||||
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Fulfillment Module Options`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn about the options of the Fulfillment Module.
|
||||
|
||||
## providers
|
||||
|
||||
The `providers` option is an array of either fulfillment provider modules, fulfillment plugins, or path to a file that holds a fulfillment provider.
|
||||
|
||||
When the Medusa application starts, these providers are registered and can be used to process fulfillments.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const modules = {
|
||||
// ...
|
||||
fulfillment: {
|
||||
resolve: "@medusajs/fulfillment",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: `@medusajs/fulfillment-manual`,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
The `providers` option is an array of objects that accept the following properties:
|
||||
|
||||
- `resolve`: A string indicating the package name of the fulfillment provider module or the fulfillment plugin, or the path to the file defining the fulfillment provider.
|
||||
- `options`: An optional object of options to pass to the fulfillment provider.
|
||||
@@ -0,0 +1,198 @@
|
||||
import { CodeTabs, CodeTab } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Fulfillment Module`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
The Fulfillment Module is the `@medusajs/fulfillment` NPM package that provides fulfillment-related features in your Medusa and Node.js applications.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Fulfillment Management
|
||||
|
||||
Create fulfillments and keep track of their statuses, items, and more.
|
||||
|
||||
```ts
|
||||
const fulfillment =
|
||||
await fulfillmentModuleService.createFulfillment({
|
||||
location_id: "loc_123",
|
||||
provider_id: "webshipper",
|
||||
delivery_address: {
|
||||
country_code: "us",
|
||||
city: "Strongsville",
|
||||
address_1: "18290 Royalton Rd",
|
||||
},
|
||||
items: [
|
||||
{
|
||||
title: "Shirt",
|
||||
sku: "SHIRT",
|
||||
quantity: 1,
|
||||
barcode: "123456",
|
||||
},
|
||||
],
|
||||
labels: [],
|
||||
order: {},
|
||||
})
|
||||
```
|
||||
|
||||
### Integrate Third-Party Fulfillment Providers
|
||||
|
||||
Use third-party fulfillment providers to provide customers with shipping options and fulfill their orders.
|
||||
|
||||
```ts
|
||||
const shippingOption =
|
||||
await fulfillmentModuleService.createShippingOptions({
|
||||
name: "Express shipping",
|
||||
// ...
|
||||
provider_id: "webshipper",
|
||||
})
|
||||
```
|
||||
|
||||
### Restrict By Location and Rules
|
||||
|
||||
Shipping options can be restricted to specific geographical locations. You can also specify custom rules to restrict shipping options.
|
||||
|
||||
```ts
|
||||
const serviceZone =
|
||||
await fulfillmentModuleService.createServiceZones({
|
||||
name: "US",
|
||||
fulfillment_set_id: "fset_123",
|
||||
geo_zones: [
|
||||
{
|
||||
type: "country",
|
||||
country_code: "us",
|
||||
},
|
||||
],
|
||||
})
|
||||
|
||||
const shippingOption =
|
||||
await fulfillmentModuleService.createShippingOptions({
|
||||
name: "Express Shipping",
|
||||
// restrict location
|
||||
service_zone_id: serviceZone.id,
|
||||
// restrict by custom rules
|
||||
rules: [
|
||||
{
|
||||
field: "customer_group",
|
||||
operator: "eq",
|
||||
value: "vip",
|
||||
},
|
||||
],
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### Support Different Fulfillment Forms
|
||||
|
||||
Support various fulfillment forms, such as shipping or pick up.
|
||||
|
||||
```ts
|
||||
const fulfillmentSets = await fulfillmentModuleService.create(
|
||||
[
|
||||
{
|
||||
name: "Shipping",
|
||||
type: "shipping",
|
||||
},
|
||||
{
|
||||
name: "Pick-up",
|
||||
type: "pick-up",
|
||||
},
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configure Fulfillment Module
|
||||
|
||||
After installing the `@medusajs/fulfillment` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const modules = {
|
||||
// ...
|
||||
fulfillment: {
|
||||
resolve: "@medusajs/fulfillment",
|
||||
providers: [
|
||||
// ...
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Module Options
|
||||
|
||||
Refer to [this documentation](./module-options/page.mdx) for details on the module's options.
|
||||
|
||||
---
|
||||
|
||||
## How to Use Fulfillment Module's Service
|
||||
|
||||
You can use the Fulfillment Module's main service by resolving from the Medusa container the resource `ModuleRegistrationName.API_KEY` imported from `@medusajs/modules-sdk`.
|
||||
|
||||
For example:
|
||||
|
||||
<CodeTabs groupId="resource-type">
|
||||
<CodeTab label="API Route" value="api-route">
|
||||
|
||||
```ts title="src/api/store/custom/route.ts"
|
||||
import { MedusaRequest, MedusaResponse } from "@medusajs/medusa"
|
||||
import { IFulfillmentModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
export async function GET(
|
||||
req: MedusaRequest,
|
||||
res: MedusaResponse
|
||||
): Promise<void> {
|
||||
const fulfillmentModuleService: IFulfillmentModuleService =
|
||||
req.scope.resolve(ModuleRegistrationName.FULFILLMENT)
|
||||
|
||||
res.json({
|
||||
fulfillments:
|
||||
await fulfillmentModuleService.listFulfillments(),
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="Subscriber" value="subscribers">
|
||||
|
||||
```ts title="src/subscribers/custom-handler.ts"
|
||||
import { SubscriberArgs } from "@medusajs/medusa"
|
||||
import { IFulfillmentModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
export default async function subscriberHandler({
|
||||
container,
|
||||
}: SubscriberArgs) {
|
||||
const fulfillmentModuleService: IFulfillmentModuleService =
|
||||
container.resolve(ModuleRegistrationName.FULFILLMENT)
|
||||
|
||||
const fulfillments =
|
||||
await fulfillmentModuleService.listFulfillments()
|
||||
}
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
<CodeTab label="Workflow Step" value="workflow-step">
|
||||
|
||||
```ts title="src/workflows/hello-world/step1.ts"
|
||||
import { createStep } from "@medusajs/workflows-sdk"
|
||||
import { IFulfillmentModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
const step1 = createStep("step-1", async (_, context) => {
|
||||
const fulfillmentModuleService: IFulfillmentModuleService =
|
||||
context.container.resolve(
|
||||
ModuleRegistrationName.FULFILLMENT
|
||||
)
|
||||
const fulfillments =
|
||||
await fulfillmentModuleService.listFulfillments()
|
||||
})
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
</CodeTabs>
|
||||
+17
@@ -0,0 +1,17 @@
|
||||
export const metadata = {
|
||||
title: `Relations between Fulfillment Module and Other Modules`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
When Commerce Modules are used together in a Medusa application, the Medusa application handles building the relations between these modules.
|
||||
|
||||
This document showcases the relation between the Fulfillment Module and other Commerce Modules.
|
||||
|
||||
## Stock Location Module
|
||||
|
||||
When the Fulfillment and Stock Location modules are used together, a fulfillment set can be conditioned to a specific stock location.
|
||||
|
||||
The Medusa application forms a relation between the `FulfillmentSet` and `StockLocation` data models.
|
||||
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
export const metadata = {
|
||||
title: `Shipping Options`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about shipping options and their rules.
|
||||
|
||||
## What’s 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.
|
||||
|
||||
When the customer places their order, they choose a shipping option to be used to fulfill their items.
|
||||
|
||||
A shipping option is represented by the `ShippingOption` data model.
|
||||
|
||||
---
|
||||
|
||||
## Service Zone Restrictions
|
||||
|
||||
A shipping option is restricted by a service zone, which specifies in what locations can a shipping option be used.
|
||||
|
||||
For example, a fulfillment provider may have a shipping option that can be used in the United States, and another in Canada.
|
||||
|
||||
|
||||
|
||||
Service zones can be more restrictive, such as restricting to certain cities or province codes.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Shipping Option Rules
|
||||
|
||||
You can restrict shipping options by custom rules, such as the item’s weight or the customer’s group.
|
||||
|
||||
These rules are represented by the `ShippingOptionRule` data model. Its fields define the custom rule:
|
||||
|
||||
- `field`: The name of an field or table that the rule applies to. For example, `customer_group`.
|
||||
- `value`: One or more values.
|
||||
- `operator`: The operator used in the condition. For example:
|
||||
- To allow multiple values, use the operator `in`, which validates that the provided values are in the rule’s values.
|
||||
- To create a negation condition that considers `value` against the rule, use `nin`, which validates that the provided values aren’t in the rule’s values.
|
||||
- Check out more operators in [this reference](/references/fulfillment/types/fulfillment.RuleOperatorType).
|
||||
|
||||
|
||||
|
||||
A shipping option can have multiple rules. For example, a shipping option is available if the customer belongs to the VIP group and the total weight is less than 2000g.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Shipping Profile 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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## data Field
|
||||
|
||||
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` field. It's an object that stores custom data relevant later when creating and processing a fulfillment.
|
||||
Reference in new issue
Block a user