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

chore: updated READMEs of plugins (#3546)

Browse Source 
* chore: updated READMEs of plugins

* added notice to plugins
This commit is contained in:
Shahed Nasser
2023-03-23 09:43:17 +02:00
committed by GitHub
parent 6e0b9c3991
commit 95232e7ac9
27 changed files with 1661 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/plugins/payment/klarna.md
View File

@@ -62,7 +62,7 @@ Finally, in `medusa-config.js`, add the Klarna plugin to the `plugins` array wit
const plugins = [
// other plugins...
{
resolve: `medusa-payment-klarnal`,
resolve: `medusa-payment-klarna`,
options: {
backend_url: process.env.KLARNA_BACKEND_URL,
url: process.env.KLARNA_URL,

86
packages/medusa-file-minio/README.md
View File

@@ -1,38 +1,72 @@
# medusa-file-minio
# MinIO
Upload files to a MinIO server.
Store uploaded files to your Medusa backend on MinIO.
Learn more about how you can use this plugin in the [documentation](https://docs.medusajs.com/add-plugins/minio).
[Plugin Documentation](https://docs.medusajs.com/plugins/file-service/minio) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
endpoint: "minio.server.com",
bucket: "test",
access_key_id: "YOUR-ACCESS-KEY",
secret_access_key: "YOUR-SECRET-KEY",
- Store product images on MinIO
- Support for importing and exporting data through CSV files, such as Products or Prices.
- Support for both private and public buckets.
// private bucket configuration
private_bucket: 'private-bucket',
private_access_key_id: "YOUR-ACCESS-KEY",
private_secret_access_key: "YOUR-SECRET-KEY",
}
```
---
Optionally a `download_url_duration` option can be specified to change the valid duration of presigned download links. The duration is configured in seconds. (Default = 60 seconds)
## Prerequisites
## Configuring a private bucket in Minio
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [MinIO](https://docs.min.io/minio/baremetal/quickstart/quickstart.html)
Certain operations in Medusa such as data import and export require a separate, protected bucket. The plugin will raise an error if operations used for imports and exports are invoked without the correct setup.
---
Configuring Minio for requires configuration of one additional option: `private_bucket` which refers to the name given to the protected bucket in Minio.
## How to Install
Separate credentials can, optionally, be used to access the private bucket by configuring the following options:
1\. Run the following command in the directory of the Medusa backend:
```
private_access_key_id: "YOUR-ACCESS-KEY",
private_secret_access_key: "YOUR-SECRET-KEY",
```
```bash
npm install medusa-file-minio
```
If no separate access key is given the same access key will be used for both the `bucket` and the `private_bucket`.
2\. Set the following environment variables in `.env`:
```bash
MINIO_ENDPOINT=<ENDPOINT>
MINIO_BUCKET=<BUCKET>
MINIO_ACCESS_KEY=<ACCESS_KEY>
MINIO_SECRET_KEY=<SECRET_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-file-minio`,
options: {
endpoint: process.env.MINIO_ENDPOINT,
bucket: process.env.MINIO_BUCKET,
access_key_id: process.env.MINIO_ACCESS_KEY,
secret_access_key: process.env.MINIO_SECRET_KEY,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Upload an image for a product using the admin dashboard or using [the Admin APIs](https://docs.medusajs.com/api/admin#tag/Upload).
---
## Additional Resources
- [MinIO Plugin Documentation](https://docs.medusajs.com/plugins/file-service/minio)

86
packages/medusa-file-s3/README.md
View File

@@ -1,20 +1,74 @@
# medusa-file-s3
# S3
Upload files to an AWS S3 bucket.
Store uploaded files to your Medusa backend on S3.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/s3).
[Plugin Documentation](https://docs.medusajs.com/plugins/file-service/s3) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
s3_url: "https://s3-guide-test.s3.eu-west-1.amazonaws.com",
bucket: "test",
region: "eu-west-1"
access_key_id: "YOUR-ACCESS-KEY",
secret_access_key: "YOUR-SECRET-KEY",
aws_config_object : {
// object for aws config properties
}
}
```
- Store product images on S3
- Support for importing and exporting data through CSV files, such as Products or Prices.
- Support for Bucket Policies and User Permissions.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [S3](https://aws.amazon.com/s3)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-file-s3
```
2\. Set the following environment variables in `.env`:
```bash
S3_URL=<YOUR_BUCKET_URL>
S3_BUCKET=<YOUR_BUCKET_NAME>
S3_REGION=<YOUR_BUCKET_REGION>
S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
S3_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-file-s3`,
options: {
s3_url: process.env.S3_URL,
bucket: process.env.S3_BUCKET,
region: process.env.S3_REGION,
access_key_id: process.env.S3_ACCESS_KEY_ID,
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Upload an image for a product using the admin dashboard or using [the Admin APIs](https://docs.medusajs.com/api/admin#tag/Upload).
---
## Additional Resources
- [S3 Plugin Documentation](https://docs.medusajs.com/plugins/file-service/s3)

82
packages/medusa-file-spaces/README.md
View File

@@ -1,19 +1,73 @@
# medusa-file-spaces
# DigitalOcean Spaces
Upload files to a DigitalOcean Space.
Store uploaded files to your Medusa backend on Spaces.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/spaces).
[Plugin Documentation](https://docs.medusajs.com/plugins/file-service/spaces) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
spaces_url: "https://test.fra1.digitaloceanspaces.com",
bucket: "test",
endpoint: "fra1.digitaloceanspaces.com",
access_key_id: "YOUR-ACCESS-KEY",
secret_access_key: "YOUR-SECRET-KEY",
}
```
- Store product images on DigitalOcean Spaces
- Support for importing and exporting data through CSV files, such as Products or Prices.
Optionally a `download_url_duration` option can be specified to change the valid duration of presigned download links. The duration is configured in seconds. (Default = 60 seconds)
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-file-spaces
```
2\. Set the following environment variables in `.env`:
```bash
SPACE_URL=<YOUR_SPACE_URL>
SPACE_BUCKET=<YOUR_SPACE_NAME>
SPACE_ENDPOINT=<YOUR_SPACE_ENDPOINT>
SPACE_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
SPACE_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-file-spaces`,
options: {
spaces_url: process.env.SPACE_URL,
bucket: process.env.SPACE_BUCKET,
endpoint: process.env.SPACE_ENDPOINT,
access_key_id: process.env.SPACE_ACCESS_KEY_ID,
secret_access_key: process.env.SPACE_SECRET_ACCESS_KEY,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Upload an image for a product using the admin dashboard or using [the Admin APIs](https://docs.medusajs.com/api/admin#tag/Upload).
---
## Additional Resources
- [Spaces Plugin Documentation](https://docs.medusajs.com/plugins/file-service/spaces)

48
packages/medusa-fulfillment-manual/README.md Normal file
View File

@@ -0,0 +1,48 @@
# Manual Fulfillment
A minimal fulfillment provider that allows merchants to handle fulfillments manually.
[Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Provides a restriction-free fulfillment provider that can be used during checkout and while processing orders.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-fulfillment-manual
```
2\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
`medusa-fulfillment-manual`
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
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\. 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.

93
packages/medusa-fulfillment-webshipper/README.md
View File

@@ -1,26 +1,85 @@
# medusa-fulfillment-webshipper
# Webshipper
Adds Webshipper as a fulfilment provider in Medusa Commerce.
Handle order fulfillments using Webshipper.
On each new fulfillment an order is created in Webshipper. The plugin listens for shipment events and updated the shipment accordingly.
A webhook listener is exposed at `/webshipper/shipments` to listen for shipment creations. You must create this webhook in Webshipper to have Medusa listen for shipment events.
[Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```
account: [your webshipper account] (required)
api_token: [a webshipper api token] (required)
order_channel_id: [the channel id to register orders on] (required)
webhook_secret: [the webhook secret used to listen for shipments] (required)
coo_countries: [an array of countries in which a Certificate of Origin will be attached] (default: "all")
delete_on_cancel [determines whether Webshipper orders are deleted when a Medusa fulfillment is canceled] (default: false)
```
- Webshipper can be used as a shipping option during checkouts and for handling order fulfillment.
- Sync order details and updates with Webshipper.
- Support for Webshipper webhooks.
## Personal Customs Numbers
---
In countries like South Korea a personal customs number is required to clear customs. The Webshipper fulfillment plugin is able pass this information to Webshipper given that the number is stored in `order.shipping_address.metadata.personal_customs_no`.
## Prerequisites
### Modifications in checkout flow
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Webshipper Account](https://webshipper.com)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-fulfillment-webshipper
```
2\. Set the following environment variables 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=<WEBSHIPPER_COO_COUNTRIES>
WEBSHIPPER_DELETE_ON_CANCEL=<WEBSHIPPER_DELETE_ON_CANCEL>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-fulfillment-webshipper`,
options: {
account: process.env.WEBSHIPPER_ACCOUNT, // required
api_token: process.env.WEBSHIPPER_API_TOKEN, // required
order_channel_id: process.env.WEBSHIPPER_ORDER_CHANNEL_ID, // required, the channel id to register orders on
webhook_secret: process.env.WEBSHIPPER_WEBHOOK_SECRET, // required, the webhook secret used to listen for shipments
coo_countries: process.env.WEBSHIPPER_COO_COUNTRIES, // default: "all", an array of countries or a string of one country in which a Certificate of Origin will be attached
delete_on_cancel: process.env.WEBSHIPPER_DELETE_ON_CANCEL, // default: false, determines whether Webshipper orders are deleted when a Medusa fulfillment is canceled
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
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\. 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.
---
## Additional Details
### Personal Customs Numbers
In countries like South Korea, a personal customs number is required to clear customs. The Webshipper fulfillment plugin is able pass this information to Webshipper given that the number is stored in `order.shipping_address.metadata.personal_customs_no`.
#### Modifications in Checkout Flow
To pass the information along you should dynamically show an input field to the customer when they are shopping from a region that requires a personal customs number, and make sure that the metadata field is set when updating the cart shipping address.
@@ -43,4 +102,4 @@ const onUpdateAddress = async () => {
console.log("Good stuff - Webshipper will pass along the customs number")
})
}
```
```

79
packages/medusa-payment-adyen/README.md Normal file
View File

@@ -0,0 +1,79 @@
# Adyen
Receive payments on your Medusa commerce application using Adyen.
> This plugin is not ready for production use. Community contributions are highly appreciated. You can learn more about contributing in [our repository](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md).
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Authorize payments on orders from any sales channel.
- Support for MobilePay.
- Capture payments from the admin dashboard.
- Support for Webhooks.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Adyen account](https://www.adyen.com)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-payment-adyen
```
2\. Set the following environment variables in `.env`:
```bash
ADYEN_API_KEY=<YOUR_API_KEY>
ADYEN_NOTIFICATION_HMAC=<YOUR_NOTIFICATION_HMAC>
ADYEN_RETURN_URL=<YOUR_RETURN_URL>
ADYEN_MERCHANT_ACCOUNT=<YOUR_MERCHANT_ACCOUNT>
ADYEN_ORIGIN=<YOUR_ORIGIN>
ADYEN_ENVIRONMENT=<YOUR_ENVIRONMENT>
ADYEN_LIVE_ENDPOINT_PREFIX=<YOUR_LIVE_ENDPOINT_PREFIX>
ADYEN_PAYMENT_ENDPOINT=<YOUR_PAYMENT_ENDPOINT>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-payment-adyen`,
options: {
api_key: process.env.STRIPE_API_KEY,
notification_hmac: process.env.ADYEN_NOTIFICATION_HMAC,
return_url: process.env.ADYEN_RETURN_URL,
merchant_account: process.env.ADYEN_MERCHANT_ACCOUNT,
origin: process.env.ADYEN_ORIGIN,
environment: process.env.ADYEN_ENVIRONMENT,
live_endpoint_prefix: process.env.ADYEN_LIVE_ENDPOINT_PREFIX,
payment_endpoint: process.env.ADYEN_PAYMENT_ENDPOINT,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Enable Adyen in a region 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\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use Stripe as a payment method.

82
packages/medusa-payment-klarna/README.md Normal file
View File

@@ -0,0 +1,82 @@
# Klarna
Receive payments on your Medusa commerce application using Klarna.
[Klarna Plugin Documentation](https://docs.medusajs.com/plugins/payment/klarna) | [Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Authorize payments on orders from any sales channel.
- Capture payments from the admin dashboard.
- Support for Webhooks.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Klarna account](https://www.klarna.com/)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-payment-klarna
```
2\. Set the following environment variables in `.env`:
```bash
KLARNA_BACKEND_URL=<YOUR_KLARNA_BACKEND_URL>
KLARNA_URL=<YOUR_KLARNA_URL>
KLARNA_USER=<YOUR_KLARNA_USER>
KLARNA_PASSWORD=<YOUR_KLARNA_PASSWORD>
KLARNA_TERMS_URL=<YOUR_KLARNA_TERMS_URL>
KLARNA_CHECKOUT_URL=<YOUR_KLARNA_CHECKOUT_URL>
KLARNA_CONFIRMATION_URL=<YOUR_KLARNA_CONFIRMATION_URL>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// other plugins...
{
resolve: `medusa-payment-klarna`,
options: {
backend_url: process.env.KLARNA_BACKEND_URL,
url: process.env.KLARNA_URL,
user: process.env.KLARNA_USER,
password: process.env.KLARNA_PASSWORD,
merchant_urls: {
terms: process.env.KLARNA_TERMS_URL,
checkout: process.env.KLARNA_CHECKOUT_URL,
confirmation: process.env.KLARNA_CONFIRMATION_URL,
},
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Enable Klarna in a region 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\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use Stripe as a payment method.
---
## Additional Resources
- [Klarna Plugin Documentation](https://docs.medusajs.com/plugins/payment/klarna)

48
packages/medusa-payment-manual/README.md Normal file
View File

@@ -0,0 +1,48 @@
# Manual Payment
A minimal payment provider that allows merchants to handle payments manually.
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Provides a restriction-free payment provider that can be used during checkout and while processing orders.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-payment-manual
```
2\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
`medusa-payment-manual`
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Enable the payment provider in a region 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\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use Stripe as a payment method.

84
packages/medusa-payment-paypal/README.md
View File

@@ -1,16 +1,76 @@
# medusa-payment-paypal
# PayPal
Add PayPal as a Payment Provider.
Receive payments on your Medusa commerce application using PayPal.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/paypal).
[PayPal Plugin Documentation](https://docs.medusajs.com/plugins/payment/paypal) | [Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
sandbox: true, //default false
client_id: "CLIENT_ID", // REQUIRED
client_secret: "CLIENT_SECRET", // REQUIRED
auth_webhook_id: "WEBHOOK_ID" //REQUIRED for webhook to work
}
```
- Authorize payments on orders from any sales channel.
- Capture payments from the admin dashboard.
- View payment analytics through PayPal's dashboard.
- Ready-integration with [Medusa's Next.js starter storefront](https://docs.medusajs.com/starters/nextjs-medusa-starter).
- Support for Webhooks.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [PayPal account](https://www.paypal.com)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-payment-paypal
```
2\. Set the following environment variables in `.env`:
```bash
PAYPAL_SANDBOX=true
PAYPAL_CLIENT_ID=<CLIENT_ID>
PAYPAL_CLIENT_SECRET=<CLIENT_SECRET>
PAYPAL_AUTH_WEBHOOK_ID=<WEBHOOK_ID>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-payment-paypal`,
options: {
sandbox: process.env.PAYPAL_SANDBOX,
client_id: process.env.PAYPAL_CLIENT_ID,
client_secret: process.env.PAYPAL_CLIENT_SECRET,
auth_webhook_id: process.env.PAYPAL_AUTH_WEBHOOK_ID,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Enable PayPal in a region 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\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use Stripe as a payment method.
---
## Additional Resources
- [PayPal Plugin Documentation](https://docs.medusajs.com/plugins/payment/paypal)

81
packages/medusa-payment-stripe/README.md
View File

@@ -1,19 +1,74 @@
# medusa-payment-stripe
# Stripe
Add Stripe as a Payment Provider.
Receive payments on your Medusa commerce application using Stripe.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/stripe).
[Stripe Plugin Documentation](https://docs.medusajs.com/plugins/payment/stripe) | [Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
api_key: "STRIPE_API_KEY",
webhook_secret: "STRIPE_WEBHOOK_SECRET",
automatic_payment_methods: true
}
```
- Authorize payments on orders from any sales channel.
- Support for Bancontact, BLIK, giropay, iDEAL, and Przelewy24.
- Capture payments from the admin dashboard.
- View payment analytics through Stripe's dashboard.
- Ready-integration with [Medusa's Next.js starter storefront](https://docs.medusajs.com/starters/nextjs-medusa-starter).
- Support for Stripe Webhooks.
## Automatic Payment Methods
---
If you wish to use [Stripe's automatic payment methods](https://stripe.com/docs/connect/automatic-payment-methods) set the `automatic_payment_methods` flag to true.
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Stripe account](https://stripe.com/)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-payment-stripe
```
2\. Set the following environment variables in `.env`:
```bash
STRIPE_API_KEY=sk_...
# only necessary for production
STRIPE_WEBHOOK_SECRET=whsec_...
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-payment-stripe`,
options: {
api_key: process.env.STRIPE_API_KEY,
webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Enable Stripe in a region 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\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use Stripe as a payment method.
---
## Additional Resources
- [Stripe Plugin Documentation](https://docs.medusajs.com/plugins/payment/stripe)

100
packages/medusa-plugin-algolia/README.md
View File

@@ -1,22 +1,86 @@
# medusa-plugin-algolia
# Algolia
Algolia Plugin for Medusa to search for products.
Provide powerful indexing and searching features in your commerce application with Algolia.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/algolia).
[Algolia Plugin Documentation](https://docs.medusajs.com/plugins/search/algolia) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
application_id: "someId",
admin_api_key: "someApiKey",
settings: {
[indexName]: [algolia settings passed to algolia's `updateSettings()` method]
// example
products: {
searchableAttributes: ["title", "description", "variant_sku", "type_value"],
attributesToRetrieve: ["title", "description", "variant_sku", "type_value"],
}
}
}
```
- Flexible configurations for specifying searchable and retrievable attributes.
- Ready-integration with [Medusa's Next.js starter storefront](https://docs.medusajs.com/starters/nextjs-medusa-starter).
- Utilize Algolia's powerful search functionalities including typo-tolerance, query suggestions, results ranking, and more.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Algolia account](https://www.algolia.com/)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-algolia
```
2\. Set the following environment variables in `.env`:
```bash
ALGOLIA_APP_ID=<YOUR_APP_ID>
ALGOLIA_ADMIN_API_KEY=<YOUR_ADMIN_API_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-plugin-algolia`,
options: {
application_id: process.env.ALGOLIA_APP_ID,
admin_api_key: process.env.ALGOLIA_ADMIN_API_KEY,
settings: {
products: {
searchableAttributes: ["title", "description"],
attributesToRetrieve: [
"id",
"title",
"description",
"handle",
"thumbnail",
"variants",
"variant_sku",
"options",
"collection_title",
"collection_handle",
"images",
],
},
},
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Try searching products either using your storefront or using the [Store APIs](https://docs.medusajs.com/api/store#tag/Product/operation/PostProductsSearch).
---
## Additional Resources
- [Algolia Plugin Documentation](https://docs.medusajs.com/plugins/search/algolia)

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

@@ -1,37 +1,102 @@
# medusa-plugin-brightpearl
# Brightpearl
Sends orders to Brightpearl, listens for stock movements, handles returns.
Manage and streamline your business processes using Brightpearl.
## Options
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
```
account: [the Brightpearl account] (required)
channel_id: [channel id to map sales and credits to] (required)
backend_url: [the url where the Medusa server is running, needed for webhooks] (required)
event_owner: [the id of the user who will own goods out events] (required),
warehouse: [the warehouse id to allocate orders from] (required)
default_status_id: [the status id to assign new orders with] (optional: defaults to 1)
swap_status_id: [the status id to assign new swaps] (optional: defaults to 1)
payment_method_code: [the method code to register payments with] (optional: defaults to 1220)
sales_account_code: [nominal code to assign line items to] (optional: defaults to 4000)
shipping_account_code: [nominal code to assign shipping line to] (optional: defaults to 4040)
discount_account_code: [nominal code to use for Discount-type refunds] (optional)
gift_card_account_code: [nominal code to use for gift card products and redeems] (optional: default to 4000)
inventory_sync_cron: [cron pattern for inventory sync, if left out the job will not be created] (default: false)
```
## Features
- Send and sync orders with Brightpearl.
- Listen for inventory and stock movements in Brightpearl.
- Handle order returns through Brightpearl.
## Orders
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Brightpearl account](https://www.brightpearl.com)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-brightpearl
```
2\. Set the following environment variables 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_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>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-plugin-brightpearl`,
options: {
account: process.env.BRIGHTPEARL_ACCOUNT, // required, the Brightpearl account
channel_id: process.env.BRIGHTPEARL_CHANNEL_ID, // required, channel id to map sales and credits to
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
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
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. On placing an order, you should see that order appear on Brightpearl.
---
## Additional Information
### Orders
When an order is created in Medusa it will 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 Medusa will send the order to the fulfillment provider associated with the shipping method selected by the Customer.
When line items on an order are returned the plugin will generate a sales credit in Brightpearl.
## Products
### Products
The plugin doesn't automatically create products in Medusa, but listens for inventory changes in Brightpearl. 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.
## OAuth
The plugin registers an OAuth app in Medusa allowing installation at https://medusa-commerce.com/a/settings/apps. The OAuth tokens are refreshed every hour to prevent unauthorized requests.
### OAuth
The plugin registers an OAuth app in Medusa allowing installation at https://medusa-commerce.com/a/settings/apps. The OAuth tokens are refreshed every hour to prevent unauthorized requests.

98
packages/medusa-plugin-contentful/README.md
View File

@@ -1,15 +1,91 @@
# medusa-payment-contentful
# Contentful
Integrate Contentful with Medusa for rich CMS functionalities.
Manage the content of your storefront with rich Content Management System (CMS) capabilities using Contentful.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/contentful).
[Contentful Plugin Documentation](https://docs.medusajs.com/plugins/cms/contentful/) | [Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
space_id: "CONTENTFUL_SPACE_ID",
access_token: "CONTENTFUL_ACCESS_TOKEN",
environment: "CONTENTFUL_ENV",
}
```
- Handle the presentational content of your commerce application using Contentful.
- Two-way sync between Medusa and Contentful, allowing you to manage products details consistently.
- Benefit from Contentful's advanced CMS features such as localization and versioning.
---
## Prerequisites
- [Contentful account](https://stripe.com/)
- [Medusa CLI Tool](https://docs.medusajs.com/cli/reference#how-to-install-cli-tool)
- [PostgreSQL](https://docs.medusajs.com/development/backend/prepare-environment#postgresql)
- [Redis](https://docs.medusajs.com/development/backend/prepare-environment#redis)
---
## How to Install
1\. Run the following command to install a new Medusa server configured with Contentful:
```bash
medusa new medusa-contentful https://github.com/medusajs/medusa-starter-contentful
```
2\. Change to the newly created directory `medusa-contentful`:
```bash
cd medusa-contentful
```
3\. Set the following environment variables in `.env`:
```bash
CONTENTFUL_SPACE_ID=<YOUR_CONTENTFUL_SPACE_ID>
CONTENTFUL_ACCESS_TOKEN=<YOUR_CONTENTFUL_ACCESS_TOKEN>
CONTENTFUL_ENV=<YOUR_CONTENTFUL_ENV>
REDIS_URL=<YOUR_REDIS_URL>
DATABASE_URL=<YOUR_DB_URL>
```
3\. In `medusa-config.js`, enable PostgreSQL and remove the SQLite configurations:
```js
module.exports = {
projectConfig: {
// ...
database_url: DATABASE_URL,
database_type: "postgres",
// REMOVE OR COMMENT OUT THE BELOW:
// database_database: "./medusa-db.sql",
// database_type: "sqlite",
},
}
```
4\. Migrate the content types into Contentful with the following command:
```bash
npm run migrate:contentful
```
5\. Seed Contentful with demo content data using the following command:
```bash
npm run seed:contentful
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. You can then setup the [Gatsby Contentful Storefront](https://docs.medusajs.com/plugins/cms/contentful/#setup-gatsby-storefront), or connect to Contentful from your own storefront to retrieve content data.
---
## Additional Resources
- [Contentful Plugin Documentation](https://docs.medusajs.com/plugins/cms/contentful/)

41
packages/medusa-plugin-discount-generator/README.md Normal file
View File

@@ -0,0 +1,41 @@
# Discount Generator
Generate dynamic discount codes in your Medusa backend.
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Provides a service that can be used to generate a dynamic discount with a random code.
- Provides an endpoint that can be used to generate a dynamic discount with a random code.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-discount-generator
```
2\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
`medusa-plugin-discount-generator`
]
```
---
## Test the Plugin
Try using the `DiscountGeneratorService` in your code, or using the `/discount-code` endpoint to generate a random discount code.

84
packages/medusa-plugin-economic/README.md Normal file
View File

@@ -0,0 +1,84 @@
# e-conomic
Manage your commerce accounting with e-conomic.
> This plugin is not ready for production use. Community contributions are highly appreciated. You can learn more about contributing in [our repository](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md).
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Create draft and book e-conomic invoices automatically when an order is placed.
- Provide endpoints to manually trigger booking and creating draft e-comonic invoices.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Visma e-conomic account](https://www.e-conomic.com/developer/connect)
- [Redis](https://docs.medusajs.com/development/backend/prepare-environment#redis)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-economic
```
2\. Set the following environment variables in `.env`:
```bash
ECONOMIC_SECRET_TOKEN=<YOUR_SECRET_TOKEN>
ECONOMIC_AGREEMENT_TOKEN=<YOUR_AGREEMENT_TOKEN>
ECONOMIC_CUSTOMER_NUMBER_DK=<YOUR_CUSTOMER_NUMBER_DK>
ECONOMIC_CUSTOMER_NUMBER_EU=<YOUR_CUSTOMER_NUMBER_EU>
ECONOMIC_CUSTOMER_NUMBER_WORLD=<YOUR_CUSTOMER_NUMBER_WORLD>
ECONOMIC_UNIT_NUMBER=<YOUR_UNIT_NUMBER>
ECONOMIC_PAYMENT_TERMS_NUMBER=<YOUR_PAYMENT_TERMS_NUMBER>
ECONOMIC_LAYOUT_NUMBER=<YOUR_LAYOUT_NUMBER>
ECONOMIC_VATZONE_NUMBER_DK=<YOUR_VATZONE_NUMBER_DK>
ECONOMIC_VATZONE_NUMBER_EU=<YOUR_VATZONE_NUMBER_EU>
ECONOMIC_VATZONE_NUMBER_WORLD=<YOUR_VATZONE_NUMBER_WORLD>
ECONOMIC_RECIPIENT_NAME=<YOUR_RECIPIENT_NAME>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// other plugins...
{
resolve: `medusa-plugin-economic`,
options: {
secret_token: process.env.ECONOMIC_SECRET_TOKEN,
agreement_token: process.env.ECONOMIC_AGREEMENT_TOKEN,
customer_number_dk: process.env.ECONOMIC_CUSTOMER_NUMBER_DK,
customer_number_eu: process.env.ECONOMIC_CUSTOMER_NUMBER_EU,
customer_number_world: process.env.ECONOMIC_CUSTOMER_NUMBER_WORLD,
unit_number: process.env.ECONOMIC_UNIT_NUMBER,
payment_terms_number: process.env.ECONOMIC_PAYMENT_TERMS_NUMBER,
layout_number: process.env.ECONOMIC_LAYOUT_NUMBER,
vatzone_number_dk: process.env.ECONOMIC_VATZONE_NUMBER_DK,
vatzone_number_eu: process.env.ECONOMIC_VATZONE_NUMBER_EU,
vatzone_number_world: process.env.ECONOMIC_VATZONE_NUMBER_WORLD,
recipient_name: process.env.ECONOMIC_RECIPIENT_NAME,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Try creating an order using the storefront or the [Store APIs](https://docs.medusajs.com/api/store#tag/Cart). Once the order is placed, a draft invoice will be created in e-conomic.

54
packages/medusa-plugin-ip-lookup/README.md Normal file
View File

@@ -0,0 +1,54 @@
# ipstack (IP Lookup)
Automatically detect the region and location of your customer using ipstack.
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Look up the location of your customer using ipstack.
- Provides a middleware that can be added to any request to set the region and country of a cart.
- Provides a service that can be used across codebase to detect the location of a user using their IP.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [ipstack account](https://ipstack.com)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-ip-lookup
```
2\. Set the following environment variable in `.env`:
```bash
IPSTACK_ACCESS_KEY=<YOUR_ACCESS_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// other plugins...
{
resolve: `medusa-plugin-ip-lookup`,
options: {
access_token: process.env.IPSTACK_ACCESS_KEY,
},
},
]
```
---
## Test the Plugin
You can use the `IpLookupService` service to look up the location of an IP, or use the middleware `preCartCreation` on any route.

81
packages/medusa-plugin-mailchimp/README.md
View File

@@ -1,29 +1,68 @@
# medusa-plugin-mailchimp
# Mailchimp
Mailchimp plugin for Medusa that supports newsletter subscriptions.
Manage newsletter subscriptions in your commerce application with Mailchimp.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/mailchimp).
[Mailchimp Plugin Documentation](https://docs.medusajs.com/plugins/notifications/mailchimp) | [Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
api_key: "MAILCHIMP_API_KEY",
newsletter_list_id: ["123456789"]
}
```
- Allow customers to subscribe to your newsletter.
- Provides custom services and endpoints to give developers flexibility in how to implement newsletter subscription.
## Dynamic usage
---
You can resolve the Mailchimp service, such that your server can handle newsletter subscriptions.
## Prerequisites
Example:
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Mailchimp account](https://mailchimp.com/signup)
```js
const mailchimpService = req.scope.resolve("mailchimpService")
mailchimpService.subscribeNewsletter(
"acme@mail.com",
// merge_fields to include in the subscription
{ FIRSTNAME: "Acme", LASTNAME: "Inc." }
)
```
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-mailchimp
```
2\. Set the following environment variables in `.env`:
```bash
MAILCHIMP_API_KEY=<YOUR_API_KEY>
MAILCHIMP_NEWSLETTER_LIST_ID=<YOUR_NEWSLETTER_LIST_ID>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...,
{
resolve: `medusa-plugin-mailchimp`,
options: {
api_key: process.env.MAILCHIMP_API_KEY,
newsletter_list_id:
process.env.MAILCHIMP_NEWSLETTER_LIST_ID,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Use the `/mailchimp/subscribe` endpoint or the `MailchimpService` to subscribe to the newsletter.
---
## Additional Resources
- [Mailchimp Plugin Documentation](https://docs.medusajs.com/plugins/notifications/mailchimp)

106
packages/medusa-plugin-meilisearch/README.md
View File

@@ -1,23 +1,91 @@
# medusa-plugin-meilisearch
# MeiliSearch
Meilisearch Plugin for Medusa to search for products.
Provide powerful indexing and searching features in your commerce application with MeiliSearch.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/meilisearch).
[MeiliSearch Plugin Documentation](https://docs.medusajs.com/plugins/search/meilisearch) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
config: {
host: "[your meilisearch host]",
},
settings: {
"[indexName]": "[meilisearch settings passed to meilisearch's `updateSettings()` method]"
// example
products: {
searchableAttributes: ["title", "description", "variant_sku"],
displayedAttributes: ["title", "description", "variant_sku", "thumbnail", "handle"],
}
}
}
```
- Flexible configurations for specifying searchable and retrievable attributes.
- Ready-integration with [Medusa's Next.js starter storefront](https://docs.medusajs.com/starters/nextjs-medusa-starter).
- Utilize MeiliSearch's powerful search functionalities including typo-tolerance, synonyms, filtering, and more.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [MeiliSearch instance](https://docs.meilisearch.com/learn/getting_started/quick_start.html#setup-and-installation)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-meilisearch
```
2\. Set the following environment variables in `.env`:
```bash
MEILISEARCH_HOST=<YOUR_MEILISEARCH_HOST>
MEILISEARCH_API_KEY=<YOUR_MASTER_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-plugin-meilisearch`,
options: {
// config object passed when creating an instance
// of the MeiliSearch client
config: {
host: process.env.MEILISEARCH_HOST,
apiKey: process.env.MEILISEARCH_API_KEY,
},
settings: {
// index name
products: {
// MeiliSearch's setting options
// to be set on a particular index
searchableAttributes: [
"title",
"description",
"variant_sku",
],
displayedAttributes: [
"title",
"description",
"variant_sku",
"thumbnail",
"handle",
],
},
},
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Try searching products either using your storefront or using the [Store APIs](https://docs.medusajs.com/api/store#tag/Product/operation/PostProductsSearch).
---
## Additional Resources
- [MeiliSearch Plugin Documentation](https://docs.medusajs.com/plugins/search/meilisearch)

129
packages/medusa-plugin-restock-notification/README.md
View File

@@ -1,89 +1,98 @@
# medusa-plugin-restock-notification
# Restock Notifications
Send notifications to subscribed customers when an item has been restocked.
## Usage
[Medusa Website](https://medusajs.com/) | [Medusa Repository](https://github.com/medusajs/medusa)
Install the plugin:
## Features
`$ yarn add medusa-plugin-restock-notification`
- Triggers an event when a product variant has been restocked.
- Provides an endpoint to subscribe customers to receive restock notifications.
- Does not implement the email or notification sending mechanisms. Instead, it is compatible with Notification plugins such as [SendGrid](https://docs.medusajs.com/plugins/notifications/sendgrid).
```js
// medusa-config.js
---
module.exports = {
...,
plugins: [
...,
`medusa-plugin-restock-notification`
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Redis](https://docs.medusajs.com/development/backend/prepare-environment#redis)
- [PostgreSQL](https://docs.medusajs.com/development/backend/prepare-environment#postgresql)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-restock-notification
```
2\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// other plugins...
{
resolve: `medusa-plugin-restock-notification`,
options: {
trigger_delay, // optional, delay time in milliseconds
inventory_required, // minimum inventory quantity to consider a variant as restocked
},
},
]
}
```
```
The plugin will migrate your database to include the RestockNotification entity, which consists of a variant id of a sold out item and a jsonb list of arrays that wish to be notified about restocks for the item.
3\. Run the following command in the directory of the Medusa backend to run the plugin's migrations:
```bash
medusa migrations run
```
## API endpoint
---
The plugin exposes an endpoint to sign emails up for restock notifications:
## Test the Plugin
```
POST /restock-notifications/variants/:variant_id
1\. Run the following command in the directory of the Medusa backend to run the backend:
Body
```bash
npm run start
```
2\. Subscribe an email or identification username (depends on your notification service) to receive restock notifications using the endpoint `/restock-notifications/variants/<variant_id>`. `<variant_id>` is the ID of the variant you're subscribing to.
2\. Change the inventory quantity of a product variant based on the restock threshold you've set, and see the event `restock-notification.restocked` triggered.
---
## Additional Information
### API endpoint
The plugin exposes an endpoint `/restock-notifications/variants/:variant_id` to sign emails up for restock notifications. It accepts the following request body:
```json
{
"email": "seb@test.com"
"email": "customer@test.com"
}
```
The endpoint responds with `200 OK` on successful signups. If a signup for an already in stock item is attempted the endpoint will have a 400 response code.
## Restock events
### Restock events
The plugin listens for the `product-variant.updated` call and emits a `restock-notification.restocked` event when a variant with restock signups become available.
The data sent with the `restock-notification.restocked` event is:
```
variant_id: The id of the variant to listen for restock events for.
emails: An array of emails that are to be notified of restocks.
The data sent with the `restock-notification.restocked` event are:
e.g.
- `variant_id`: The ID of the variant to listen for restock events for.
- `emails`: An array of emails that are to be notified of restocks.
For example:
```json
{
"variant_id": "variant_1234567890",
"emails": ["seb@test.com", "oli@test.com"]
}
```
*Note: This plugin does not send any communication to the customer, communication logic must be implemented or provided through a communication plugin.*
You may use `medusa-plugin-sendgrid` to orchestrate transactional emails.
## Usage with medusa-plugin-sendgrid
Install the plugins:
`$ yarn add medusa-plugin-restock-notification medusa-plugin-sendgrid`
```js
// medusa-config.js
module.exports = {
...,
plugins: [
...,
`medusa-plugin-restock-notification`,
{
resolve: `medusa-plugin-sendgrid`,
options: {
from: SENDGRID_FROM,
api_key: SENDGRID_API_KEY,
medusa_restock_template: `d-13141234123412342314`
}
}
]
}
```
You should set up a dynamic template in SendGrid which will be send for each of the emails in the restock notification.

15
packages/medusa-plugin-segment/READMD.md
View File

@@ -1,15 +0,0 @@
# medusa-plugin-segment
Segment Plugin to add tracking to your Medusa server.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/segment).
## Options
```js
{
write_key: "<YOUR_SEGMENT_WRITE_KEY>"
}
```
Where `<YOUR_SEGMENT_WRITE_KEY>` is the write key of the Segment Source you create for the Medusa server.

65
packages/medusa-plugin-segment/README.md Normal file
View File

@@ -0,0 +1,65 @@
# Segment
Track essential commerce analytics with Segment.
[Segment Plugin Documentation](https://docs.medusajs.com/plugins/analytics/segment) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Automatic analytics tracking for events related to Orders, Swaps, and Claims.
- Flexibility to track analytics for custom events or operations.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Segment account](https://app.segment.com/signup)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-segment
```
2\. Set the following environment variable in `.env`:
```bash
SEGMENT_WRITE_KEY=<YOUR_SEGMENT_WRITE_KEY>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-plugin-segment`,
options: {
write_key: process.env.SEGMENT_WRITE_KEY,
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should see the event tracked in Segment.
---
## Additional Resources
- [Segment Plugin Documentation](https://docs.medusajs.com/plugins/analytics/segment)

103
packages/medusa-plugin-sendgrid/README.md
View File

@@ -1,47 +1,78 @@
# medusa-plugin-sendgrid
# SendGrid
Sendgrid Plugin for Medusa to send transactional emails.
Handle sending emails to customers related to orders, restock notifications, users, or custom events.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/sendgrid).
[SendGrid Plugin Documentation](https://docs.medusajs.com/plugins/notifications/sendgrid) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
If no values are defined for a given option, the plugin will not try to send an email for that event.
- Send emails when an event related to orders, restock notifications, or users is triggered.
- Use dynamic templates in SendGrid to build the emails to be sent.
- Send emails with SendGrid for custom events.
```js
{
api_key: "SENDGRID_API_KEY", //required
from: "[the from field, i.e. ACME <acme@mail.com>]", //required
gift_card_created_template: "[used on gift_card.created]",
order_placed_template: "[used on order.placed]",
order_canceled_template: "[used on order.canceled]",
order_shipped_template: "[used on order.shipment_created]",
order_completed_template: "[used on order.completed]",
user_password_reset_template: "[used on user.password_reset]",
customer_password_reset_template: "[used on customer.password_reset]",
localization: {
"de-DE": { // locale key
gift_card_created_template: "[used on gift_card.created]",
order_placed_template: "[used on order.placed]",
order_canceled_template: "[used on order.canceled]",
order_shipped_template: "[used on order.shipment_created]",
order_completed_template: "[used on order.completed]",
user_password_reset_template: "[used on user.password_reset]",
customer_password_reset_template: "[used on customer.password_reset]",
}
}
}
```
---
## Dynamic usage
## Prerequisites
You can resolve the SendGrid service to dynamically send emails via sendgrid.
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [SendGrid account](https://signup.sendgrid.com/)
Example:
---
```js
## How to Install
const sendgridService = scope.resolve("sendgridService")
sendgridService.sendEmail("d-123....", "ACME <acme@mail.com>", "customer@mail.com", { dynamic: "data" })
1\. Run the following command in the directory of the Medusa backend:
```
```bash
npm install medusa-plugin-sendgrid
```
2\. Set the following environment variable in `.env`:
```bash
SENDGRID_API_KEY=<API_KEY>
SENDGRID_FROM=<SEND_FROM_EMAIL>
# IDs for different email templates
SENDGRID_ORDER_PLACED_ID=<ORDER_PLACED_TEMPLATE_ID> # example
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...,
{
resolve: `medusa-plugin-sendgrid`,
options: {
api_key: process.env.SENDGRID_API_KEY,
from: process.env.SENDGRID_FROM,
order_placed_template:
process.env.SENDGRID_ORDER_PLACED_ID,
localization: {
"de-DE": { // locale key
order_placed_template:
process.env.SENDGRID_ORDER_PLACED_ID_LOCALIZED,
},
},
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should receive a confirmation email.
---
## Additional Resources
- [SendGrid Plugin Documentation](https://docs.medusajs.com/plugins/notifications/sendgrid)

75
packages/medusa-plugin-slack-notification/README.md
View File

@@ -1,15 +1,68 @@
# medusa-plugin-slack-notification
# Slack
Slack Integration to receive new order notifications on Slack.
Receive new order notifications on Slack.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/slack).
[Slack Plugin Documentation](https://docs.medusajs.com/plugins/notifications/slack) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
show_discount_code: false,
slack_url: `<WEBHOOK_URL>`,
admin_orders_url: `http://localhost:7001/a/orders`
}
```
- Receive details about new orders including purchased items, totals, customer information, and more.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Slack account](https://slack.com)
- [Redis](https://docs.medusajs.com/development/backend/prepare-environment#redis)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-slack-notification
```
2\. Set the following environment variable in `.env`:
```bash
SLACK_WEBHOOK_URL=<YOUR_SLACK_WEBHOOK_URL>
SLACK_ADMIN_ORDERS_URL=<YOUR_ADMIN_ORDERS_URL>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...,
{
resolve: `medusa-plugin-slack-notification`,
options: {
show_discount_code: false, // optional, whether the discount code should be shown in notifications
slack_url: process.env.SLACK_WEBHOOK_URL,
admin_orders_url: process.env.SLACK_ADMIN_ORDERS_URL, // for example, http://localhost:7001/a/orders
},
},
]
```
---
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should receive a notification on your Slack workspace.
---
## Additional Resources
- [Slack Plugin Documentation](https://docs.medusajs.com/plugins/notifications/slack)

72
packages/medusa-plugin-twilio-sms/README.md
View File

@@ -1,26 +1,62 @@
# medusa-plugin-twilio-sms
# Twilio SMS
Twilio SMS / Messaging plugin.
Utilize Twilio's SMS APIs to send customers SMS notifications.
Learn more about how you can use this plugin in the [documentaion](https://docs.medusajs.com/add-plugins/twilio-sms).
[Twilio SMS Plugin Documentation](https://docs.medusajs.com/plugins/notifications/twilio-sms) | [Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Options
## Features
```js
{
account_sid: "[twilio messaging account sid]", // required
auth_token: "[twilio massaging authentication token]", // required
from_number: "[the number used as sender SMS]",
}
```
- Access Twilio's SMS APIs easily using the `TwilioSmsService`.
## Dynamic usage
---
You can resolve the Twilio SMS service to dynamically send SMS's via Twilio.
## Prerequisites
Example:
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Twilio account](https://www.twilio.com/sms)
```js
const twilioSmsService = scope.resolve("twilioSmsService")
twilioSmsService.sendSms({ to: "+4500112233", body: "Hello world!" })
```
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-twilio-sms
```
2\. Set the following environment variable in `.env`:
```bash
TWILIO_SMS_ACCOUNT_SID=<YOUR_ACCOUNT_SID>
TWILIO_SMS_AUTH_TOKEN=<YOUR_AUTH_TOKEN>
TWILIO_SMS_FROM_NUMBER=<YOUR_TWILIO_NUMBER>
```
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
{
resolve: `medusa-plugin-twilio-sms`,
options: {
account_sid: process.env.TWILIO_SMS_ACCOUNT_SID,
auth_token: process.env.TWILIO_SMS_AUTH_TOKEN,
from_number: process.env.TWILIO_SMS_FROM_NUMBER,
},
},
]
```
---
## Test the Plugin
In your code, use the `TwilioSmsService` where necessary to send your customers notifications.
---
## Additional Resources
- [Twilio SMS Plugin Documentation](https://docs.medusajs.com/plugins/notifications/twilio-sms)

46
packages/medusa-plugin-wishlist/README.md Normal file
View File

@@ -0,0 +1,46 @@
# Wishlist
Add wishlist capabilities to your commerce application.
[Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
## Features
- Allow customers to manage items in their wishlist.
---
## Prerequisites
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
---
## How to Install
1\. Run the following command in the directory of the Medusa backend:
```bash
npm install medusa-plugin-wishlist
```
2\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
const plugins = [
// ...
`medusa-plugin-wishlist`
]
```
---
## 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.

106
packages/medusa-source-shopify/README.md
View File

@@ -1,85 +1,61 @@
# Medusa Source Shopify
Plugin that allows users to source Medusa using a Shopify store.
# Shopify Source
## Quick start
Migrate your products and categories from Shopify to Medusa.
This plugin will copy all of your products and collections from Shopify to Medusa.
[Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)
To get started with the plugin you should follow these steps.
## Features
### Install the plugin
- Migrate data related to products from Shopify to Medusa.
- Consistently keep data in sync between Shopify and Medusa.
Navigate to your Medusa server in your terminal, and install the plugin.
---
```zsh
$ cd my-medusa-server
$ yarn medusa-source-shopify
```
## Prerequisites
### Create a Shopify app
- [Medusa backend](https://docs.medusajs.com/development/backend/install)
- [Shopify account](https://shopify.dev/)
Navigate to your Shopify dashboard, and then go to `Apps` and click the `Develop apps for your store` button at the bottom of the page. After navigating to the `App development` page, click the `Create an app` in the top right corner.
---
This should open a modal where you can choose a name for your app. Write a name and click `Create app`.
## How to Install
You should then click the button that says `Configure Admin API scopes`. Scroll down to `Products` and select the `read_products` scope, and then save your changes.
1\. Run the following command in the directory of the Medusa backend:
Go back to overview and click `Install app`. This should generate a token, that you should write down as you can only view it once.
```bash
npm install medusa-source-shopify
```
2\. Set the following environment variable in `.env`:
### Add the required plugin options
```bash
SHOPIFY_DOMAIN=<YOUR_SHOPIFY_DOMAIN>
SHOPIFY_PASSWORD=<YOUR_SHOPIFY_PASSWORD>
```
Update your `medusa-config.js` with the following:
3\. In `medusa-config.js` add the following at the end of the `plugins` array:
```js
//Shopify keys
const SHOPIFY_STORE_URL = process.env.SHOPIFY_STORE_URL || "";
const SHOPIFY_API_KEY = process.env.SHOPIFY_API_KEY || "";
```js
const plugins = [
// ...,
{
resolve: 'medusa-source-shopify',
options: {
domain: process.env.SHOPIFY_DOMAIN,
password: process.env.SHOPIFY_PASSWORD
}
}
];
```
const plugins = [
// other plugins...
{
resolve: `medusa-source-shopify`,
options: {
domain: SHOPIFY_STORE_URL,
password: SHOPIFY_API_KEY,
},
},
];
```
---
You should then add `SHOPIFY_STORE_URL` and `SHOPIFY_API_KEY` to your `.env`.
```env
SHOPIFY_API_KEY=<your_secret_shopify_key>
SHOPIFY_STORE_URL=<your_store_name>
```
The `SHOPIFY_API_KEY` is the token that we generated in the previous step. `SHOPIFY_STORE_URL` is the name of your store. You can view the name in the url of your Shopify dashboard, which has the following format `<your_store_name>.myshopify.com`.
### Run your server
After setting everything up you can now run your server
```zsh
$ yarn start
```
and the plugin will handle the rest.
## Note
### The plugin only queries updates since last build time
The plugin stores everytime it is run, and will use this timestamp to only fetch products, collections and collects that have been updated in Shopify since the last time it pulled data.
### `Product/Collection` relations (`Collect`)
Shopify supports products being part of more than one collection, but Medusa does not support this. For this reason a product will only be part of the first collection it has a relation to in Medusa. The plugin processes Shopify product/collection relations in the following order:
1. Custom collections
2. Smart collections
This means that if product `X` is part of custom collection `Y` and smart collection `Z` in Shopify, it will only be added to custom collection `X` in Medusa.
## Test the Plugin
1\. Run the following command in the directory of the Medusa backend to run the backend:
```bash
npm run start
```
2\. The data migration runs on server start-up. You should see your Shopify products in Medusa.