diff --git a/packages/medusa-fulfillment-manual/README.md b/packages/medusa-fulfillment-manual/README.md index 52418fb063..bf7af9e4ed 100644 --- a/packages/medusa-fulfillment-manual/README.md +++ b/packages/medusa-fulfillment-manual/README.md @@ -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. \ No newline at end of file diff --git a/packages/medusa-plugin-brightpearl/README.md b/packages/medusa-plugin-brightpearl/README.md index fcb4a797c7..10c345a701 100644 --- a/packages/medusa-plugin-brightpearl/README.md +++ b/packages/medusa-plugin-brightpearl/README.md @@ -37,12 +37,15 @@ Manage and streamline your business processes using Brightpearl. BRIGHTPEARL_WAREHOUSE= BRIGHTPEARL_DEFAULT_STATUS_ID= BRIGHTPEARL_SWAP_STATUS_ID= + BRIGHTPEARL_CLAIM_STATUS_ID= BRIGHTPEARL_PAYMENT_METHOD_CODE= BRIGHTPEARL_SALES_ACCOUNT_CODE= BRIGHTPEARL_SHIPPING_ACCOUNT_CODE= BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE= BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE= BRIGHTPEARL_INVENTORY_SYNC_CRON= + BRIGHTPEARL_COST_PRICE_LIST= + BRIGHTPEARL_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. }, }, ] diff --git a/packages/medusa-plugin-wishlist/README.md b/packages/medusa-plugin-wishlist/README.md index 54aea1ac70..15db673e3b 100644 --- a/packages/medusa-plugin-wishlist/README.md +++ b/packages/medusa-plugin-wishlist/README.md @@ -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) diff --git a/www/docs/content/plugins/analytics/index.mdx b/www/docs/content/plugins/analytics/index.mdx index 4ff3018c3f..67049e6929 100644 --- a/www/docs/content/plugins/analytics/index.mdx +++ b/www/docs/content/plugins/analytics/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/analytics/segment.md b/www/docs/content/plugins/analytics/segment.md index e25c477cb0..b44df00732 100644 --- a/www/docs/content/plugins/analytics/segment.md +++ b/www/docs/content/plugins/analytics/segment.md @@ -129,7 +129,7 @@ const plugins = [ Run your backend with the following command: -```bash npm2yarn +```bash npx medusa develop ``` diff --git a/www/docs/content/plugins/cms/index.mdx b/www/docs/content/plugins/cms/index.mdx index b12b03b35a..5060991b96 100644 --- a/www/docs/content/plugins/cms/index.mdx +++ b/www/docs/content/plugins/cms/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/erp/brightpearl.md b/www/docs/content/plugins/erp/brightpearl.md new file mode 100644 index 0000000000..5cb0256b6d --- /dev/null +++ b/www/docs/content/plugins/erp/brightpearl.md @@ -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= +BRIGHTPEARL_CHANNEL_ID= +BRIGHTPEARL_BACKEND_URL= +BRIGHTPEARL_EVENT_OWNER= +BRIGHTPEARL_WAREHOUSE= +BRIGHTPEARL_DEFAULT_STATUS_ID= +BRIGHTPEARL_SWAP_STATUS_ID= +BRIGHTPEARL_CLAIM_STATUS_ID= +BRIGHTPEARL_PAYMENT_METHOD_CODE= +BRIGHTPEARL_SALES_ACCOUNT_CODE= +BRIGHTPEARL_SHIPPING_ACCOUNT_CODE= +BRIGHTPEARL_DISCOUNT_ACCOUNT_CODE= +BRIGHTPEARL_GIFT_CARD_ACCOUNT_CODE= +BRIGHTPEARL_INVENTORY_SYNC_CRON= +BRIGHTPEARL_COST_PRICE_LIST= +BRIGHTPEARL_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 `/a/settings/apps`, where `` 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. diff --git a/www/docs/content/plugins/erp/index.mdx b/www/docs/content/plugins/erp/index.mdx new file mode 100644 index 0000000000..74b18fadb6 --- /dev/null +++ b/www/docs/content/plugins/erp/index.mdx @@ -0,0 +1,5 @@ +import DocCardList from '@theme/DocCardList'; + +# ERP Plugins + + \ No newline at end of file diff --git a/www/docs/content/plugins/file-service/index.mdx b/www/docs/content/plugins/file-service/index.mdx index 8f512e2f3f..415edbcbb2 100644 --- a/www/docs/content/plugins/file-service/index.mdx +++ b/www/docs/content/plugins/file-service/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/file-service/local.md b/www/docs/content/plugins/file-service/local.md index e914102222..286d82d388 100644 --- a/www/docs/content/plugins/file-service/local.md +++ b/www/docs/content/plugins/file-service/local.md @@ -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. diff --git a/www/docs/content/plugins/fulfillment/index.mdx b/www/docs/content/plugins/fulfillment/index.mdx new file mode 100644 index 0000000000..7380f0dc59 --- /dev/null +++ b/www/docs/content/plugins/fulfillment/index.mdx @@ -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). + + \ No newline at end of file diff --git a/www/docs/content/plugins/fulfillment/manual.md b/www/docs/content/plugins/fulfillment/manual.md new file mode 100644 index 0000000000..f5d46ab09d --- /dev/null +++ b/www/docs/content/plugins/fulfillment/manual.md @@ -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. diff --git a/www/docs/content/plugins/fulfillment/webshipper.md b/www/docs/content/plugins/fulfillment/webshipper.md new file mode 100644 index 0000000000..5c7716897f --- /dev/null +++ b/www/docs/content/plugins/fulfillment/webshipper.md @@ -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://.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= +WEBSHIPPER_API_TOKEN= +WEBSHIPPER_ORDER_CHANNEL_ID= +WEBSHIPPER_WEBHOOK_SECRET= +WEBSHIPPER_COO_COUNTRIES= +WEBSHIPPER_DELETE_ON_CANCEL= +WEBSHIPPER_DOCUMENT_SIZE= +# Return Portal Variables +WEBSHIPPER_RETURN_PORTAL_ID= +WEBSHIPPER_RETURN_PORTAL_CAUSE_ID= +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" + ) + }) +} +``` diff --git a/www/docs/content/plugins/notifications/index.mdx b/www/docs/content/plugins/notifications/index.mdx index 86759a60d2..8d175c867e 100644 --- a/www/docs/content/plugins/notifications/index.mdx +++ b/www/docs/content/plugins/notifications/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/other/discount-generator.md b/www/docs/content/plugins/other/discount-generator.md new file mode 100644 index 0000000000..8031d011e8 --- /dev/null +++ b/www/docs/content/plugins/other/discount-generator.md @@ -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 +} +``` \ No newline at end of file diff --git a/www/docs/content/plugins/other/index.mdx b/www/docs/content/plugins/other/index.mdx index 383e19ba2f..68b6cb8b9d 100644 --- a/www/docs/content/plugins/other/index.mdx +++ b/www/docs/content/plugins/other/index.mdx @@ -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. + \ No newline at end of file diff --git a/www/docs/content/plugins/other/wishlist.md b/www/docs/content/plugins/other/wishlist.md new file mode 100644 index 0000000000..2f55f771b0 --- /dev/null +++ b/www/docs/content/plugins/other/wishlist.md @@ -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//wishlist` allows customers to add items to their existing or new wishlist, where `` 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//wishlist` allows customers to delete items from their wishlist, where `` 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//wishlist/share-token` allows customers to retrieve a token that can be used to access the wishlist, where `` 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/` allows anyone to access the wishlist using its token, where `` 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. diff --git a/www/docs/content/plugins/overview.mdx b/www/docs/content/plugins/overview.mdx index 034020987d..76227a8288 100644 --- a/www/docs/content/plugins/overview.mdx +++ b/www/docs/content/plugins/overview.mdx @@ -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', diff --git a/www/docs/content/plugins/payment/index.mdx b/www/docs/content/plugins/payment/index.mdx index 07e39be058..b4f3bc5e97 100644 --- a/www/docs/content/plugins/payment/index.mdx +++ b/www/docs/content/plugins/payment/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/search/index.mdx b/www/docs/content/plugins/search/index.mdx index 6be91dd84e..5a1365031e 100644 --- a/www/docs/content/plugins/search/index.mdx +++ b/www/docs/content/plugins/search/index.mdx @@ -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). + \ No newline at end of file diff --git a/www/docs/content/plugins/source/index.mdx b/www/docs/content/plugins/source/index.mdx new file mode 100644 index 0000000000..68c414f785 --- /dev/null +++ b/www/docs/content/plugins/source/index.mdx @@ -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. + + \ No newline at end of file diff --git a/www/docs/content/plugins/source/shopify.md b/www/docs/content/plugins/source/shopify.md new file mode 100644 index 0000000000..1fbac9c789 --- /dev/null +++ b/www/docs/content/plugins/source/shopify.md @@ -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= +SHOPIFY_PASSWORD= +``` + +Where: + +- `` 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 `.myshopify.com`. The `` is the value of this environment variable. +- `` 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. diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index e7354b3bdf..4260974c8d 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -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.", + }, + }, ], }, ],