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

docs: add documentation for remaining plugins (#4994)

Browse Source 
* docs: add documentation for remaining plugins

* fix eslint errors
This commit is contained in:
Shahed Nasser
2023-09-08 19:18:48 +03:00
committed by GitHub
parent 4b0e3fb2a7
commit 1a1fc6c968
23 changed files with 821 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/medusa-fulfillment-manual/README.md
View File

@@ -45,4 +45,6 @@ A minimal fulfillment provider that allows merchants to handle fulfillments manu
2\. Enable the fulfillment provider in the admin. You can refer to [this User Guide](https://docs.medusajs.com/user-guide/regions/providers) to learn how to do that. Alternatively, you can use the [Admin APIs](https://docs.medusajs.com/api/admin#tag/Region/operation/PostRegionsRegion).
3\. Add shipping options for the fulfillment provider. You can do that using either the [Medusa Admin](../../user-guide/regions/shipping-options.mdx) or the [Admin REST APIs](../../modules/regions-and-currencies/admin/manage-regions.mdx#add-a-shipping-option-to-a-region).
3\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use the manual fulfillment provider during checkout.

20
packages/medusa-plugin-brightpearl/README.md
View File

@@ -37,12 +37,15 @@ Manage and streamline your business processes using Brightpearl.
BRIGHTPEARL_WAREHOUSE=<YOUR_WAREHOUSE>
BRIGHTPEARL_DEFAULT_STATUS_ID=<YOUR_DEFAULT_STATUS_ID>
BRIGHTPEARL_SWAP_STATUS_ID=<YOUR_SWAP_STATUS_ID>
BRIGHTPEARL_CLAIM_STATUS_ID=<YOUR_CLAIM_STATUS_ID>
BRIGHTPEARL_PAYMENT_METHOD_CODE=<YOUR_PAYMENT_METHOD_CODE>
BRIGHTPEARL_SALES_ACCOUNT_CODE=<YOUR_SALES_ACCOUNT_CODE>
BRIGHTPEARL_SHIPPING_ACCOUNT_CODE=<YOUR_SHIPPING_ACCOUNT_CODE>
BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE=<YOUR_DISCOUNT_ACCOUNT_CODE>
BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE=<YOUR_GIFT_CARD_ACCOUNT_CODE>
BRIGHTPEARL_INVENTORY_SYNC_CRON=<YOUR_INVENTORY_SYNC_CRON>
BRIGHTPEARL_COST_PRICE_LIST=<YOUR_COST_PRICE_LIST>
BRIGHTPEARL_BASE_CURRENCY=<YOUR_BASE_CURRENCY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
@@ -58,14 +61,17 @@ Manage and streamline your business processes using Brightpearl.
backend_url: process.env.BRIGHTPEARL_BACKEND_URL, // required, the url where the Medusa server is running, needed for webhooks
event_owner: process.env.BRIGHTPEARL_EVENT_OWNER, // required, the id of the user who will own goods out events]
warehouse: process.env.BRIGHTPEARL_WAREHOUSE, // required, the warehouse id to allocate orders from
default_status_id: process.env.BRIGHTPEARL_DEFAULT_STATUS_ID, // (optional: defaults to 1), the status id to assign new orders with
swap_status_id: process.env.BRIGHTPEARL_SWAP_STATUS_ID, // (optional: defaults to 1), the status id to assign new swaps]
payment_method_code: process.env.BRIGHTPEARL_PAYMENT_METHOD_CODE, // (optional: defaults to 1220), the method code to register payments with
sales_account_code: process.env.BRIGHTPEARL_SALES_ACCOUNT_CODE, // (optional: defaults to 4000), nominal code to assign line items to
shipping_account_code: process.env.BRIGHTPEARL_SHIPPING_ACCOUNT_CODE, // (optional: defaults to 4040), nominal code to assign shipping line to
default_status_id: process.env.BRIGHTPEARL_DEFAULT_STATUS_ID, // (default: `3`), the status id to assign new orders with
swap_status_id: process.env.BRIGHTPEARL_SWAP_STATUS_ID, // (default: `3`), the status id to assign new swaps
claim_status_id: process.env.BRIGHTPEARL_CLAIM_STATUS_ID, // (default: `3`), the status id to assign new claims
payment_method_code: process.env.BRIGHTPEARL_PAYMENT_METHOD_CODE, // (default: `1220`), the method code to register payments with
sales_account_code: process.env.BRIGHTPEARL_SALES_ACCOUNT_CODE, // (defaults: `4000`), nominal code to assign line items to
shipping_account_code: process.env.BRIGHTPEARL_SHIPPING_ACCOUNT_CODE, // (default: `4040`), nominal code to assign shipping line to
discount_account_code: process.env.BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE, // optional, nominal code to use for Discount-type refunds
gift_card_account_code: process.env.BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE, // (optional: default to 4000), nominal code to use for gift card products and redeems
inventory_sync_cron: process.env.BRIGHTPEARL_INVENTORY_SYNC_CRON, // (default: false), cron pattern for inventory sync, if left out the job will not be created
gift_card_account_code: process.env.BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE, // (default: `4000`), nominal code to use for gift card products and redeems
inventory_sync_cron: process.env.BRIGHTPEARL_INVENTORY_SYNC_CRON, // optional, cron pattern for inventory sync, if left out the job will not be created
cost_price_list: process.env.BRIGHTPEARL_COST_PRICE_LIST, // (default: `1`) the ID of the price list to assign to created claims
base_currency: process.env.BRIGHTPEARL_BASE_CURRENCY, // (default: `EUR`) the ISO 3 character code of the currency to assign to created claims.
},
},
]

