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

Merge branch 'master' into develop

Browse Source
This commit is contained in:
olivermrbl
2022-09-14 10:25:03 +02:00
parent 992ef733f4 9be3860fa5
commit b227fcb163
122 changed files with 971 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
docs/content/add-plugins/strapi.md
View File

@@ -1,190 +1,178 @@
# Strapi
Use [Medusa](https://github.com/medusajs/medusa) and [Strapi](https://github.com/strapi/strapi) to power your commerce setup for a full open-source headless solution. In recent years, it has become increasingly popular to go with a headless approach when building ecommerce, blogs, portfolios, and the likes. Among many benefits, you get improved performance, more customizability, and support to scale as your business grows.
In this document, you’ll learn how to integrate Strapi with Medusa to add rich CMS functionalities.
A headless system is essentially a decoupling of presentational layers and backend. It cuts off the traditional proprietary frontend displaying your content (hence the name), and instead gives you Rest APIs, you can consume from whatever system, client, or service you would like.
:::info
Going with the headless approach when building your setup will provide you with a modular system with best-in-breed services within each specific area of your stack; CMS, ecommerce, etc. This is in contrast to how you would traditionally choose a monolithic platform that partly (or hardly) caters to all of your needs.
This article will guide you through setting up a headless ecommerce setup in which content is managed by [Strapi](http://strapi.io) and the ecommerce is powered by [Medusa](https://github.com/medusajs/medusa) - on a 100% open-source stack.
## Why Medusa, and why Strapi?
The bottleneck of headless ecommerce systems is most often the amount of resources it requires to both get started and to maintain. You need backend developers to handle your infrastructure and integrations and frontend developers to build the customer experience. This is one of the reasons many existing headless solutions target enterprise businesses. To allow for small to mid-sized businesses to enter the space, one must cater to the developer experience. If the onboarding, setup, and implementation process are all easy to approach, you no longer need a team of ten to build a scalable ecommerce setup.
Strapi and Medusa are two systems built primarily for developers and the combination of the two enables you to build an ecommerce store with a blazingly fast, content-rich frontend and a highly extendable backend.
Both projects are open-source, headless, and built with Node.js. They use a very similar architecture for plugins and customizations, that gives you the ability to extend your commerce and CMS to fit exactly your needs. Let's now dive into the installation and setup of the two.
## Installation
The following guide for setting up the plugin assumes, that you are familiar with both Strapi and Medusa. If this is not the case, visit the official [Medusa](https://docs.medusajs.com/tutorial/set-up-your-development-environment) and [Strapi](https://strapi.io/documentation/developer-docs/latest/getting-started/introduction.html) documentation.
### Setting up Medusa
First, create a Medusa project using your favorite package manager. You can go about this in two ways:
**Use `npx`**
`npx create-medusa-app` will allow you to create a Medusa store engine, a storefront, and Medusa admin in a single command
```bash
npx create-medusa-app
```
Alternatively, using Yarn:
```bash
yarn create medusa-app
```
:::note
When choosing `npx` you are shown different store engine options as part of the setup. For this Strapi tutorial, you should choose `medusa-starter-default`. Optionally, pick a storefront.
This plugin is a [community plugin](https://github.com/Deathwish98/medusa-plugin-strapi) and is not managed by the official Medusa team.
:::
**Use `medusa-cli`**
`@medusajs/medusa-cli` is our Command Line Tool for creating the Medusa store engine (alongside many other powerful commands). First, install it:
## Overview
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
[Strapi](https://strapi.io/) is an open source headless CMS service that allows developers to have complete control over their content models. It can be integrated into many other frameworks, including Medusa.
Then, initialize a Medusa project:
By integrating Strapi to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, [two-way sync](#test-two-way-sync), an easy-to-use interface to use for static content and pages, and much more.
## Prerequisites
### Medusa CLI
[Medusa’s CLI tool](../cli/reference.md#how-to-install-cli-tool) is required to set up a new Medusa server.
### Redis
Redis is required for the Strapi plugin to work as expected on your Medusa server. If you don’t have it installed, you can learn [how to install it in this documentation](../tutorial/0-set-up-your-development-environment.mdx#redis).
## Create Strapi Project
The first step is to create a Strapi project using the Medusa template:
```bash
medusa new my-medusa-store
npx create-strapi-app strapi-medusa --template shahednasser/strapi-medusa-template
```
Medusa uses Redis for emitting events in the system, so ensure, that this is installed and running
This creates the Strapi project in the directory `strapi-medusa`.
```
$ redis-cli
127.0.0.1:6379> ping
PONG
```
Once the installation is finished, the Strapi development server will run on `localhost:1337`. A new page will also open in your default browser to create a new admin user and log in.
And in `medusa-config.js` you should enable it. Your project config in the bottom of the file should look similar to this:
![Create User Form in Strapi](https://i.imgur.com/9pFE1Ij.png)
Once you log in, you can access the Strapi dashboard.
### Create a Strapi User
The Strapi plugin in Medusa requires the credentials of a Strapi user. To create a new user, go to Content Manager, then choose User under Collection Types.
![Showing the users under Content Manager](https://i.imgur.com/YyGJPUf.png)
Click on the Create new entry button at the top right. This opens a new form to enter the user’s details.
![Create User Form on Strapi](https://i.imgur.com/mdMhSlV.png)
Enter the user’s username, email, and password. Once you’re done, click on the Save button at the top right.
## Modify Permissions
By default, created users have the “Authenticated” role. Before you start using the Strapi plugin on your Medusa server, you must modify this role’s permissions to allow making changes to Medusa’s models in Strapi.
On your Strapi dashboard, go to Settings → Roles → Authenticated. Then, under the Permissions section, expand the accordion of each content model type and check the Select All checkbox.
![An example of modifying permissions on the Product content type](https://i.imgur.com/QgckXqS.png)
Once you’re done, click the Save button at the top right.
## Create Medusa Server
:::note
You can use the Strapi plugin on an existing Medusa server, however, existing data (such as existing products) will not be imported. Only newer data will be imported.
:::
To create your Medusa server, run the following command:
```bash
projectConfig: {
redis_url: REDIS_URL,
database_database: "./medusa-db.sql",
database_type: "sqlite",
store_cors: STORE_CORS,
admin_cors: ADMIN_CORS,
},
medusa new medusa-server --seed
```
Additionally, add Strapi to your list of plugins:
The `--seed` flag creates an SQLite database and seeds it with some demo data.
```json
{
"resolve": `medusa-plugin-strapi`,
"options": {
"strapi_medusa_user": "medusa_user",
"strapi_medusa_password": "medusaPassword1",
"strapi_url": "127.0.0.1",
"strapi_port": "1337"
### Configure your Server
Once the command is done executing, change to the newly created `medusa-server` directory. Then, in `medusa-config.js`, change the exported object at the end of the file to enable Redis:
```jsx
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
//...
}
}
//...
};
```
And finally, install the plugin using your package manager:
This uses the default Redis configurations. If you want to learn more about configuring Redis, [check out this documentation](../usage/configurations.md#redis).
:::tip
It is also recommended to use PostgreSQL for an optimal experience, however, it is not required. Learn how to [install](../tutorial/0-set-up-your-development-environment.mdx#postgres) and [configure](../usage/configurations.md#postgresql-configurations) it on your Medusa server.
:::
## Install the Strapi Plugin
In the directory of your Medusa server, run the following command to install the Strapi plugin:
```bash npm2yarn
npm install medusa-plugin-strapi
```
You've now successfully installed and configured your Medusa store engine. Seed it with data and start it up by running:
Then, add the following environment variables:
```bash
STRAPI_USER=<STRAPI_IDENTIFIER>
STRAPI_PASSWORD=<STRAPI_PASSWORD>
STRAPI_PROTOCOL=http # Optional
STRAPI_URL=<STRAPI_URL> # Optional
STRAPI_PORT=<STRAPI_PORT> # Optional
```
Where:
- `<STRAPI_IDENTIFIER>` is either the email address or username of the user you created in the previous step.
- `<STRAPI_PASSWORD>` is the password of the user you created in the previous step.
- `<STRAPI_PROTOCOL>` is the protocol of your Strapi server. If you’re using a local Strapi server, set this to `http`. The default value is `https`.
- `<STRAPI_URL>` is the URL of your Strapi server. By default, the URL is `localhost`.
- `<STRAPI_PORT>` is the port the Strapi server runs on. By default, the port is `1337`.
Finally, open `medusa-config.js` and add the following new item to the `plugins` array:
```jsx
const plugins = [
//...
{
resolve: `medusa-plugin-strapi`,
options: {
strapi_medusa_user: process.env.STRAPI_USER,
strapi_medusa_password: process.env.STRAPI_PASSWORD,
strapi_url: process.env.STRAPI_URL, //optional
strapi_port: process.env.STRAPI_PORT, //optional
strapi_protocol: process.env.STRAPI_PROTOCOL //optional
}
}
];
```
## Run Medusa Server
Make sure the Strapi server is still running. If not, you can run the following command to run the Strapi server in the directory of the Strapi project:
```bash npm2yarn
npm run seed && npm run start
npm run develop
```
We'll now turn to the Strapi side of things.
Then, in the directory of your Medusa server, run the following command to start the Medusa server:
### Setting up Strapi
Similar to how you installed Medusa, you can install Strapi using your favorite package manager. Use the `strapi-medusa-template` to create your project. The template is a custom Strapi implementation required for the two systems to work together.
You can use NPX:
```bash
npx create-strapi-app@3.6.8 strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git
```bash npm2yarn
npm run start
```
Alternatively, using Yarn:
Once you start your Medusa server, if you ran the `--seed` command when you created your Medusa server, you’ll see that `product.created` events have been triggered along with similar events. This will update Strapi with the products you seeded.
```bash
yarn global add create-strapi-app@3.6.8
create-strapi-app strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git
```
:::note
## Test Two-Way Sync
The plugin expects node version to be '>= 10.16.0 and <=14.x.x', otherwise it will throw an error.
This plugin ensures a two-way sync between the Medusa server and the Strapi server. So, if you update data on Strapi, it will be reflected on your Medusa server, and vice-versa.
:::
### Update Products on Strapi
After running the command, you have a full Strapi project configured to synchronize with Medusa. Upon the initial start of the Strapi server, all the required models will be created. They will correlate with models from Medusa to allow for two-way synchronization.
Try updating any products on Strapi by going to Content Manager → Products and choosing a product from the list. Then, make changes to the product and click Save. If you view the products on your server now, either using the [REST APIs](https://docs.medusajs.com/api/admin/#tag/Product/operation/GetProducts) or using [the Medusa Admin](../user-guide/products/index.mdx), you’ll see that the product has been updated.
:::caution
### Update Products on Medusa
The Strapi template starter uses SQLite as the default database. There is a known bug related to `knex.js` that comes from multiple write connections. Restarting the Strapi server should make the error disappear.
If you try to update products on Medusa either using the [REST APIs](https://docs.medusajs.com/api/admin/#tag/Product/operation/PostProductsProduct) or using [the Medusa Admin](../user-guide/products/manage.md), you’ll see that the product is also updated on Strapi.
:::
## What’s Next 🚀
**Synchronization**
The power of using Strapi with Medusa comes from two-way synchronization. Strapi allows you to enrich your products with extra fields and data, such that you can perfect the customer experience. But for the products to appear in Strapi, you are required to create them in Medusa. For the commerce logic in your presentational layer to function properly, you need the Medusa IDs of products and variants. This is used for operations like adding to cart and going through the checkout flow.
When products are created in Medusa, the two-way communication ensures that data is kept consistent between the two systems. Though only some fields are synchronized and those are:
**Product**: title, subtitle, description, handle
**Variants**: title
**Region**: name
:::note
Further down the road, the support for synchronizing more entities is expected to be introduced
:::
**Using Postgres in Medusa (optional)**
For Postgres to function, you need to create a local database. One way of doing this would be to use your terminal:
```json
createdb medusa-store
```
Depending on what system you are on and how your local Postgres is configured, the above command might fail. In that case, please investigate the correct way to create a local database on your pc.
Navigate to your newly created Medusa project (`<project name>/backend` if you used `npx`). In `medusa-config.js`, ensure that you have Redis and Postgres enabled. The project configurations at the bottom of the file should look similar to this:
```bash
projectConfig: {
redis_url: REDIS_URL,
database_url: DATABASE_URL,
database_type: "postgres",
store_cors: STORE_CORS,
admin_cors: ADMIN_CORS,
},
```
:::tip
The `DATABASE_URL` variable should use the Postgres database created in the previous step
:::
## Summary and next steps
You are now provided with the toolbox for creating amazing digital commerce experiences on top of a highly extendable CMS system and ecommerce platform.
To quickly get started, see our starters for:
- [GatsbyJS](https://github.com/medusajs/gatsby-starter-medusa) (much more feature-rich V2 coming soon)
- [NextJS](https://github.com/medusajs/nextjs-starter-medusa)
A big thanks to community member Pawan Sharma ([Deathwish98](https://github.com/Deathwish98)) for leading the implementation of this integration with Strapi. If you want to be part of the Medusa community, feel free to join us on our [Discord channel](https://discord.gg/F87eGuwkTp).
- Learn [how to deploy the Medusa server](../deployments/server/index.mdx).
- Learn [how to create your own plugin](../advanced/backend/plugins/create.md).

4
docs/content/advanced/backend/services/create-service.md
View File

@@ -43,9 +43,9 @@ async getProductCount() {
}
```
## Using a Service
## Use a Service
You can use core and custom services throughout your Medusa server.
In this section, you'll learn how to use services throughout your Medusa server. This includes both Medusa's services and your custom services.
:::note

78
docs/content/tutorial/0-set-up-your-development-environment.mdx
View File

@@ -6,51 +6,10 @@ import TabItem from '@theme/TabItem';
This document will guide you to set up your development environment to efficiently and properly use Medusa.
## Prerequisite Background Knowledge
### JavaScript
Medusa is built with JavaScript. If you’re not familiar with JavaScript, it is the language that runs in your browser to create dynamic web applications and has over the past decade gained a lot of traction as a backend language. If you wish to customize or extend Medusa, it is highly recommended that you learn how JavaScript works.
You can learn more about JavaScript with the [Basic JavaScript course from freeCodeCamp.](https://www.freecodecamp.org/learn/javascript-algorithms-and-data-structures/#basic-javascript)
### Express
Medusa uses [Express](https://expressjs.com), a Node.js web application framework, to create your ecommerce server. It facilitates creating REST APIs in Node.js. If you’re interested in customizing Medusa or understanding more about how it works, you should learn more about Express.
You can learn more about Node.js and Express with the [Free 8-hour-long Node.js + Express course from freeCodeCamp](https://www.freecodecamp.org/news/free-8-hour-node-express-course/).
### SQL
SQL is a programming language used to interact with relational databases and store data in your ecommerce server. To understand how different entities relate to each other in Medusa it is helpful to have a good understanding of SQL.
You can learn more about SQL and relational databases with the [SQL and Databases course from freeCodeCamp.](https://www.freecodecamp.org/news/sql-and-databases-full-course/)
### Command Line Interface (CLI)
To install and use Medusa, you’ll need to be familiar with CLI tools. If you’re not familiar with the command line, it is a text interface for your computer. It is used to run commands such as starting a program, performing a task, or interfacing with the files on your computer.
If you have never used the command line before you can check out [this tutorial](https://www.learnenough.com/command-line-tutorial) to get the basics in place.
### Additional Information
To get a further understanding of what powers Medusa you can lookup these concepts:
- [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer)
- [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection)
- [Idempotency Keys](https://brandur.org/idempotency-keys)
## Installations[](https://docs.medusajs.com/tutorial/set-up-your-development-environment#installations)
## Required Tools
To get your development environment ready you need to install the following tools:
- [Node.js](#nodejs)
- [Git](#git)
- [Postgresql](#postgresql)
- [Redis](#redis)
- [Medusa CLI](#medusa-cli)
- [Code Editor](#code-editor)
### Node.js
:::info
@@ -167,6 +126,20 @@ You can also check out [git’s guide](https://git-scm.com/download/mac) for mor
</TabItem>
</Tabs>
### Medusa CLI
The final installation required to get started with Medusa is the Medusa CLI. It is an NPM package you can install globally on your machine to get instant access to commands that help you manage and run your Medusa project.
You can install Medusa’s CLI with the following command:
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
## Optional Tools
These tools are not required to have to run a Medusa server, but we highly recommend that you have them installed.
### PostgreSQL
:::info
@@ -298,27 +271,6 @@ To install Redis without Homebrew you can check out [Redis’s guide on installi
</TabItem>
</Tabs>
### Medusa CLI
The final installation required to get started with Medusa is the Medusa CLI. It is an NPM package you can install globally on your machine to get instant access to commands that help you manage and run your Medusa project.
You can install Medusa’s CLI with the following command:
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
### Code editor
If you don't already have a code editor of choice, we recommend using [VSCode](https://code.visualstudio.com/) as it is a widely used IDE (Integrated Development Environment) by developers.
Here are some other options:
- [Atom](https://atom.io/)
- [Neovim](https://neovim.io/) (if you are super old school there's also plain [Vim](https://www.vim.org/))
It is not important which editor you use as long as you feel comfortable working with it.
## What’s Next 🚀
- Learn how to [configure your Medusa server](../usage/configurations.md).

11
docs/content/user-guide/orders/drafts.md
View File

@@ -1,11 +0,0 @@
---
sidebar_position: 5
---
# Manage Draft Orders
:::note
This guide is coming soon.
:::

127
docs/content/user-guide/orders/drafts.mdx Normal file
View File

@@ -0,0 +1,127 @@
---
sidebar_position: 5
---
import UiIcon from '@site/src/components/UiIcon';
# Manage Draft Orders
In this document, you’ll learn more about draft orders, how to create them, and more.
## Overview
Draft orders are orders created from the Medusa admin. Existing products or custom items can be added to the order as purchased items. You can also specify custom shipping amounts.
After a draft order is created and is marked as paid, an order will be created based on that draft order and it will appear as part of the Orders list.
---
## Create a Draft Order
To create a draft order:
1. Go to Orders → Drafts.
2. Click on “Create draft order” at the top right.
3. A new window then opens with six steps to go through to create the draft order:
1. In the first step, choose the region this draft order belongs to, then click the Next button.
2. In the second step, add items to the order. You must add at least one item. Once you’re done, click the Next button.
1. To add existing products:
1. Click on the Add Existing button.
2. Choose the products you want to add into the draft order by clicking the checkbox at the left of the product. You can choose more than one product.
3. Once done, click on the Add button.
2. To add a custom item:
1. Click on the Add Custom button.
2. Enter the title, price, and quantity of the custom item.
3. Click on the Add button.
3. To remove an item you added, click on the <UiIcon lightIcon="https://i.imgur.com/7hztVhj.png" darkIcon="https://i.imgur.com/1yp4PNt.png" alt="trash" /> icon at the right of the item.
4. To change the quantity of any item, use the <UiIcon lightIcon="https://i.imgur.com/1hL8NiW.png" darkIcon="https://i.imgur.com/8LtkPqW.png" alt="plus" /> and <UiIcon lightIcon="https://i.imgur.com/EGk9uYD.png" darkIcon="https://i.imgur.com/XvkBK8p.png" alt="minus" /> icons under the Quantity column.
5. Once you’re done, click the Next button.
3. In the third step, choose a shipping method then click the Next button.
1. If you want to change the default price of the shipping method, click on the “Set custom price” button and enter the price you want to use.
2. If you want to remove the custom price, you can click on the <UiIcon lightIcon="https://i.imgur.com/7hztVhj.png" darkIcon="https://i.imgur.com/1yp4PNt.png" alt="trash" /> icon.
4. In the fourth step, enter the customer’s details and shipping address.
1. If the customer already exists, you can choose it from the first input. You can search the list of customers by name or email. This fills out the fields under the General section as well.
2. If this is a new customer, in the first field, enter the email of the customer to add. Then, fill out the customer’s first name, last name, and phone number in the General section.
3. In the Shipping Address section, enter the customer’s address details such as the Address line, postal code, and more.
4. Once you’re done, click on the Next button.
5. In the fifth step, specify the billing address details.
1. If the billing address is the same as the shipping address, you can just check the “Use same as shipping” checkbox.
2. If the billing address is different than the shipping address, fill out the information under the General and Billing Address as instructed in the previous step.
3. Once done, click the Next button.
6. In the last step, confirm that all the information is correct.
1. If you want to add a discount, click on the Add Discount button and enter the discount code.
2. If you want to edit any of the draft order’s info, click on the Edit link next to any of the sections. This will take you back to the step associated with that section.
4. Once you’re done following all the six steps, click on the Submit button.
---
## Open Draft Order’s Details
To open a draft order’s details page:
1. Go to Orders → Drafts.
2. Select the draft order you want to view.
---
## Edit Draft Order Info
### Edit Shipping Address
To edit the shipping address of a draft order:
1. Open the draft order details page.
2. Scroll down to the customer section and click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon in that section.
3. Click on Edit Shipping Address in the dropdown.
4. This opens a new window to edit the shipping address’s info.
5. Once you’re done click on the Save button.
---
## Cancel Draft Order
:::warning
Canceling a draft order cannot be undone and the draft order will be removed from the list of draft orders.
:::
To cancel a draft order:
1. Open the draft order details page.
2. Click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon at the top right.
3. Click on Cancel Draft Order in the dropdown.
4. Confirm canceling the draft order by clicking the “Yes, remove” button in the pop-up.
---
## Mark Draft Order as Paid
:::caution
When you mark a draft order as paid, a new order is created and associated with this draft order. This can’t be undone, but the new order created can be canceled.
:::
To mark a draft order as paid:
1. Open the draft order details page.
2. Scroll down to the Payment section.
3. Click on the “Mark as paid” button.
You should see a new order in the Orders list now.
---
## Go to Associated Order
:::info
This is only available after a draft order is marked as paid.
:::
To go to the order associated with the draft order.
1. Open the draft order details page.
2. Click on the “Go to Order” button at the top right.

11
docs/content/user-guide/orders/fulfillments.md
View File

@@ -1,11 +0,0 @@
---
sidebar_position: 4
---
# Manage Fulfillments
:::note
This guide is coming soon.
:::

83
docs/content/user-guide/orders/fulfillments.mdx Normal file
View File

@@ -0,0 +1,83 @@
---
sidebar_position: 4
sidebar_label: Manage Fulfillments
---
import UiIcon from '@site/src/components/UiIcon';
# Manage Order's Fulfillments
In this tutorial, you’ll learn about order fulfillments and how to manage them, including how to create fulfillments and mark them as shipped.
## Overview
When a customer places an order, the fulfillment status of the order will be “not_shipped”. You can then create fulfillments and mark them as shipped once you ship the items.
You can create more than one fulfillment, with each fulfillment used for at least one item in the order.
If some items of the order are fulfilled, the order’s fulfillment status will be “partially_shipped”. Once all items are shipped, the order’s fulfillment status will be “shipped”.
---
## Create Fulfillment
:::info
You can only create a fulfillment in an order while there are items in the order that haven’t been shipped.
:::
To create a fulfillment for an order:
1. Open the order details page.
2. Scroll down to the Fulfillment section.
3. Click on the Create Fulfillment button.
4. In the window that opens:
- Choose the items you want to create the fulfillment for. These are the items you’ll ship together. You can also choose a specific quantity of an item to ship using the <UiIcon lightIcon="https://i.imgur.com/1hL8NiW.png" darkIcon="https://i.imgur.com/8LtkPqW.png" alt="plus" /> and <UiIcon lightIcon="https://i.imgur.com/EGk9uYD.png" darkIcon="https://i.imgur.com/XvkBK8p.png" alt="minus" /> icons under the Quantity column.
- Optionally enter any additional information you want to associate with the fulfillment under the Metadata section.
- If you don’t want the customer to receive an email that a fulfillment has been created, uncheck the “Send notifications” checkbox.
5. Once done, click on the Complete button.
You can check the fulfillment details in the Fulfillment and Timeline sections.
---
## Mark a Fulfillment Shipped
:::caution
Once a fulfillment is marked as shipped, it can’t be reverted. You must [create a fulfillment](#create-fulfillment) first before you can mark it as shipped.
:::
To mark a fulfillment as shipped in an order:
1. Open the order details page.
2. Scroll down to the Fulfillment section.
3. Find the fulfillment you want to mark as shipped, then click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon next to it.
4. Click on Mark Shipped in the dropdown.
5. In the new window that opens:
- Enter a tracking number for the shipment.
- If you have more than one tracking number, click on the “Add Additional Tracking Number” to add more numbers.
- If you don’t want the customer to receive an email that the fulfillment has been shipped, uncheck the “Send notifications” checkbox.
6. Once you’re done, click the Complete button.
Shipment details can be seen in the Timeline section.
---
## Cancel a Fulfillment
:::caution
If you cancel a fulfillment, it can’t be reverted. Only a fulfillment that hasn’t been marked as shipped can be canceled.
:::
To cancel a fulfillment in an order:
1. Open the order details page.
2. Scroll down to the Fulfillment section.
3. Find the fulfillment you want to cancel, then click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon next to it.
4. Click on Cancel Fulfillment in the dropdown.
5. Confirm canceling the fulfillment by clicking the “Yes, confirm” button in the pop-up.

13
docs/content/user-guide/orders/index.md
View File

@@ -1,5 +1,6 @@
---
sidebar_position: 1
sidebar_label: Overview
---
# Orders Overview
@@ -12,24 +13,30 @@ When customers buy one or more products, their order appears on the Orders page.
The Orders domain also contains draft orders. Draft orders are orders that you create from the Medusa admin. After you fill out the order and mark it paid, it’s transformed into an order that appears as part of the Orders list.
---
## View List of Orders
You can view the list of available orders in your ecommerce store by clicking on Orders from the sidebar menu.
In the list, you can see order details such as the ID, date, customer, fulfillment and payment status, total, and the country of the shipping address.
---
## View List of Draft Orders
You can view the list of draft orders on the Orders page by clicking on the grey Drafts headline next to the Orders headline.
In the list, you can see order details such as ID, the ID of the order the draft order belongs to, the date, the customer, and the status of the draft order.
---
## Learn More About Orders
- [Manage Order Details](./manage.mdx)
- [Manage Order’s Payment](./payments.md)
- [Manage Order’s Fulfillment](./fulfillments.md)
- [Manage Draft Orders](./drafts.md)
- [Manage Order Returns](./returns.md)
- [Manage Order’s Fulfillment](./fulfillments.mdx)
- [Manage Draft Orders](./drafts.mdx)
- [Manage Order Returns](./returns.mdx)
- [Manage Order Claims](./claims.md)
- [Manage Order Exchanges and Swaps](./swaps.md)

13
docs/content/user-guide/orders/manage.mdx
View File

@@ -1,5 +1,6 @@
---
sidebar_position: 2
sidebar_label: Manage Details
---
import UiIcon from '@site/src/components/UiIcon';
@@ -17,6 +18,8 @@ To open an order’s details:
This opens the order’s details page.
---
## Sections of the Order Details Page
### Order Summary
@@ -43,6 +46,8 @@ This section includes details related to the shipping method and fulfillment and
This section includes the customer’s details, including their shipping address.
---
## Edit the Shipping Address
To edit the shipping address used for an order:
@@ -54,6 +59,8 @@ To edit the shipping address used for an order:
5. This opens a new window to edit the shipping address.
6. Once you’re done, click on the Save button.
---
## Edit Email Address
To edit the email address associated with an order:
@@ -65,6 +72,8 @@ To edit the email address associated with an order:
5. This opens a new window to edit the email address.
6. Once you’re done, click on the Save button.
---
## Add a Note
To add a note to an order:
@@ -75,6 +84,8 @@ To add a note to an order:
The note will be added and can be seen in the timeline.
---
## Delete a Note
:::caution
@@ -91,6 +102,8 @@ To delete a note in an order:
4. Click on Delete from the dropdown.
5. Confirm deleting the note by clicking the “Yes, delete” button in the pop-up.
---
## Cancel an Order
:::warning

48
docs/content/user-guide/orders/payments.md
View File

@@ -1,11 +1,53 @@
---
sidebar_position: 3
sidebar_label: Manage Payments
---
# Manage Payments
# Manage Order's Payments
:::note
In this document, you’ll learn how to manage an order’s payment, including capturing and refunding the payment.
This guide is coming soon.
## Overview
When a customer places an order, using the payment provider they choose during checkout, they authorize the payment.
The payment isn’t automatically captured. You must capture it manually from the Medusa admin.
---
## Capture Payment
:::info
Payment can only be captured once.
:::
To capture an order’s payment:
1. Open the order details page.
2. Scroll to the Payment section.
3. Click on the Capture Payment button.
---
## Refund Payment
:::caution
Refunding payments can’t be undone. Payment can only be refunded after it has been captured.
:::
To refund an order’s payment:
1. Open the order details page.
2. Scroll to the Payment section.
3. Click on the Refund button.
4. In the new window that opens:
- Enter the Refund amount. It must be less than the Total Paid amount specified in the Payment section.
- Choose a reason for the refund and optionally provide a note.
- If you don’t want the customer to receive an email that the refund has been made, uncheck the “Send notifications” checkbox.
5. Once you’re done, click on the Complete button.
You can check refund details in the Payment, Summary, and Timeline sections.

11
docs/content/user-guide/orders/returns.md
View File

@@ -1,11 +0,0 @@
---
sidebar_position: 6
---
# Manage Returns
:::note
This guide is coming soon.
:::

83
docs/content/user-guide/orders/returns.mdx Normal file
View File

@@ -0,0 +1,83 @@
---
sidebar_position: 6
sidebar_label: Manage Returns
---
import UiIcon from '@site/src/components/UiIcon';
# Manage Order’s Returns
In this document, you’ll learn more about order returns, how to request a return, and more.
## Overview
Part of the order management system that Medusa provides is automating and managing order returns.
There are two ways of returns for an order to be requested:
1. The customer requests a return for an order through the storefront, which the store operator can view on the admin.
2. The store operator requests to receive a return from the customer. The customer can be informed about this through an email.
After a return is requested, the store operator can choose to either cancel the return or mark it as received. When a return is marked as received, a refund is issued to the customer.
---
## Find Return Requests of an Order
To find return requests of an order:
1. Open the order details page.
2. On the Timeline section, you’ll find any returns requested, whether by store operators or by customers.
---
## Request a Return for an Order
To request a return for an order:
1. Open the order details page.
2. In the Timeline section, click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon at the top right.
3. Click on Request Return in the dropdown.
4. In the new window that opens:
- Choose the items in the order that you want to request the return.
- For each item that you choose, click on the Select Reason below that item.
- Choose a Return Reason, optionally enter a Note, then click the Add button.
- Select a shipping method you want to use for this return.
- If you want to change the default price of the shipping method, click on the “Add custom price” button and enter the price you want to use.
- If you want to remove the custom price, you can click on the <UiIcon lightIcon="https://i.imgur.com/7hztVhj.png" darkIcon="https://i.imgur.com/1yp4PNt.png" alt="trash" /> icon.
- If you don’t want the customer to receive an email that a return has been requested, uncheck the “Send notifications” checkbox.
5. Once done, click on the Submit button.
---
## Receive Return
:::caution
Once the return is marked as received, a refund will be issued to the customer. A return can only be marked as “received” if the payment of the order or the items chosen in the return is captured.
:::
To mark a return as received:
1. Open the order details page.
2. In the Timeline section, find the return requested.
3. Click on the Receive Return button.
4. Check or uncheck the items that have been received.
5. Click the Complete button.
---
## Cancel a Return
:::danger
If a return is canceled it can’t be undone. A return can only be canceled if it hasn’t been marked as received.
:::
To cancel a return:
1. Open the order details page.
2. In the Timeline section, find the return requested and click on the <UiIcon lightIcon="https://i.imgur.com/1ordBC6.png" darkIcon="https://i.imgur.com/dSwWYBH.png" alt="three dots" /> icon.
3. Click on “Cancel return” in the dropdown.