8
packages/medusa-plugin-wishlist/README.md
View File

@@ -37,10 +37,4 @@ Add wishlist capabilities to your commerce application.
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Retrieve a customer's wishlist using the endpoint `/wishlist/:token`, where `:token` is the customer's token.
Learn about testing the plugin in [the documentation](https://docs.medusajs.com/plugins/other/wishlist)

2
www/docs/content/plugins/analytics/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Analytics Plugins
If you can't find your analytics provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Analytics&categories=Analytics).
<DocCardList />

2
www/docs/content/plugins/analytics/segment.md
View File

@@ -129,7 +129,7 @@ const plugins = [
Run your backend with the following command:
```bash npm2yarn
```bash
npx medusa develop
```

2
www/docs/content/plugins/cms/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# CMS Plugins
If you can't find your CMS provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=CMS&categories=CMS).
<DocCardList />

154
www/docs/content/plugins/erp/brightpearl.md Normal file
View File

@@ -0,0 +1,154 @@
---
addHowToData: true
---
# Brightpearl
This document will guide you through installing the Brightpearl plugin on your Medusa backend.
## Overview
[Brightpearl](https://www.brightpearl.com/) is a Retail Operations Platform. It can be integrated to a business's different sales channels to provide features related to inventory management, automation, analytics and reporting, and more.
Medusa provides an official Brightpearl plugin with the following features:
- Send and sync orders with Brightpearl.
- Listen for inventory and stock movements in Brightpearl.
- Handle order returns through Brightpearl.
---
## Prerequisites
### Medusa Backend
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../create-medusa-app.mdx) to get started in minutes.
### Brightpearl Account
Using this plugin requires having a [Webshipper account](https://www.brightpearl.com/) with access to development keys and resources.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-plugin-brightpearl
```
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: `medusa-plugin-brightpearl`,
options: {
account: process.env.BRIGHTPEARL_ACCOUNT,
backend_url: process.env.BRIGHTPEARL_BACKEND_URL,
channel_id: process.env.BRIGHTPEARL_CHANNEL_ID,
event_owner: process.env.BRIGHTPEARL_EVENT_OWNER,
warehouse: process.env.BRIGHTPEARL_WAREHOUSE,
// optional
default_status_id:
process.env.BRIGHTPEARL_DEFAULT_STATUS_ID,
swap_status_id:
process.env.BRIGHTPEARL_SWAP_STATUS_ID,
claim_status_id:
process.env.BRIGHTPEARL_CLAIM_STATUS_ID,
payment_method_code:
process.env.BRIGHTPEARL_PAYMENT_METHOD_CODE,
sales_account_code:
process.env.BRIGHTPEARL_SALES_ACCOUNT_CODE,
shipping_account_code:
process.env.BRIGHTPEARL_SHIPPING_ACCOUNT_CODE,
discount_account_code:
process.env.BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE,
gift_card_account_code:
process.env.BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE,
inventory_sync_cron:
process.env.BRIGHTPEARL_INVENTORY_SYNC_CRON,
cost_price_list:
process.env.BRIGHTPEARL_COST_PRICE_LIST,
base_currency:
process.env.BRIGHTPEARL_BASE_CURRENCY,
},
},
]
```
The plugin accepts the following options:
- `account`: (required) is a string indicating your account ID. You can refer to [Brightpearl's documentation](https://help.brightpearl.com/s/article/360028541892#:~:text=Your%20account%20ID%20can%20be,your%20email%20address%20and%20password.) on how to retrieve it.
- `channel_id`: (required) is a string indicating the ID of the channel to map sales and credits to.
- `backend_url`: (required) is a string indicating the URL of your Medusa backend. This is useful for webhooks.
- `event_owner`: (required) is a string indicating the ID of the contact used when sending the [Goods-Out Note Event](https://api-docs.brightpearl.com/warehouse/goods-out-note%20event/post.html).
- `warehouse`: (required) is a string indicating the ID of the warehouse to allocate order items' inventory from.
- `default_status_id`: (default: `3`) is a string indicating the ID of the status to assign new orders. This value will also be used on swaps or claims if their respective options, `swap_status_id` and `claim_status_id`, are not provided.
- `swap_status_id`: (default: `3`) is a string indicating the ID of the status to assign new swaps. If not provided and `default_status_id` is provided, the value of `default_status_id` will be used.
- `claim_status_id`: (default: `3`) is a string indicating the ID of the status to assign new claims. If not provided and `default_status_id` is provided, the value of `default_status_id` will be used.
- `payment_method_code`: (default: `1220`) is a string indicating the payment method code to register payments with.
- `sales_account_code`: (default: `4000`) is a string indicating the nominal code to assign line items to.
- `shipping_account_code`: (default: `4040`) is a string indicating the nominal code to assign shipping lines to.
- `discount_account_code`: (optional) is a string indicating the nominal code to use for discount-type refunds.
- `gift_card_account_code`: (default: `4000`) is a string indicating the nominal code to use for gift card products and redeems.
- `inventory_sync_cron`: (optional) is a string indicating a cron pattern that should be used to create a scheduled job for syncing inventory. If not provided, the scheduled job will not be created.
- `cost_price_list`: (default: `1`) is a string indicating the ID of the price list to assign to created claims.
- `base_currency`: (default: `EUR`) is a string indicating the ISO 3 character code of the currency to assign to created claims.
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
BRIGHTPEARL_ACCOUNT=<YOUR_ACCOUNT>
BRIGHTPEARL_CHANNEL_ID=<YOUR_CHANNEL_ID>
BRIGHTPEARL_BACKEND_URL=<YOUR_BACKEND_URL>
BRIGHTPEARL_EVENT_OWNER=<YOUR_EVENT_OWNER>
BRIGHTPEARL_WAREHOUSE=<YOUR_WAREHOUSE>
BRIGHTPEARL_DEFAULT_STATUS_ID=<YOUR_DEFAULT_STATUS_ID>
BRIGHTPEARL_SWAP_STATUS_ID=<YOUR_SWAP_STATUS_ID>
BRIGHTPEARL_CLAIM_STATUS_ID=<YOUR_CLAIM_STATUS_ID>
BRIGHTPEARL_PAYMENT_METHOD_CODE=<YOUR_PAYMENT_METHOD_CODE>
BRIGHTPEARL_SALES_ACCOUNT_CODE=<YOUR_SALES_ACCOUNT_CODE>
BRIGHTPEARL_SHIPPING_ACCOUNT_CODE=<YOUR_SHIPPING_ACCOUNT_CODE>
BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE=<YOUR_DISCOUNT_ACCOUNT_CODE>
BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE=<YOUR_GIFT_CARD_ACCOUNT_CODE>
BRIGHTPEARL_INVENTORY_SYNC_CRON=<YOUR_INVENTORY_SYNC_CRON>
BRIGHTPEARL_COST_PRICE_LIST=<YOUR_COST_PRICE_LIST>
BRIGHTPEARL_BASE_CURRENCY=<YOUR_BASE_CURRENCY>
```
---
## Test the Plugin
To test the plugin, run the following command in the directory of the Medusa backend to start the backend:
```bash
npx medusa develop
```
Then, place an order either using a [storefront](../../starters/nextjs-medusa-starter.mdx) or the [Store REST APIs](https://docs.medusajs.com/api/store). The order should appear on Brightpearl.
---
## How the Plugin Works
### OAuth
The plugin registers an OAuth app in Medusa allowing installation at `<BACKEND_URL>/a/settings/apps`, where `<BACKEND_URL>` is the URL of your Medusa backend.
The OAuth tokens are refreshed every hour to prevent unauthorized requests.
### Orders and Fulfillments
When an order is created in the Medusa backend, it'll automatically be sent to Brightpearl and allocated there. Once allocated, it is up to Brightpearl to figure out how the order is to be fulfilled. The plugin listens for Goods-Out notes and tries to map each of these to a Medusa order. If the matching succeeds, the Medusa backend will send the order to the fulfillment provider associated with the shipping method selected by the Customer.
### Order Returns
When line items in an order are returned, the plugin will generate a sales credit in Brightpearl.
### Products
The plugin doesn't automatically create products in Medusa, but listens for inventory changes in Brightpearl. Then, the plugin updates each product variant to reflect the inventory quantity listed in Brightpearl, thereby ensuring that the inventory levels in Medusa are always in sync with Brightpearl.

5
www/docs/content/plugins/erp/index.mdx Normal file
View File

@@ -0,0 +1,5 @@
import DocCardList from '@theme/DocCardList';
# ERP Plugins
<DocCardList />

2
www/docs/content/plugins/file-service/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# File Service Plugins
If you can't find your file service or storage provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Storage&categories=Storage). You can also [create your own file service](../../development/file-service/create-file-service.md).
<DocCardList />

6
www/docs/content/plugins/file-service/local.md
View File

@@ -23,11 +23,11 @@ For production, it's recommended to use a file service plugin that hosts your im
## Prerequisites
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes.
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../create-medusa-app.mdx) to get started in minutes.
---
## Plugin Installation
## Install Plugin
In the directory of your Medusa backend, run the following command to install the local file service plugin:
@@ -64,7 +64,7 @@ You can pass the plugin the following options:
---
## Test it Out
## Test the Plugin
Run your Medusa backend alongside the [Medusa Admin](../../admin/quickstart.mdx) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored locally in your backend.

7
www/docs/content/plugins/fulfillment/index.mdx Normal file
View File

@@ -0,0 +1,7 @@
import DocCardList from '@theme/DocCardList';
# Fulfillment Plugins
If you can't find your fulfillment provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Shipping&categories=Shipping). You can also [create your own fulfillment provider](../../modules/carts-and-checkout/backend/add-fulfillment-provider.md).
<DocCardList />

56
www/docs/content/plugins/fulfillment/manual.md Normal file
View File

@@ -0,0 +1,56 @@
---
addHowToData: true
---
# Manual Fulfillment Plugin
This document will guide you through installing the manual fulfillment plugin on your Medusa backend.
## Overview
With Medusa, you can create or integrate fulfillment providers as plugins. Medusa also provides the manual fulfillment plugin as a minimal plugin that allows merchants to handle fulfillments manually. This plugin is installed by default in your Medusa backend.
The manual fulfillment plugin is similar to a cash-on-delivery (COD) fulfillment plugin. A merchant can provide shipping options to the customer on checkout, and create fulfillments and shipments for orders. This data is stored in Medusa, but no actual fulfillment actions are performed, such as communicating with a third-party service. The merchant is assumed to handle that themselves.
---
## Prerequisites
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../create-medusa-app.mdx) to get started in minutes.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-fulfillment-manual
```
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: `medusa-fulfillment-manual`,
},
]
```
---
## Test the Plugin
To test the plugin, run the following command in the directory of the Medusa backend to start the backend:
```bash
npx medusa develop
```
Then, you must enable the Manual Fulfillment Provider in at least one region to use it. You can do that using either the [Medusa Admin](../../user-guide/regions/providers.mdx), which is available at `http://localhost:7001` after you run the above command, or the [Admin REST APIs](../../modules/regions-and-currencies/admin/manage-regions.mdx).
After enabling the provider, you must add shipping options for that provider. You can also do that using either the [Medusa Admin](../../user-guide/regions/shipping-options.mdx) or the [Admin REST APIs](../../modules/regions-and-currencies/admin/manage-regions.mdx#add-a-shipping-option-to-a-region).
Finally, try to place an order using either a [storefront](../../starters/nextjs-medusa-starter.mdx) or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use the shipping options you created for the fullfilment provider.

150
www/docs/content/plugins/fulfillment/webshipper.md Normal file
View File

@@ -0,0 +1,150 @@
---
addHowToData: true
---
# Webshipper
This document will guide you through installing the Webshipper fulfillment plugin on your Medusa backend.
## Overview
[Webshipper](https://webshipper.com/) is a service that allows merchants to connect to multiple carriers through a single Webshipper account. Developers can then integrate webshipper with ecommerce store like Medusa to handle shipping and fulfillment.
Medusa provides an official plugin that allows you to integrate Webshipper in your store. When integrated, you can provide customers with Webshippers' shipping options on checkout, and process and handle fulfillment and shipments of orders through Webshipper.
---
## Prerequisites
### Medusa Backend
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../create-medusa-app.mdx) to get started in minutes.
### Webshipper Account
Using this plugin requires having a [Webshipper account](https://webshipper.com/) with access to development keys and resources.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-fulfillment-webshipper
```
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: `install medusa-fulfillment-webshipper`,
options: {
account: process.env.WEBSHIPPER_ACCOUNT,
api_token: process.env.WEBSHIPPER_API_TOKEN,
order_channel_id:
process.env.WEBSHIPPER_ORDER_CHANNEL_ID,
webhook_secret: process.env.WEBSHIPPER_WEBHOOK_SECRET,
return_address: {
// Webshipper Shipping Address fields
},
// optional
coo_countries: process.env.WEBSHIPPER_COO_COUNTRIES,
delete_on_cancel:
process.env.WEBSHIPPER_DELETE_ON_CANCEL !== "false",
document_size: process.env.WEBSHIPPER_DOCUMENT_SIZE,
return_portal: {
id: process.env.WEBSHIPPER_RETURN_PORTAL_ID,
cause_id:
process.env.WEBSHIPPER_RETURN_PORTAL_CAUSE_ID,
refund_method_id:
process.env.WEBSHIPPER_RETURN_REFUND_METHOD_ID,
},
},
},
]
```
The plugin accepts the following options:
- `account`: (required) is a string indicating your account name. If you're unsure of it, it's in the first part of the URL you use when accessing the Webshipper UI which has the format `https://<account name>.webshipper.io`.
- `api_token`: (required) is a string indicating your API token. You can create it from the Webshipper UI under Settings > Access and tokens.
- `order_channel_id`: (required) is a string indicating the ID of the order channel to retrieve shipping rates from.
- `webhook_secret`: (required) is a string indicating the secret used to sign the HMAC in webhooks.
- `return_address`: (required for returns) is an object that indicates the return address that should be used when fulfilling an order return. Refer to [Webshipper's API reference](https://docs.webshipper.io/#shipping_addresses) for accepted properties in this object.
- `coo_countries`: (default: `all`) is a list of ISO 3 character country codes used when attaching a Certificate of Origin. To support all countries you can set the value to `all`.
- `delete_on_cancel`: (default: `false`) is a boolean value that determines whether Webshipper orders should be deleted when its associated Medusa fulfillment is canceled.
- `document_size`: (default: `A4`) is a string indicating the size used when retrieving documents, such as fulfillment documents. The accepted values, based on Webshipoer's documentation, are `100X150`, `100X192`, or `A4`.
- `return_portal`: is an optional object that includes options related to order returns. It includes the following properties:
- `id`: is a string indicating the ID of the return portal to use when fulfilling an order return.
- `cause_id`: is a string indicating the ID of the return cause to use when fulfilling an order return.
- `refund_method_id` is a string indicating the ID of the refund method to use when fulfilling an order return.
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
WEBSHIPPER_ACCOUNT=<YOUR_WEBSHIPPER_ACCOUNT>
WEBSHIPPER_API_TOKEN=<YOUR_WEBSHIPPER_API_TOKEN>
WEBSHIPPER_ORDER_CHANNEL_ID=<YOUR_WEBSHIPPER_ORDER_CHANNEL_ID>
WEBSHIPPER_WEBHOOK_SECRET=<YOUR_WEBSHIPPER_WEBHOOK_SECRET>
WEBSHIPPER_COO_COUNTRIES=<YOUR_WEBSHIPPER_COO_COUNTRIES>
WEBSHIPPER_DELETE_ON_CANCEL=<YOUR_WEBSHIPPER_DELETE_ON_CANCEL>
WEBSHIPPER_DOCUMENT_SIZE=<YOUR_WEBSHIPPER_DOCUMENT_SIZE>
# Return Portal Variables
WEBSHIPPER_RETURN_PORTAL_ID=<YOUR_WEBSHIPPER_RETURN_PORTAL_ID>
WEBSHIPPER_RETURN_PORTAL_CAUSE_ID=<YOUR_WEBSHIPPER_RETURN_PORTAL_CAUSE_ID>
WEBSHIPPER_RETURN_REFUND_METHOD_ID=<YOUR_WEBSHIPPER_RETURN_REFUND_METHOD_ID>
```
---
## Test the Plugin
To test the plugin, run the following command in the directory of the Medusa backend to start the backend:
```bash
npx medusa develop
```
Then, you must enable the Webshipper Fulfillment Provider in at least one region to use it. You can do that using either the [Medusa Admin](../../user-guide/regions/providers.mdx), which is available at `http://localhost:7001` after you run the above command, or the [Admin REST APIs](../../modules/regions-and-currencies/admin/manage-regions.mdx).
After enabling the provider, you must add shipping options for that provider. You can also do that using either the [Medusa Admin](../../user-guide/regions/shipping-options.mdx) or the [Admin REST APIs](../../modules/regions-and-currencies/admin/manage-regions.mdx#add-a-shipping-option-to-a-region).
Finally, try to place an order using either a [storefront](../../starters/nextjs-medusa-starter.mdx) or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use the shipping options you created for the fullfilment provider.
---
## Personal Customs Numbers
In countries like South Korea, a personal customs number is required to clear customs. The Webshipper plugin is able pass this information to Webshipper given that the number is stored in `order.shipping_address.metadata.personal_customs_no`.
### Adding Field in Checkout Flow
To allow the customer to pass their personal customs number along with the order, you should dynamically show an input field to the customer when they are shopping from a region that requires a personal customs number. Then, make sure that the `metadata` field includes the personal customs number when updating the cart's shipping address.
```ts
const onUpdateAddress = async () => {
const address = {
first_name: "John",
last_name: "Johnson",
// ...,
metadata: {
// TODO the value should be replaced with the
// value entered by the customer
personal_customs_no: "my-customs-number",
},
}
await medusaClient.carts
.update(cartId, {
shipping_address: address,
})
.then(() => {
console.log(
"Webshipper will pass along the customs number"
)
})
}
```

2
www/docs/content/plugins/notifications/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Notifications Plugins
If you can't find your notification provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Notification&categories=Notification). You can also [create your own notification service](../../development/notification/create-notification-provider.md).
<DocCardList />

95
www/docs/content/plugins/other/discount-generator.md Normal file
View File

@@ -0,0 +1,95 @@
---
addHowToData: true
---
# Discount Generator
In this document, you’ll learn how to install the Discount Generator plugin on your Medusa backend.
## Overview
In Medusa, merchants can create dynamic discounts that act as a template for other discounts. With dynamic discounts, merchants don't have to repeat certain conditions every time they want to create a new discount.
The discount generator plugin allows merchants and developers to generate new discounts from a dynamic discount. This can be done either by envoking the `/discount-code` endpoint or using the `DiscountGeneratorService`.
---
## Prerequisites
Before you follow this guide, you must have a Medusa backend installed. If not, you can follow the [quickstart guide](../../create-medusa-app.mdx) to learn how to do it.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-plugin-discount-generator
```
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: `medusa-plugin-discount-generator`,
},
]
```
---
## Test the Plugin
### Using the Endpoint
The plugin registers a `POST` endpoint `/discount-code`. The endpoint accepts in the request body the parameter `discount_code` which is a string indicating the code of the dynamic discount to generate a new discount from. The endpoint then creates the new discount from the dynamic discount and returns it in the response.
So, to test out the endpoint, run the following command in the root of your project to start the Medusa backend:
```bash
npx medusa develop
```
Then, create a dynamic discount. You can do that either using the [Medusa admin](../../user-guide/discounts/create.mdx) which is available (if installed) at `http://localhost:7001` after starting the backend, or using the [Admin REST APIs](../../modules/discounts/admin/manage-discounts.mdx).
After that, send a `POST` request to the `/discount-code` endpoint, passing the `discount_code` parameter in the request body with the value being the code of the dynamic discount you just created. A new discount will be created with the same attributes as the dynamic discount code and returned in the response.
### Using the DiscountGeneratorService
After installing the plugin, the `DiscountGeneratorService` is registered in the [dependency container](../../development/fundamentals/dependency-injection.md). So, you can resolve and use it in custom services, endpoints, or other resources.
The `DiscountGeneratorService` has one method `generateDiscount`. This method requires passing the code of a dynamic discount as a parameter. It then creates a new discount having the same attributes as the dynamic discount, but with a different, random code.
Here's an example of using the service in an endpoint:
```ts title=src/api/index.ts
import { Request, Response, Router } from "express"
import bodyParser from "body-parser"
export default (rootDirectory: string): Router | Router[] => {
const router = Router()
router.use(
"/generate-discount-code",
bodyParser.json(),
async (req: Request, res: Response) => {
// skipping validation for simplicity
const { dynamicCode } = req.body
const discountGenerator = req.scope.resolve(
"discountGeneratorService"
)
const code = await discountGenerator.generateDiscount(
dynamicCode
)
res.json({
code,
})
})
return router
}
```

2
www/docs/content/plugins/other/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Other Plugins
Check the [Community Plugins Library](https://medusajs.com/plugins/?filters=Other&categories=Other&categories=Source) for more plugins.
<DocCardList />

96
www/docs/content/plugins/other/wishlist.md Normal file
View File

@@ -0,0 +1,96 @@
---
addHowToData: true
---
# Wishlist Plugin
In this document, you’ll learn how to install the Wishlist plugin on your Medusa backend.
## Overview
A wishlist allows customers to save items they like so they can browse and purchase them later. Medusa's wishlist plugin provides the following features:
- Allow a customer to manage their wishlist, including adding or deleting items.
- Allow a customer to share their wishlist with others using a token.
:::tip
Items in the wishlist are added as line items. This allows you to implement functionalities like moving an item from the wishlist to the cart, although this is not implemented by the plugin.
:::
---
## Prerequisites
Before you follow this guide, you must have a Medusa backend installed. If not, you can follow the [quickstart guide](../../create-medusa-app.mdx) to learn how to do it.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-plugin-wishlist
```
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: `medusa-plugin-wishlist`,
},
]
```
---
## Test the Plugin
Before testing the plugin, run the following command in the directory of the Medusa backend to start the backend:
```bash
npx medusa develop
```
The plugin exposes four endpoints.
### Add Item to Wishlist Endpoint
The `POST` endpoint at `/store/customer/<CUSTOMER_ID>/wishlist` allows customers to add items to their existing or new wishlist, where `<CUSTOMER_ID>` is the ID of the customer. It accepts the following body parameters:
- `variant_id`: a string indicating the ID of the product variant to add to the wishlist.
- `quantity`: (optional) a number indicating the quantity of the product variant.
- `metadata`: (optional) any metadata to attach to the wishlist item.
The request returns the full customer object. The wishlist is available at `customer.metadata.wishlist`, where its value is an array of items.
### Delete Item from Wishlist Endpoint
The `DELETE` endpoint at `/store/customer/<CUSTOMER_ID>/wishlist` allows customers to delete items from their wishlist, where `<CUSTOMER_ID>` is the ID of the customer.
The endpoint accepts one request body parameter `index`, which indicates the index of the item in the `customer.metadata.wishlist` array.
The request returns the full customer object. The wishlist is available at `customer.metadata.wishlist`, where its value is an array of items.
#### Generate Share Token Endpoint
The `POST` endpoint at `/store/customer/<CUSTOMER_ID>/wishlist/share-token` allows customers to retrieve a token that can be used to access the wishlist, where `<CUSTOMER_ID>` is the ID of the customer.
The endpoint doesn't accept any request body parameters.
The request returns an object in the response having the property `share_token`, being the token that can be used to access the wishlist.
#### Access Wishlist with Token Endpoint
The `GET` endpoint at `/wishlists/<TOKEN>` allows anyone to access the wishlist using its token, where `<TOKEN>` is the token retrieved from the [Generate Share Token Endpoint](#generate-share-token-endpoint).
The endpoint doesn't accept any request body parameters.
The request returns an object in the response having the following properties:
- `items`: an array of objects, each being an item in the wishlist.
- `first_name`: a string indicating the first name of the customer that this wishlist belongs to.

27
www/docs/content/plugins/overview.mdx
View File

@@ -56,6 +56,15 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation]
description: 'Check out official Payment plugins.'
}
},
{
type: 'link',
href: '/plugins/fulfillment',
label: 'Fulfillment',
customProps: {
icon: Icons['squares-plus-solid'],
description: 'Check out official Fulfillment plugins.'
}
},
{
type: 'link',
href: '/plugins/search',
@@ -74,6 +83,24 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation]
description: 'Check out official File Service plugins.'
}
},
{
type: 'link',
href: '/plugins/erp',
label: 'ERP',
customProps: {
icon: Icons['squares-plus-solid'],
description: 'Check out official ERP plugins.'
}
},
{
type: 'link',
href: '/plugins/source',
label: 'Source',
customProps: {
icon: Icons['squares-plus-solid'],
description: 'Check out official Source plugins.'
}
},
{
type: 'link',
href: '/plugins/other',

2
www/docs/content/plugins/payment/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Payment Plugins
If you can't find your payment provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Payment&categories=Payment). You can also [create your own fulfillment provider](../../modules/carts-and-checkout/backend/add-payment-provider.md).
<DocCardList />

2
www/docs/content/plugins/search/index.mdx
View File

@@ -2,4 +2,6 @@ import DocCardList from '@theme/DocCardList';
# Search Plugins
If you can't find your search provider, try checking the [Community Plugins Library](https://medusajs.com/plugins/?filters=Search&categories=Search). You can also [create your own search service](../../development/search/create.md).
<DocCardList />

7
www/docs/content/plugins/source/index.mdx Normal file
View File

@@ -0,0 +1,7 @@
import DocCardList from '@theme/DocCardList';
# Source Plugins
Source plugins are plugins that allow you to migrate from other ecommerce platforms to Medusa.
<DocCardList />

89
www/docs/content/plugins/source/shopify.md Normal file
View File

@@ -0,0 +1,89 @@
---
addHowToData: true
---
# Shopify Source Plugin
This document will guide you through installing the shopify source plugin on your Medusa backend.
## Overview
If you're migrating from Shopify to Medusa, this plugin will facilitate the process for you. It migrates data related to your products on Shopify to Medusa. It also registers a scheduled job that runs periodically and ensures your data is synced between Shopify and Medusa.
---
## Prerequisites
### Medusa Backend
A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../create-medusa-app.mdx) to get started in minutes.
### Shopify Account
Using this plugin requires having a Shopify account with access to development keys and resources.
### Private Shopify App
This plugin authenticates with Shopify through a private app that has Read access to products.
To create a private app:
1. Open your Shopify store's dashboard
2. Choose Apps from the sidebar
3. Scroll down and click on "Manage private apps"
4. If asked, enable private app development.
5. Once enabled, click on the "Create private app" button.
6. In the form, enter the app's name and email.
7. In the Admin API section, click on "Show inactive Admin API permissions" then, for Products, choose "Read Access".
8. Once done, click on the "Save" button.
9. Click the "Create App" button in the pop-up that shows up.
10. Copy the Password to use for the plugin's configurations.
---
## Install Plugin
In the directory of your Medusa backend, run the following command to install the plugin:
```bash npm2yarn
npm install medusa-source-shopify
```
Then, add the following environment variables to `.env`:
```bash
SHOPIFY_DOMAIN=<YOUR_SHOPIFY_DOMAIN>
SHOPIFY_PASSWORD=<YOUR_SHOPIFY_PASSWORD>
```
Where:
- `<YOUR_SHOPIFY_DOMAIN>` is the subdomain of the Shopify store that you're migrating. If you're not sure what it is, your store's domain should be of the format `<DOMAIN>.myshopify.com`. The `<DOMAIN>` is the value of this environment variable.
- `<YOUR_SHOPIFY_PASSWORD>` is the password for the [private app](#private-shopify-app) you created.
Finally, add the plugin to the `plugins` array in `medusa-config.js`:
```js title=medusa-config.js
const plugins = [
// ...,
{
resolve: "medusa-source-shopify",
options: {
domain: process.env.SHOPIFY_DOMAIN,
password: process.env.SHOPIFY_PASSWORD,
},
},
]
```
---
## Test the Plugin
To test the plugin, run the following command in the directory of the Medusa backend to start the backend:
```bash
npx medusa develop
```
As the backend starts, so does the migration script. The products and its data will be migrated into Medusa.

101
www/docs/sidebars.js
View File

@@ -2217,6 +2217,40 @@ module.exports = {
},
],
},
{
type: "category",
label: "Fulfillment",
collapsible: false,
link: {
type: "doc",
id: "plugins/fulfillment/index",
},
customProps: {
sidebar_is_group_headline: true,
},
items: [
{
type: "doc",
id: "plugins/fulfillment/webshipper",
label: "Webshipper",
customProps: {
iconName: "bolt-solid",
description:
"Learn how to integrate Webshipper with the Medusa backend.",
},
},
{
type: "doc",
id: "plugins/fulfillment/manual",
label: "Manual Fulfillment",
customProps: {
iconName: "bolt-solid",
description:
"Learn how to integrate manual fulfillment in the Medusa backend.",
},
},
],
},
{
type: "category",
label: "Search",
@@ -2304,6 +2338,54 @@ module.exports = {
},
],
},
{
type: "category",
label: "ERP",
collapsible: false,
link: {
type: "doc",
id: "plugins/erp/index",
},
customProps: {
sidebar_is_group_headline: true,
},
items: [
{
type: "doc",
id: "plugins/erp/brightpearl",
label: "Brightpearl",
customProps: {
iconName: "bolt-solid",
description:
"Learn how to integrate Brightpearl with the Medusa backend.",
},
},
],
},
{
type: "category",
label: "Source",
collapsible: false,
link: {
type: "doc",
id: "plugins/source/index",
},
customProps: {
sidebar_is_group_headline: true,
},
items: [
{
type: "doc",
id: "plugins/source/shopify",
label: "Shopify",
customProps: {
iconName: "bolt-solid",
description:
"Learn how to install this plugin to migrate data from Shopify.",
},
},
],
},
{
type: "category",
label: "Other",
@@ -2326,6 +2408,25 @@ module.exports = {
"Learn how to integrate ipstack to access the user's region.",
},
},
{
type: "doc",
id: "plugins/other/discount-generator",
label: "Discount Generator",
customProps: {
iconName: "bolt-solid",
description: "Learn how to add a discount generator in Medusa.",
},
},
{
type: "doc",
id: "plugins/other/wishlist",
label: "Wishlist",
customProps: {
iconName: "bolt-solid",
description:
"Learn how to add wishlists for customers in Medusa.",
},
},
],
},
],