+
+// ...
```
If you run your Gatsby storefront while the Medusa server is running, you should find a search bar in the header of the page. Try entering a query to search through the products in your store.
-## What’s Next
+---
-- Learn how to [deploy your Medusa server](../deployments/server/index.mdx).
-- Learn how to [deploy your Gatsby storefront](../deployments/storefront/deploying-gatsby-on-netlify.md).
+## See Also
+
+- [Deploy your Medusa server](../deployments/server/index.mdx)
+- [Deploy your Gatsby storefront](../deployments/storefront/deploying-gatsby-on-netlify.md)
diff --git a/docs/content/add-plugins/contentful/customize-contentful.md b/docs/content/add-plugins/contentful/customize-contentful.md
index 75989cb0de..cfcbad213b 100644
--- a/docs/content/add-plugins/contentful/customize-contentful.md
+++ b/docs/content/add-plugins/contentful/customize-contentful.md
@@ -12,10 +12,14 @@ On your storefront, you can add any necessary components that can render the Con
As an example to explain this process, in this documentation, you’ll create a migration that creates a Rich Text content model in Contentful and edits the Page and Product content models to allow using Rich Text content as a tile in pages and products. Then, you’ll modify the Gatsby storefront to render the Rich Text content model.
+---
+
## Prerequisites
It’s assumed you already have set up a Medusa server integrated with Contentful and have a Gatsby storefront integrated with Contentful. If not, [please follow this documentation first](index.md).
+---
+
## Create a Contentful Migration
The Contentful migrations are located in the `contentful-migrations` directory in the Medusa Contentful server starter. So, if you want to create your own Contentful migrations, you can create them under that directory.
@@ -25,32 +29,32 @@ Here’s an example of a migration created in a new file `contentful-migrations/
```jsx title=contentful-migrations/rich-text.js
#! /usr/bin/env node
-require("dotenv").config();
+require("dotenv").config()
-const { runMigration } = require("contentful-migration");
+const { runMigration } = require("contentful-migration")
const options = {
spaceId: process.env.CONTENTFUL_SPACE_ID,
accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
environment: process.env.CONTENTFUL_ENVIRONMENT,
yes: true,
-};
+}
const migration = async () => {
await runMigration({
...options,
migrationFunction: function (migration, context) {
- //create Rich Text content model
+ // create Rich Text content model
const richText = migration
.createContentType("richText")
.name("Rich Text")
- .displayField("title");
+ .displayField("title")
- richText.createField("title").name("Title (Internal)").type("Symbol");
- richText.createField("body").name("Body").type("RichText");
+ richText.createField("title").name("Title (Internal)").type("Symbol")
+ richText.createField("body").name("Body").type("RichText")
- //edit Page content model
+ // edit Page content model
const page = migration.editContentType("page")
page.editField("contentModules").items({
@@ -63,7 +67,7 @@ const migration = async () => {
],
})
- //edit Product content model
+ // edit Product content model
const product = migration.editContentType("product")
product
@@ -79,11 +83,11 @@ const migration = async () => {
},
],
})
- }
- });
+ },
+ })
}
-migration();
+migration()
```
This example creates a new content model Rich Text that has two fields: title and body. It also edits the Page content model to allow using Rich Text content models on the page.
@@ -93,7 +97,19 @@ In addition, it edits the Product content model by adding a new field `contentMo
You can also add other types of content models the `contentModules` should accept. For example, to accept `tileSection` add it to the `linkContentType` option:
```jsx
-linkContentType: ["tileSection", "richText"],
+product
+ .createField("contentModules")
+ .name("Content Modules")
+ .type("Array")
+ .items({
+ type: "Link",
+ linkType: "Entry",
+ validations: [
+ {
+ linkContentType: ["richText", "tileSection"],
+ },
+ ],
+ })
```
### Run a Contentful Migration
@@ -144,6 +160,8 @@ Similarly, you can add Rich Text content to any product page.
+---
+
## Render New Content Models in the Storefront
After creating a new content model in your Contentful Space, you must add the necessary component to render it in your Gatsby storefront.
@@ -159,10 +177,10 @@ import { renderRichText } from "gatsby-source-contentful/rich-text"
const RichText = ({ data }) => {
return (
{data.body ? renderRichText(data.body) : ""}
@@ -188,7 +206,7 @@ Then, in the returned JSX add a new case to the switch statement:
```jsx title=src/pages/{ContentfulPage.slug}.js
switch (cm.internal.type) {
- //...
+ // ...
case "ContentfulRichText":
return
- {children}
-
- ) : (
-
- )
- );
+ const Results = connectStateResults(
+ ({ searchState, searchResults, children }) => {
+ return (
+ searchState && searchState.query &&
+ searchResults && searchResults.nbHits !== 0 ?
+ (
+
+ {children}
+
+ ) : (
+
+ )
+ )
+ }
+ )
return (
-
+
` is the URL of your MinIO server, `` is the name of th
Finally, configure your `medusa-config.js` to include the plugin with the required options:
```js title=medusa-config.js
-{
+const plugins = [
+ // ...
+ {
resolve: `medusa-file-minio`,
options: {
endpoint: process.env.MINIO_ENDPOINT,
@@ -106,7 +114,8 @@ Finally, configure your `medusa-config.js` to include the plugin with the requ
access_key_id: process.env.MINIO_ACCESS_KEY,
secret_access_key: process.env.MINIO_SECRET_KEY,
},
-},
+ },
+]
```
:::caution
@@ -115,12 +124,16 @@ If you have multiple storage plugins configured, the last plugin declared in the
:::
+---
+
## Test it Out
-Run your Medusa server alongside the [Medusa Admin](../admin/quickstart.md) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in a MinIO server.
+Run your Medusa server 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 in a MinIO server.
+---
+
## Private Buckets
### Handle Exports
@@ -146,13 +159,16 @@ MINIO_PRIVATE_BUCKET=exports
Then, add a new option to the plugin’s options in `medusa-config.js`:
```jsx title=medusa-config.js
-{
+const plugins = [
+ // ...
+ {
resolve: `medusa-file-minio`,
options: {
- //...
- private_bucket: process.env.MINIO_PRIVATE_BUCKET
+ // ...
+ private_bucket: process.env.MINIO_PRIVATE_BUCKET,
},
-},
+ },
+]
```
### Use Different Secret and Access Keys
@@ -171,19 +187,24 @@ Where `` and `` are the access
Then, add two new options to the plugin’s options in `medusa-config.js`:
```jsx title=medusa-config.js
-{
+const plugins = [
+ // ...
+ {
resolve: `medusa-file-minio`,
options: {
- //...
+ // ...
private_access_key_id: process.env.MINIO_PRIVATE_ACCESS_KEY,
- private_secret_access_key: process.env.MINIO_PRIVATE_SECRET_KEY
+ private_secret_access_key: process.env.MINIO_PRIVATE_SECRET_KEY,
},
-},
+ },
+]
```
+---
+
## Next.js Storefront Configuration
-If you’re using a [Next.js](../starters/nextjs-medusa-starter.md) storefront, you need to add an additional configuration that adds the MinIO domain name into the configured images domain names. This is because all URLs of product images will be from the MinIO server.
+If you’re using a [Next.js](../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the MinIO domain name into the configured images domain names. This is because all URLs of product images will be from the MinIO server.
If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
@@ -192,13 +213,13 @@ In `next.config.js` add the following option in the exported object:
```jsx title=next.config.js
const { withStoreConfig } = require("./store-config")
-//...
+// ...
module.exports = withStoreConfig({
- //...
+ // ...
images: {
domains: [
- //...
+ // ...
"127.0.0.1",
],
},
@@ -207,6 +228,8 @@ module.exports = withStoreConfig({
Where `127.0.0.1` is the domain of your local MinIO server.
-## What’s Next
+---
+
+## See Also
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.
diff --git a/docs/content/add-plugins/paypal.md b/docs/content/add-plugins/paypal.md
index fe2d8a7705..3586825d6f 100644
--- a/docs/content/add-plugins/paypal.md
+++ b/docs/content/add-plugins/paypal.md
@@ -10,6 +10,8 @@ As a developer, you can use PayPal’s SDKs and APIs to integrate PayPal as a pa
Using the `medusa-payment-paypal` plugin, this guide shows you how to set up your Medusa server with PayPal as a payment provider.
+---
+
## Prerequisites
Before you proceed with this guide, make sure you create a [PayPal account](https://www.paypal.com). You also need a PayPal Developer account and retrieve the Client ID and Client Secret. You can learn more about how to do that in [PayPal’s documentation](https://developer.paypal.com/api/rest/).
@@ -20,7 +22,9 @@ Webhooks are used in scenarios where the customer might leave the page during th
Additionally, you need a Medusa server installed and set up. If not, you can follow the [quickstart guide](https://docs.medusajs.com/quickstart/quick-start) to get started.
-You also need [Medusa Admin](../admin/quickstart.md) installed to enable PayPal as a payment provider. You can alternatively use the [REST APIs](https://docs.medusajs.com/api/admin).
+You also need [Medusa Admin](../admin/quickstart.mdx) installed to enable PayPal as a payment provider. You can alternatively use the [REST APIs](https://docs.medusajs.com/api/admin).
+
+---
## Medusa Server
@@ -53,21 +57,23 @@ Then, in `medusa-config.js`, add the PayPal plugin to the `plugins` array with t
```jsx title=medusa-config.js
const plugins = [
- //other plugins...
+ // other 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
- }
- }
-];
+ auth_webhook_id: process.env.PAYPAL_AUTH_WEBHOOK_ID,
+ },
+ },
+]
```
That’s all you need to install PayPal on your Medusa server!
+---
+
## Admin Setup
This section will guide you through adding PayPal as a payment provider in a region using your Medusa admin dashboard.
@@ -76,12 +82,14 @@ This step is required for you to be able to use PayPal as a payment provider in
### Admin Prerequisites
-If you don’t have a Medusa admin installed, make sure to follow along with [the guide on how to install it](../admin/quickstart.md) before continuing with this section.
+If you don’t have a Medusa admin installed, make sure to follow along with [the guide on how to install it](../admin/quickstart.mdx) before continuing with this section.
### Add PayPal to Regions
You can refer to [this documentation in the user guide](../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like PayPal to a region.
+---
+
## Storefront Setup
This section will take you through the steps to add PayPal as a payment method on the storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront.
@@ -115,7 +123,7 @@ In Medusa, by default, payments are authorized during checkout, but the payment
### Add to Next.js Storefront
-Medusa has a Next.js storefront that you can easily use with your Medusa server. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/nextjs-medusa-starter.md).
+Medusa has a Next.js storefront that you can easily use with your Medusa server. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/nextjs-medusa-starter.mdx).
In your `.env.local` file (or the file you’re using for your environment variables), add the following variable:
@@ -133,7 +141,7 @@ You can test out the payment with PayPal using your sandbox account.
### Add to Gatsby Storefront
-Medusa also has a Gatsby storefront that you can use as your ecommerce storefront. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/gatsby-medusa-starter.md).
+Medusa also has a Gatsby storefront that you can use as your ecommerce storefront. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/gatsby-medusa-starter.mdx).
In your `.env.development` file (or the file you’re using for your environment variables) add the following variable with its value set to the Client ID:
@@ -150,12 +158,15 @@ npm install @paypal/react-paypal-js
Next, create a new file `src/components/payment/paypal-payment/index.jsx` with the following content:
```jsx title=src/components/payment/paypal-payment/index.jsx
-import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";
-import React, { useMemo, useState } from "react";
+import {
+ PayPalButtons,
+ PayPalScriptProvider,
+} from "@paypal/react-paypal-js"
+import React, { useMemo, useState } from "react"
import { navigate } from "gatsby"
import { useCart } from "../../../hooks/use-cart"
-import { useMedusa } from "../../../hooks/use-medusa";
+import { useMedusa } from "../../../hooks/use-medusa"
const paypalClientId = process.env.GATSBY_PAYPAL_CLIENT_ID || ""
@@ -171,7 +182,7 @@ const PaypalPayment = () => {
const paypalSession = useMemo(() => {
if (cart.payment_sessions) {
- return cart.payment_sessions.find(s => s.provider_id === "paypal")
+ return cart.payment_sessions.find((s) => s.provider_id === "paypal")
}
return null
@@ -192,10 +203,10 @@ const PaypalPayment = () => {
await client.carts.updatePaymentSession(cart.id, "paypal", {
data: {
data: {
- ...authorizationOrder
- }
- }
- });
+ ...authorizationOrder,
+ },
+ },
+ })
const order = await completeCart(cart.id)
@@ -210,10 +221,12 @@ const PaypalPayment = () => {
const handlePayment = (data, actions) => {
actions.order.authorize().then((authorization) => {
- if (authorization.status !== 'COMPLETED') {
- setErrorMessage(`An error occurred, status: ${authorization.status}`);
- setProcessing(false);
- return;
+ if (authorization.status !== "COMPLETED") {
+ setErrorMessage(
+ `An error occurred, status: ${authorization.status}`
+ )
+ setProcessing(false)
+ return
}
completeOrder(authorization)
@@ -224,7 +237,7 @@ const PaypalPayment = () => {
{errorMessage && (
{errorMessage}
@@ -238,7 +251,7 @@ const PaypalPayment = () => {
)
}
-export default PaypalPayment;
+export default PaypalPayment
```
Here’s briefly what this code snippet does:
@@ -256,9 +269,11 @@ In `src/components/payment/index.js` you’ll find in the return statement a swi
```jsx title=src/components/payment/index.js
switch (ps.provider_id) {
case "stripe":
- //...
+ // ...
+ break
case "manual":
- //...
+ // ...
+ break
case "paypal":
return
+
+// ...
```
If you run your Gatsby storefront while the Medusa server and the MeiliSearch instance are running, you should find a search bar in the header of the page. Try entering a query to search through the products in your store.
-## What’s Next
+---
-- Learn how to [deploy your Medusa server](../deployments/server/index.mdx).
-- Learn how to [deploy your Gatsby storefront](./../deployments/storefront/deploying-gatsby-on-netlify.md).
+## See Also
+
+- [Deploy your Medusa server](../deployments/server/index.mdx).
+- [Deploy your Gatsby storefront](./../deployments/storefront/deploying-gatsby-on-netlify.md).
diff --git a/docs/content/add-plugins/minio.md b/docs/content/add-plugins/minio.md
index e5d14db855..0a0ff531f6 100644
--- a/docs/content/add-plugins/minio.md
+++ b/docs/content/add-plugins/minio.md
@@ -8,9 +8,13 @@ To manage images in Medusa, you need a file service plugin responsible for hosti
Medusa provides three different options to handle your file storage. This document will focus on setting up [MinIO](https://min.io) on your local machine and connecting Medusa to it.
+---
+
## Prerequisites
-A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.md) to get started in minutes.
+A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.mdx) to get started in minutes.
+
+---
## Set up MinIO
@@ -76,6 +80,8 @@ You will not be able to access the Secret Key after closing the pop-up. So, make
:::
+---
+
## Plugin Installation
In the directory of your Medusa server, run the following command to install the MinIO plugin:
@@ -98,7 +104,9 @@ Where `
+ .s3.amazonaws.com"
+ // ...
+ ".s3.amazonaws.com",
],
},
})
@@ -201,8 +213,10 @@ module.exports = withStoreConfig({
Where `` is the name of the S3 bucket you’re using.
-## What’s Next
+---
+
+## See Also
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.
-- Learn how to [deploy the Medusa server](../deployments/server/index.mdx).
-- Learn about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
+- [Deploy the Medusa server](../deployments/server/index.mdx)
+- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts.
diff --git a/docs/content/add-plugins/segment.md b/docs/content/add-plugins/segment.md
index 54f80f4e39..ff4ed78ae6 100644
--- a/docs/content/add-plugins/segment.md
+++ b/docs/content/add-plugins/segment.md
@@ -36,11 +36,13 @@ Check out the [Event Reference](../advanced/backend/subscribers/events-list.md)
:::
+---
+
## Prerequisites
### Medusa Server
-It is assumed you already have a Medusa server installed. If not, please follow the [Quickstart guide](../quickstart/quick-start.md) to get started in minutes.
+It is assumed you already have a Medusa server installed. If not, please follow the [Quickstart guide](../quickstart/quick-start.mdx) to get started in minutes.
In addition, make sure to have Redis installed and configured with your Medusa server. If not, follow [this documentation](../tutorial/0-set-up-your-development-environment.mdx#redis) to install Redis and then [configure it](../usage/configurations.md#redis).
@@ -48,6 +50,8 @@ In addition, make sure to have Redis installed and configured with your Medusa s
You need to [create a Segment account](https://app.segment.com/signup/) to follow along with the tutorial. Segment offers a free plan to get started quickly.
+---
+
## Create a Segment Source
On your Segment dashboard, choose Catalog from the sidebar under Connections.
@@ -84,6 +88,8 @@ You can then choose from a list of destinations such as Google Universal Analyti
The process of integrating each destination is different, so you must follow the steps detailed in Segment for each destination you choose.
+---
+
## Install the Segment Plugin
In the directory of your Medusa server, run the following command to install the Segment plugin:
@@ -104,16 +110,18 @@ Finally, in `medusa-config.js`, add the following new item to the `plugins` arra
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-plugin-segment`,
options: {
write_key: process.env.SEGMENT_WRITE_KEY,
- }
- }
-];
+ },
+ },
+]
```
+---
+
## Test the Plugin
Run your server with the following command:
@@ -122,7 +130,7 @@ Run your server with the following command:
npm run start
```
-Then, try triggering one of the [mentioned events earlier in this document](#events-that-the-segment-plugin-tracks). For example, you can place an order either using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
+Then, try triggering one of the [mentioned events earlier in this document](#events-that-the-segment-plugin-tracks). For example, you can place an order either using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts.
After you place an order, on the Segment source that you created, click on the Debugger tab. You should see at least one event triggered for each order you place. If you click on the event, you can see the order details are passed to the event.
@@ -136,6 +144,8 @@ If the data is not appearing on the destination, the issue is related to your co
:::
+---
+
## Add Custom Tracking
In some cases, you might want to track more events or custom events. You can do that using the `SegmentService` provided by the Segment Plugin.
@@ -145,24 +155,24 @@ For example, you can add the following subscriber to listen to the `customer.cre
```jsx title=src/subscribers/customer.ts
class CustomerSubscriber {
constructor({ segmentService, eventBusService }) {
- this.segmentService = segmentService;
+ this.segmentService = segmentService
- eventBusService.subscribe("customer.created", this.handleCustomer);
+ eventBusService.subscribe("customer.created", this.handleCustomer)
}
handleCustomer = async (data) => {
- const customerData = data;
- delete customerData['password_hash'];
+ const customerData = data
+ delete customerData["password_hash"]
this.segmentService.track({
- event: 'Customer Created',
+ event: "Customer Created",
userId: data.id,
- properties: customerData
+ properties: customerData,
})
- };
+ }
}
-export default CustomerSubscriber;
+export default CustomerSubscriber
```
You resolve the `SegmentService` using dependency injection. Then, when the `customer.created` event is triggered, you use the `track` method available in the `SegmentService` to send tracking data to Segment.
@@ -185,8 +195,11 @@ After adding the above subscriber, run your server again if it isn’t running a
-## What’s Next
+---
-- Learn how [services](../advanced/backend/services/create-service.md) and [subscribers](../advanced/backend/subscribers/create-subscriber.md) work.
-- Check out a [full list of events](../advanced/backend/subscribers/events-list.md) in Medusa.
-- Learn how to [deploy the Medusa server](../deployments/server/index.mdx).
+## See Also
+
+- [Services Overview](../advanced/backend/services/create-service.md)
+- [Subscribers Overview](../advanced/backend/subscribers/create-subscriber.md)
+- [Events Reference](../advanced/backend/subscribers/events-list.md)
+- [Deploy the Medusa server](../deployments/server/index.mdx)
diff --git a/docs/content/add-plugins/sendgrid.mdx b/docs/content/add-plugins/sendgrid.mdx
index 7a18733685..2b985b0f7e 100644
--- a/docs/content/add-plugins/sendgrid.mdx
+++ b/docs/content/add-plugins/sendgrid.mdx
@@ -20,12 +20,16 @@ By integrating SendGrid with Medusa, you’ll be sending email notifications to
4. User-related events including reset passwords.
5. Restock Notifications for when product stocks are low.
+---
+
## Prerequisites
-Before going further with this guide make sure you have a Medusa server set up. You can follow the [Quickstart guide](../quickstart/quick-start.md).
+Before going further with this guide make sure you have a Medusa server set up. You can follow the [Quickstart guide](../quickstart/quick-start.mdx).
You also must have [Redis configured on your Medusa server](/tutorial/set-up-your-development-environment#redis). Sending emails is done through Subscribers, which uses Redis as the event queue. If you don’t set up Redis, the plugin will not send emails.
+---
+
## Create a SendGrid Account
If you don’t have a SendGrid account, make sure to [create one](https://signup.sendgrid.com) first. You also need to set up a [single sender](https://docs.sendgrid.com/ui/sending-email/sender-verification) first in SendGrid before you can start sending emails.
@@ -60,6 +64,8 @@ Medusa supports localization so you can also create multiple templates for multi
:::
+---
+
## Template Reference
This section covers the template types supported by the plugin and what variables you can expect in your dynamic template. You can use the variables to add details like order total or customer name.
@@ -3891,6 +3897,8 @@ You don’t have to create a template for every type in the reference. You can s
```
+---
+
## Install the SendGrid Plugin
In the directory of your Medusa server run the following command to install the SendGrid plugin:
@@ -3920,7 +3928,7 @@ Finally, in your `medusa-config.js` file, add the SendGrid plugin into the array
```jsx title=medusa-config.js
const plugins = [
- ...,
+ // ...,
{
resolve: `medusa-plugin-sendgrid`,
options: {
@@ -3929,18 +3937,21 @@ const plugins = [
order_placed_template: process.env.SENDGRID_ORDER_PLACED_ID,
localization: {
"de-DE": { // locale key
- order_placed_template: process.env.SENDGRID_ORDER_PLACED_ID_LOCALIZED,
- }
- }
- }
- }
-];
+ order_placed_template:
+ process.env.SENDGRID_ORDER_PLACED_ID_LOCALIZED,
+ },
+ },
+ },
+ },
+]
```
The `api_key` and `from` options are required. Then, use the key of each template you create (from the [reference](#template-reference)) as the option name with the template ID as the value.
You can also optionally pass the option `localization` if you want to support different languages. `localization` accepts an object that has the country and language codes as keys. The value for each code should be an object of template keys and their IDs as values. Make sure to include the localized template IDs in `.env` as well.
+---
+
## Test it Out
Run your server now:
@@ -3953,7 +3964,7 @@ To test it out, perform an action that would trigger one of the emails being sen
:::tip
-If you don’t have a storefront installed, check out the [Gatsby](../starters/gatsby-medusa-starter.md) or [Next.js](../starters/nextjs-medusa-starter.md) starters to create a storefront in minutes.
+If you don’t have a storefront installed, check out the [Gatsby](../starters/gatsby-medusa-starter.mdx) or [Next.js](../starters/nextjs-medusa-starter.mdx) starters to create a storefront in minutes.
:::
@@ -3961,7 +3972,9 @@ You can also track analytics related to emails sent from the SendGrid dashboard.
-## What’s Next
+---
-- Learn more about how [Notifications work in Medusa](../advanced/backend/notification/overview.md).
-- Install the [Medusa admin](https://github.com/medusajs/admin#-setting-up-admin) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more.
\ No newline at end of file
+## See Also
+
+- [Notifications Overview](../advanced/backend/notification/overview.md)
+- Install the [Medusa admin](../admin/quickstart.mdx) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more.
\ No newline at end of file
diff --git a/docs/content/add-plugins/slack.md b/docs/content/add-plugins/slack.md
index 2a000de26b..316d57926c 100644
--- a/docs/content/add-plugins/slack.md
+++ b/docs/content/add-plugins/slack.md
@@ -17,6 +17,8 @@ The plugin registers a subscriber to the `order.placed` event. When an order is
Then, the order notificaiton is sent to Slack using Webhooks. So, you'll need to create a Slack App, add it into your workspace, and activate Incoming Webhooks.
+---
+
## Prerequisites
### Slack Account
@@ -25,7 +27,7 @@ To follow along with this guide, you need to have a Slack account with a connect
### Medusa Server
-This tutorial assumes you already have a Medusa server installed. If you don’t, please follow along with the [quickstart guide](../quickstart/quick-start.md).
+This tutorial assumes you already have a Medusa server installed. If you don’t, please follow along with the [quickstart guide](../quickstart/quick-start.mdx).
### Redis
@@ -35,6 +37,8 @@ As the Slack plugin will listen to the `order.placed` event to know when to send
You can read the [Set up your development enviornment guideline](../tutorial/0-set-up-your-development-environment.mdx#redis) to learn more about how you can install and setup Redis.
+---
+
## Create Slack App
The first step is to create a Slack app. This app will be connected to your workspace and will have Incoming Webhooks activated to receive notifications from the Medusa server using a Webhook URL.
@@ -63,6 +67,8 @@ After that, choose the channel to send the notifications to. You can also choose
This will create a new Webhook with a URL which you can see in the table at the end of the Incoming Webhooks page. Copy the URL as you’ll use it in the next section.
+---
+
## Install Slack Plugin
The next step is to install Medusa’s [Slack plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-slack-notification) into your Medusa server.
@@ -77,16 +83,16 @@ After that, open `medusa-config.js` and add the new plugin with its configuratio
```jsx title=medusa-config.js
const plugins = [
- ...,
+ // ...,
{
resolve: `medusa-plugin-slack-notification`,
options: {
show_discount_code: false,
slack_url: ``,
- admin_orders_url: `http://localhost:7001/a/orders`
- }
- }
-];
+ admin_orders_url: `http://localhost:7001/a/orders`,
+ },
+ },
+]
```
- Make sure to change `` with the Webhook URL you copied after creating the Slack app.
@@ -95,7 +101,9 @@ const plugins = [
That’s all you need to do to integrate Slack into Medusa!
-## What's Next
+---
-- Install [Medusa's Admin](https://github.com/medusajs/admin) for the full order-management experience.
-- Add a Storefront to your Medusa server using [the Next.js starter](https://docs.medusajs.com/starters/nextjs-medusa-starter) or [the Gatsby starter](https://docs.medusajs.com/starters/gatsby-medusa-starter).
+## See Also
+
+- Install [Medusa's Admin](../admin/quickstart.mdx) for the full order-management experience.
+- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts.
diff --git a/docs/content/add-plugins/spaces.md b/docs/content/add-plugins/spaces.md
index a58e1de867..7f31d81587 100644
--- a/docs/content/add-plugins/spaces.md
+++ b/docs/content/add-plugins/spaces.md
@@ -14,16 +14,20 @@ To manage images in Medusa, you need a file service plugin responsible for hosti
Medusa provides three different options to handle your file storage. This document focuses on using [Spaces](https://www.digitalocean.com/products/spaces) to store your Medusa server’s images.
+---
+
## Prerequisites
### Medusa Server
-A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.md) to get started in minutes.
+A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.mdx) to get started in minutes.
### Required Accounts
You need to [create a DigitalOcean account](https://cloud.digitalocean.com/registrations/new) to follow along with this documentation. A credit card is required during registration.
+---
+
## Create DigitalOcean Space
In your DigitalOcean account, click on the Create button at the top right, then choose Spaces from the dropdown.
@@ -40,6 +44,8 @@ In the Finalize and Create section, enter a name for the field “Choose a uniqu
Once you’re done, click on the Create a Space button. This creates the Space and redirects you to the Space’s page.
+---
+
## Create Space Access Keys
Choose API from the bottom of the sidebar.
@@ -62,6 +68,8 @@ The secret access key will not be shown again after you leave the page. Make sur
:::
+---
+
## Install the Spaces Plugin
In the directory of your Medusa server, run the following command to install the Spaces plugin:
@@ -97,7 +105,7 @@ Finally, in `medusa-config.js` add a new item to the `plugins` array:
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-file-spaces`,
options: {
@@ -108,7 +116,7 @@ const plugins = [
secret_access_key: process.env.SPACE_SECRET_ACCESS_KEY,
},
},
-];
+]
```
:::caution
@@ -117,6 +125,8 @@ If you have multiple storage plugins configured, the last plugin declared in the
:::
+---
+
## Test the Space Plugin
Run your Medusa server with the following command:
@@ -125,7 +135,7 @@ Run your Medusa server with the following command:
npm run start
```
-Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.md).
+Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.mdx).
On the Medusa Admin, create a new product and, in the Images section, upload an image then click Save. If the integration was successful, the product image will be uploaded successfully.
@@ -135,9 +145,11 @@ You can also check that the image was uploaded on the Space’s page.
+---
+
## Next.js Storefront Configuration
-If you’re using a [Next.js](../starters/nextjs-medusa-starter.md) storefront, you need to add an additional configuration that adds the Space’s domain name into the configured images’ domain names. This is because all URLs of product images will be from the Space.
+If you’re using a [Next.js](../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the Space’s domain name into the configured images’ domain names. This is because all URLs of product images will be from the Space.
If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
@@ -146,14 +158,14 @@ In `next.config.js` add the following option in the exported object:
```jsx title=next.config.js
const { withStoreConfig } = require("./store-config")
-//...
+// ...
module.exports = withStoreConfig({
- //...
+ // ...
images: {
domains: [
- //...
- ""
+ // ...
+ "",
],
},
})
@@ -161,8 +173,10 @@ module.exports = withStoreConfig({
Where `` is the domain name for your Space which can be retrieved from the Space URL. For example, `medusa-server.fra1.digitaloceanspaces.com`.
-## What’s Next
+---
+
+## See Also
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.
-- Learn how to [deploy the Medusa server on DigitalOcean](../deployments/server/deploying-on-digital-ocean.md).
-- Learn about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
+- [Seploy the Medusa server on DigitalOcean](../deployments/server/deploying-on-digital-ocean.md).
+- Install the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefront.
diff --git a/docs/content/add-plugins/strapi.md b/docs/content/add-plugins/strapi.md
index 082f96ea9a..b957616476 100644
--- a/docs/content/add-plugins/strapi.md
+++ b/docs/content/add-plugins/strapi.md
@@ -14,6 +14,8 @@ This plugin is a [community plugin](https://github.com/Deathwish98/medusa-plugin
By integrating Strapi to Medusa, you can benefit from powerful features in your ecommerce store including detailed product CMS details, [two-way sync](#test-two-way-sync), an easy-to-use interface to use for static content and pages, and much more.
+---
+
## Prerequisites
### Medusa CLI
@@ -24,6 +26,8 @@ By integrating Strapi to Medusa, you can benefit from powerful features in your
Redis is required for the Strapi plugin to work as expected on your Medusa server. If you don’t have it installed, you can learn [how to install it in this documentation](../tutorial/0-set-up-your-development-environment.mdx#redis).
+---
+
## Create Strapi Project
The first step is to create a Strapi project using the Medusa template:
@@ -52,6 +56,8 @@ Click on the Create new entry button at the top right. This opens a new form to
Enter the user’s username, email, and password. Once you’re done, click on the Save button at the top right.
+---
+
## Modify Permissions
By default, created users have the “Authenticated” role. Before you start using the Strapi plugin on your Medusa server, you must modify this role’s permissions to allow making changes to Medusa’s models in Strapi.
@@ -62,6 +68,8 @@ On your Strapi dashboard, go to Settings → Roles → Authenticated. Then, unde
Once you’re done, click the Save button at the top right.
+---
+
## Create Medusa Server
:::note
@@ -86,10 +94,10 @@ Once the command is done executing, change to the newly created `medusa-server`
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
- //...
- }
- //...
-};
+ // ...
+ },
+ // ...
+}
```
This uses the default Redis configurations. If you want to learn more about configuring Redis, [check out this documentation](../usage/configurations.md#redis).
@@ -100,6 +108,8 @@ It is also recommended to use PostgreSQL for an optimal experience, however, it
:::
+---
+
## Install the Strapi Plugin
In the directory of your Medusa server, run the following command to install the Strapi plugin:
@@ -130,20 +140,22 @@ Finally, open `medusa-config.js` and add the following new item to the `plugins`
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-plugin-strapi`,
options: {
strapi_medusa_user: process.env.STRAPI_USER,
strapi_medusa_password: process.env.STRAPI_PASSWORD,
- strapi_url: process.env.STRAPI_URL, //optional
- strapi_port: process.env.STRAPI_PORT, //optional
- strapi_protocol: process.env.STRAPI_PROTOCOL //optional
- }
- }
-];
+ strapi_url: process.env.STRAPI_URL, // optional
+ strapi_port: process.env.STRAPI_PORT, // optional
+ strapi_protocol: process.env.STRAPI_PROTOCOL, // optional
+ },
+ },
+]
```
+---
+
## Run Medusa Server
Make sure the Strapi server is still running. If not, you can run the following command to run the Strapi server in the directory of the Strapi project:
@@ -160,6 +172,8 @@ npm run start
Once you start your Medusa server, if you ran the `--seed` command when you created your Medusa server, you’ll see that `product.created` events have been triggered along with similar events. This will update Strapi with the products you seeded.
+---
+
## Test Two-Way Sync
This plugin ensures a two-way sync between the Medusa server and the Strapi server. So, if you update data on Strapi, it will be reflected on your Medusa server, and vice-versa.
@@ -172,7 +186,9 @@ Try updating any products on Strapi by going to Content Manager → Products and
If you try to update products on Medusa either using the [REST APIs](https://docs.medusajs.com/api/admin/#tag/Product/operation/PostProductsProduct) or using [the Medusa Admin](../user-guide/products/manage.mdx), you’ll see that the product is also updated on Strapi.
-## What’s Next
+---
-- Learn [how to deploy the Medusa server](../deployments/server/index.mdx).
-- Learn [how to create your own plugin](../advanced/backend/plugins/create.md).
+## See Also
+
+- [Deploy the Medusa server](../deployments/server/index.mdx)
+- [Create your own plugin](../advanced/backend/plugins/create.md)
diff --git a/docs/content/add-plugins/stripe.md b/docs/content/add-plugins/stripe.md
index 450ddd05ba..d657377050 100644
--- a/docs/content/add-plugins/stripe.md
+++ b/docs/content/add-plugins/stripe.md
@@ -18,10 +18,14 @@ You can also follow this video guide to learn how the setup works:
Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment provider.
+---
+
## Prerequisites
Before you proceed with this guide, make sure you create a [Stripe account](https://stripe.com). You’ll later retrieve the API Keys and secrets from your account to connect Medusa to your Stripe account.
+---
+
## Medusa Server
This section guides you over the steps necessary to add Stripe as a payment provider to your Medusa server.
@@ -44,7 +48,7 @@ In `medusa-config.js` add the following at the end of the `plugins` array:
```jsx title=medusa-config.js
const plugins = [
- ...,
+ // ...
{
resolve: `medusa-payment-stripe`,
options: {
@@ -52,7 +56,7 @@ const plugins = [
webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
},
},
-];
+]
```
:::note
@@ -71,7 +75,7 @@ You’ll first retrieve the API key. You can find it by choosing API Keys from t
Next, you need to add the key to your environment variables. In your Medusa server, create `.env` if it doesn’t already exist and add the Stripe key:
-```jsx
+```bash
STRIPE_API_KEY=sk_...
```
@@ -91,10 +95,12 @@ Then, you can add a description. You must select at least one event to listen to
After the Webhook is created, you’ll see "Signing secret" in the Webhook details. Click on "Reveal" to reveal the secret key. Copy that key and in your Medusa server add the Webhook secret environment variable:
-```jsx
+```bash
STRIPE_WEBHOOK_SECRET=whsec_...
```
+---
+
## Admin Setup
This section will guide you through adding Stripe as a payment provider in a region using your Medusa admin dashboard.
@@ -109,6 +115,8 @@ If you don’t have a Medusa admin installed, make sure to follow along with [th
You can refer to [this documentation in the user guide](../user-guide/regions/providers.mdx#manage-payment-providers) to learn how to add a payment provider like Stripe to a region.
+---
+
## Storefront Setup
This guide will take you through how to set up Stripe payments in your Medusa storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront.
@@ -187,30 +195,30 @@ In this section, you’ll initialize Stripe without Medusa’s checkout workflow
Create a container component that will hold the payment card component:
```jsx
-import { useState } from 'react';
+import { useState } from "react"
-import {Elements} from '@stripe/react-stripe-js';
-import Form from './Form';
-import {loadStripe} from '@stripe/stripe-js';
+import { Elements } from "@stripe/react-stripe-js"
+import Form from "./Form"
+import { loadStripe } from "@stripe/stripe-js"
-const stripePromise = loadStripe('pk_...');
+const stripePromise = loadStripe("pk_...")
export default function Container() {
const [clientSecret, setClientSecret] = useState()
- //TODO set clientSecret
+ // TODO set clientSecret
return (
+---
+
## Install the Admin
:::tip
@@ -53,6 +59,21 @@ Then, install the dependencies:
npm install
```
+
```jsx
-medusa.admin.uploads.create(file) //file is an instance of File
+medusa.admin.uploads.create(file) // file is an instance of File
.then(({ uploads }) => {
- const key = uploads[0].key;
-});
+ const key = uploads[0].key
+})
```
```jsx
-const formData = new FormData();
-formData.append('files', file); //file is an instance of File
+const formData = new FormData()
+formData.append("files", file) // file is an instance of File
fetch(`/admin/uploads`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'multipart/form-data',
+ "Content-Type": "multipart/form-data",
},
- body: formData
+ body: formData,
})
.then((response) => response.json())
.then(({ uploads }) => {
- const key = uploads[0].key;
-});
+ const key = uploads[0].key
+})
```
@@ -106,6 +110,8 @@ curl -L -X POST '/admin/uploads' \
This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the prices next.
+---
+
## 2. Create a Batch Job for Prices Import
To start a new price import, you must create a batch job.
@@ -117,16 +123,16 @@ You can do that by sending the following request to the [Create a Batch Job](htt
```jsx
medusa.admin.batchJobs.create({
- type: 'price-list-import',
+ type: "price-list-import",
context: {
- fileKey: key, //obtained from previous step
- price_list_id
+ fileKey: key, // obtained from previous step
+ price_list_id,
},
- dry_run: true
+ dry_run: true,
})
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -134,24 +140,24 @@ medusa.admin.batchJobs.create({
```jsx
fetch(`/admin/batch-jobs`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- type: 'price-list-import',
+ type: "price-list-import",
context: {
- fileKey: key, //obtained from previous step
- price_list_id
+ fileKey: key, // obtained from previous step
+ price_list_id,
},
- dry_run: true
- })
+ dry_run: true,
+ }),
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -192,6 +198,8 @@ If you don’t set `dry_run` or you set it to `false`, you don’t need to follo
:::
+---
+
## (Optional) Retrieve Batch Job
After creating the batch job, it will be pre-processed. At this point, the CSV file will be validated, and the number of prices to add are counted.
@@ -204,8 +212,8 @@ You can retrieve all the details of the batch job, including its status and the
```jsx
medusa.admin.batchJobs.retrieve(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -213,12 +221,12 @@ medusa.admin.batchJobs.retrieve(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -249,10 +257,12 @@ Here’s an example of the `result` property:
"message": "5 prices will be added"
}
],
- "advancement_count": 0 //number of prices processed so far. Will be 0 before the import is confirmed.
+ "advancement_count": 0 //number of prices processed so far.
},
```
+---
+
## 3. Confirm Batch Job
A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the price import will start which will add prices to the price list
@@ -265,8 +275,8 @@ To confirm a batch job send the following request:
```jsx
medusa.admin.batchJobs.confirm(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -274,13 +284,13 @@ medusa.admin.batchJobs.confirm(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}/confirm`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -305,7 +315,9 @@ After confirming the batch job, you can check the status while it is processing
- If the status is `failed`, it means an error has occurred during the import. You can check the error in `result.errors`.
- If the status is `completed`, it means the import has finished successfully.
-## What’s Next 🚀
+---
-- Learn more about [Batch Jobs and how they work](../backend/batch-jobs/index.md).
-- Check out the [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job).
\ No newline at end of file
+## See Also
+
+- [Batch Jobs Overview](../backend/batch-jobs/index.md)
+- [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job)
diff --git a/docs/content/advanced/admin/import-products.mdx b/docs/content/advanced/admin/import-products.mdx
index 7d2e3cc2c5..ee9074d0ca 100644
--- a/docs/content/advanced/admin/import-products.mdx
+++ b/docs/content/advanced/admin/import-products.mdx
@@ -9,11 +9,13 @@ In this document, you’ll learn how to use the Admin APIs to bulk import produc
Using Medusa’s [Batch Job Admin APIs](https://docs.medusajs.com/api/admin/#tag/Batch-Job), you can import products into your Medusa server. This will either add new products or update existing products.
+---
+
## Prerequisites
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
### Redis
@@ -48,6 +50,8 @@ You must be an authenticated admin user before following along with the steps in
You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+---
+
## 1. Upload CSV File
The first step is to upload the CSV file that you want to import products.
@@ -58,31 +62,31 @@ You can do that by sending the following request to the [Upload Files](https://d
```jsx
-medusa.admin.uploads.create(file) //file is an instance of File
+medusa.admin.uploads.create(file) // file is an instance of File
.then(({ uploads }) => {
- const key = uploads[0].key;
-});
+ const key = uploads[0].key
+})
```
```jsx
-const formData = new FormData();
-formData.append('files', file); //file is an instance of File
+const formData = new FormData()
+formData.append("files", file) // file is an instance of File
fetch(`/admin/uploads`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'multipart/form-data',
+ "Content-Type": "multipart/form-data",
},
- body: formData
+ body: formData,
})
.then((response) => response.json())
.then(({ uploads }) => {
- const key = uploads[0].key;
-});
+ const key = uploads[0].key
+})
```
@@ -100,6 +104,8 @@ curl -L -X POST '/admin/uploads' \
This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the products next.
+---
+
## 2. Create a Batch Job for Product Import
To start a new product import, you must create a batch job.
@@ -111,15 +117,15 @@ You can do that by sending the following request to the [Create a Batch Job](htt
```jsx
medusa.admin.batchJobs.create({
- type: 'product-import',
+ type: "product-import",
context: {
- fileKey: key //obtained from previous step
+ fileKey: key, // obtained from previous step
},
- dry_run: true
+ dry_run: true,
})
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -127,23 +133,23 @@ medusa.admin.batchJobs.create({
```jsx
fetch(`/admin/batch-jobs`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- type: 'product-import',
+ type: "product-import",
context: {
- fileKey: key //obtained from previous step
+ fileKey: key, // obtained from previous step
},
- dry_run: true
- })
+ dry_run: true,
+ }),
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -180,6 +186,8 @@ If you don’t set `dry_run` or you set it to `false`, you don’t need to follo
:::
+---
+
## (Optional) Retrieve Batch Job
After creating the batch job, it will be pre-processed. At this point, the CSV file will be validated, and the number of products to add and update, or that are rejected are counted.
@@ -192,8 +200,8 @@ You can retrieve all the details of the batch job, including its status and the
```jsx
medusa.admin.batchJobs.retrieve(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -201,12 +209,12 @@ medusa.admin.batchJobs.retrieve(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -234,13 +242,15 @@ Here’s an example of the `result` property:
{
"key": "product-import-count",
"name": "Products/variants to import",
- "message": "There will be 2 products created (0 updated).\n 3 variants will be created and 0 updated"
+ "message": "There will be 2 products created..."
}
],
- "advancement_count": 0 //number of products processed so far. Will be 0 before the import is confirmed.
+ "advancement_count": 0 //number of products processed so far.
},
```
+---
+
## 3. Confirm Batch Job
A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the product import will start which will create or update products on your server.
@@ -253,8 +263,8 @@ To confirm a batch job send the following request:
```jsx
medusa.admin.batchJobs.confirm(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -262,13 +272,13 @@ medusa.admin.batchJobs.confirm(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}/confirm`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -293,7 +303,9 @@ After confirming the batch job, you can check the status while it is processing
- If the status is `failed`, it means an error has occurred during the import. You can check the error in `result.errors`.
- If the status is `completed`, it means the import has finished successfully.
-## What’s Next
+---
-- Learn more about [Batch Jobs and how they work](../backend/batch-jobs/index.md).
-- Check out the [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job).
+## See Also
+
+- [Batch Jobs Overview](../backend/batch-jobs/index.md)
+- [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job)
diff --git a/docs/content/advanced/admin/manage-customers.mdx b/docs/content/advanced/admin/manage-customers.mdx
new file mode 100644
index 0000000000..3d250b8f07
--- /dev/null
+++ b/docs/content/advanced/admin/manage-customers.mdx
@@ -0,0 +1,230 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Manage Customers
+
+In this document, you’ll learn how to implement customer management functionalities for admin users.
+
+## Overview
+
+Using the customer admin REST APIs, you can manage customers, including creating, updating, and listing them.
+
+### Scenario
+
+You want to add or use the following admin functionalities:
+
+- List customers
+- Add a new customer
+- Edit a customer’s details
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../js-client/overview.md) installed and have [created an instance of the client](../../js-client/overview.md#configuration).
+
+### Authenticated Admin User
+
+You must be an authenticated admin user before following along with the steps in the tutorial.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+---
+
+## List Customers
+
+You can show a list of customers by sending a request to the [List Customers](/api/admin/#tag/Customer/operation/GetCustomers) endpoint:
+
+
+
+
+```ts
+medusa.admin.customers.list()
+.then(({ customers, limit, offset, count }) => {
+ console.log(customers.length)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/customers`, {
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ customers, limit, offset, count }) => {
+ console.log(customers.length)
+})
+```
+
+
+
+
+```bash
+curl -L -X GET '/admin/customers' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request doesn’t require any path or query parameters. You can pass it optional parameters used for filtering and pagination. Check out the [API reference](/api/admin/#tag/Customer/operation/GetCustomers) to learn more.
+
+This request returns the following data in the response:
+
+- `customers`: An array of customers.
+- `limit`: The maximum number of customers that can be returned in the request.
+- `offset`: The number of customers skipped in the result.
+- `count`: The total number of customers available.
+
+:::info
+
+You can learn more about pagination in the [API reference](/api/admin/#section/Pagination).
+
+:::
+
+---
+
+## Create a Customer
+
+Admins can create customer accounts. They have to supply the customer’s credentials and basic info.
+
+You can create a customer account by sending a request to the [Create a Customer](/api/admin/#tag/Customer/operation/PostCustomers) endpoint:
+
+
+
+
+```ts
+medusa.admin.customers.create({
+ email,
+ password,
+ first_name,
+ last_name,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/customers`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ email,
+ password,
+ first_name,
+ last_name,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/customers' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "email": "",
+ "first_name": "",
+ "last_name": "",
+ "password": ""
+}'
+```
+
+
+
+
+This request requires the following body parameters:
+
+- `email`: The email of the customer.
+- `password`: The password of the customer.
+- `first_name`: The customer’s first name.
+- `last_name`: the customer’s last name.
+
+You can also pass other optional parameters. To learn more, check out the [API reference](/api/admin/#tag/Customer/operation/PostCustomers).
+
+The request returns the created customer object in the response.
+
+---
+
+## Edit Customer’s Information
+
+An admin can edit a customer’s basic information and credentials.
+
+You can edit a customer’s information by sending a request to the [Update a Customer](/api/admin/#tag/Customer/operation/PostCustomersCustomer) endpoint:
+
+
+
+
+```ts
+medusa.admin.customers.update(customerId, {
+ first_name,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/customers/${customerId}`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ first_name,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/customers/' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "first_name": ""
+}'
+```
+
+
+
+
+This request accepts any of the customer’s fields as body parameters. In this example, you update the customer’s first name. You can learn more about accepted body parameters in the [API reference](/api/admin/#tag/Customer/operation/PostCustomersCustomer).
+
+This request returns the updated customer object in the response.
+
+---
+
+## See Also
+
+- [Manage customer groups](./use-customergroups-api.mdx)
+- [Customers admin API reference](/api/admin)
+- [Customers overview](../backend/customers/index.md)
+- [Implement customer profiles in the storefront](../storefront/customer-profiles.mdx)
diff --git a/docs/content/advanced/admin/manage-discounts.mdx b/docs/content/advanced/admin/manage-discounts.mdx
index 26a2a5f21b..c3a148e7b1 100644
--- a/docs/content/advanced/admin/manage-discounts.mdx
+++ b/docs/content/advanced/admin/manage-discounts.mdx
@@ -1,7 +1,7 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-# Manage Discounts using Admin APIs
+# How to Manage Discounts using Admin APIs
In this document, you’ll learn how to use the Admin’s Discount APIs to manage discounts, discount conditions, and more.
@@ -29,11 +29,13 @@ You can use Medusa’s Admin APIs to achieve more functionalities as well. Check
:::
+---
+
# Prerequisites
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
### JS Client
@@ -47,6 +49,8 @@ You must be an authenticated admin user before following along with the steps in
You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+---
+
## Create a Discount
You can create a discount by sending a request to the [Create Discount](/api/admin/#tag/Discount/operation/PostDiscounts) endpoint:
@@ -56,21 +60,21 @@ You can create a discount by sending a request to the [Create Discount](/api/adm
```jsx
import { AllocationType, DiscountRuleType } from "@medusajs/medusa"
-//...
+// ...
medusa.admin.discounts.create({
code,
rule: {
type: DiscountRuleType.FIXED,
value: 10,
- allocation: AllocationType.ITEM
+ allocation: AllocationType.ITEM,
},
regions: [
- regionId
- ]
+ regionId,
+ ],
})
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -78,27 +82,27 @@ medusa.admin.discounts.create({
```jsx
fetch(`/admin/discounts`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
code,
rule: {
- type: 'fixed',
+ type: "fixed",
value: 10,
- allocation: 'item'
+ allocation: "item",
},
regions: [
- regionId
- ]
- })
+ regionId,
+ ],
+ }),
})
.then((response) => response.json())
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -135,6 +139,8 @@ This request accepts [many request-body parameters](/api/admin/#tag/Discount/ope
This request returns the full `discount` object.
+---
+
## Update Discount
You can update any of the discount’s information, configurations, and conditions by sending a request to the [Update Discount](/api/admin/#tag/Discount/operation/PostDiscountsDiscount) endpoint.
@@ -147,11 +153,11 @@ For example, you can update the discount’s description and status by sending t
```jsx
medusa.admin.discounts.update(discountId, {
description: "New description",
- is_disabled: true
+ is_disabled: true,
})
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -159,20 +165,20 @@ medusa.admin.discounts.update(discountId, {
```jsx
fetch(`/admin/discounts/${discountId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
description: "New description",
- is_disabled: true
- })
+ is_disabled: true,
+ }),
})
.then((response) => response.json())
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -197,6 +203,8 @@ You can check the [API reference](/api/admin/#tag/Discount/operation/PostDiscoun
This updates the discount’s information and returns the full updated `discount` object in the response.
+---
+
## Manage Conditions
### Create a Condition
@@ -214,16 +222,16 @@ You can send a request to the [Create Condition](/api/admin/#tag/Discount-Condit
```jsx
import { DiscountConditionOperator } from "@medusajs/medusa"
-//...
+// ...
medusa.admin.discounts.createCondition(discount_id, {
operator: DiscountConditionOperator.IN,
products: [
- productId
- ]
+ productId,
+ ],
})
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -231,22 +239,22 @@ medusa.admin.discounts.createCondition(discount_id, {
```jsx
fetch(`/admin/discounts/${discountId}/conditions`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- operator: 'in',
+ operator: "in",
products: [
- productId
- ]
- })
+ productId,
+ ],
+ }),
})
.then((response) => response.json())
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -293,24 +301,28 @@ You can retrieve a condition and its resources by sending a request to the [Get
```jsx
medusa.admin.discounts.getCondition(discountId, conditionId, {
- expand: 'products'
+ expand: "products",
})
.then(({ discount_condition }) => {
- console.log(discount_condition.id, discount_condition.products);
-});
+ console.log(discount_condition.id, discount_condition.products)
+})
```
```jsx
-fetch(`/admin/discounts/${discountId}/conditions/${conditionId}&expand=products`, {
- credentials: 'include'
-})
+fetch(
+ `/admin/discounts/${discountId}` +
+ `/conditions/${conditionId}&expand=products`,
+ {
+ credentials: "include",
+ }
+)
.then((response) => response.json())
.then(({ discount_condition }) => {
- console.log(discount_condition.id, discount_condition.products);
-});
+ console.log(discount_condition.id, discount_condition.products)
+})
```
@@ -343,35 +355,38 @@ For example, to update the products in a condition:
medusa.admin.discounts.updateCondition(discountId, conditionId, {
products: [
productId1,
- productId2
- ]
+ productId2,
+ ],
})
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
```jsx
-fetch(`/admin/discounts/${discountId}/conditions/${conditionId}`, {
- method: 'POST',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json'
- },
- body: JSON.stringify({
- products: [
- productId1,
- productId2
- ]
- })
-})
+fetch(
+ `/admin/discounts/${discountId}/conditions/${conditionId}`,
+ {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ products: [
+ productId1,
+ productId2,
+ ],
+ }),
+ }
+)
.then((response) => response.json())
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -408,22 +423,25 @@ You can delete a condition by sending a request to the [Delete Condition](/api/a
```jsx
medusa.admin.discounts.deleteCondition(discountId, conditionId)
.then(({ discount }) => {
- console.log(discount);
-});
+ console.log(discount)
+})
```
```jsx
-fetch(`/admin/discounts/${discountId}/conditions/${conditionId}`, {
- method: 'DELETE',
- credentials: 'include'
-})
+fetch(
+ `/admin/discounts/${discountId}/conditions/${conditionId}`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ }
+)
.then((response) => response.json())
.then(({ discount }) => {
- console.log(discount.id);
-});
+ console.log(discount.id)
+})
```
@@ -441,6 +459,8 @@ This request accepts as a path parameter the discount ID and the condition ID.
It returns the `discount` object in the response.
+---
+
## Delete Discount
You can delete a discount by sending a request to the [Delete Discount](/api/admin/#tag/Discount/operation/DeleteDiscountsDiscount) endpoint:
@@ -451,8 +471,8 @@ You can delete a discount by sending a request to the [Delete Discount](/api/adm
```jsx
medusa.admin.discounts.delete(discount_id)
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -460,13 +480,13 @@ medusa.admin.discounts.delete(discount_id)
```jsx
fetch(`/admin/discounts/${discountId}`, {
- method: 'DELETE',
- credentials: 'include'
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -488,7 +508,9 @@ It returns in the response the following fields:
- `object`: A string indicating the type of object deleted. By default, its value is `discount`.
- `deleted`: A boolean value indicating whether the discount was deleted or not.
-## What’s Next
+---
-- Check out more [Admin Discount APIs in the API reference](/api/admin/#tag/Discount).
-- Learn how you can [use Discounts on the storefront](../storefront/use-discounts-in-checkout.mdx).
+## See Also
+
+- [Discounts API reference](/api/admin/#tag/Discount)
+- [Use Discounts on the storefront](../storefront/use-discounts-in-checkout.mdx)
diff --git a/docs/content/advanced/admin/manage-regions.mdx b/docs/content/advanced/admin/manage-regions.mdx
index 20d6c0961e..52def1da8e 100644
--- a/docs/content/advanced/admin/manage-regions.mdx
+++ b/docs/content/advanced/admin/manage-regions.mdx
@@ -1,7 +1,7 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-# Manage Regions using Admin APIs
+# How to Manage Regions using Admin APIs
In this document, you’ll learn how to manage regions using the Admin APIs.
@@ -31,7 +31,7 @@ You can use Medusa’s Admin APIs to achieve more functionalities as well. Check
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
### JS Client
@@ -57,9 +57,9 @@ You can retrieve regions available on your server using the [List Regions](/api/
```tsx
medusa.admin.regions.list()
.then(({ regions, limit, offset, count }) => {
- console.log(regions.length);
- //display regions
-});
+ console.log(regions.length)
+ // display regions
+})
```
@@ -67,13 +67,13 @@ medusa.admin.regions.list()
```tsx
fetch(`/admin/regions`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ regions, limit, offset, count }) => {
- console.log(regions.length);
- //display regions
-});
+ console.log(regions.length)
+ // display regions
+})
```
@@ -102,22 +102,22 @@ You can create a region by sending a request to the [Create a Region](/api/admin
```tsx
medusa.admin.regions.create({
- name: 'Europe',
- currency_code: 'eur',
+ name: "Europe",
+ currency_code: "eur",
tax_rate: 0,
payment_providers: [
- 'manual'
+ "manual",
],
fulfillment_providers: [
- 'manual'
+ "manual",
],
countries: [
- 'DK'
- ]
+ "DK",
+ ],
})
.then(({ region }) => {
- console.log(region.id);
-});
+ console.log(region.id)
+})
```
@@ -125,27 +125,27 @@ medusa.admin.regions.create({
```tsx
fetch(`/admin/regions`, {
- credentials: 'include',
- method: 'POST',
+ credentials: "include",
+ method: "POST",
body: JSON.stringify({
- name: 'Europe',
- currency_code: 'eur',
+ name: "Europe",
+ currency_code: "eur",
tax_rate: 0,
payment_providers: [
- 'manual'
+ "manual",
],
fulfillment_providers: [
- 'manual'
+ "manual",
],
countries: [
- 'DK'
- ]
- })
+ "DK",
+ ],
+ }),
})
.then((response) => response.json())
.then(({ region }) => {
- console.log(region.id);
-});
+ console.log(region.id)
+})
```
@@ -202,12 +202,12 @@ Alternatively, you can update the details of a region using the [Update a Region
medusa.admin.regions.update(regionId, {
countries: [
"DK",
- "DE"
- ]
+ "DE",
+ ],
})
.then(({ region }) => {
- console.log(region.id);
-});
+ console.log(region.id)
+})
```
@@ -215,25 +215,25 @@ medusa.admin.regions.update(regionId, {
```tsx
fetch(`/admin/regions/${regionId}`, {
- credentials: 'include',
- method: 'POST',
+ credentials: "include",
+ method: "POST",
body: JSON.stringify({
countries: [
- 'DK',
- 'DE'
- ]
- })
+ "DK",
+ "DE",
+ ],
+ }),
})
.then((response) => response.json())
.then(({ region }) => {
- console.log(region.id);
-});
+ console.log(region.id)
+})
```
-```tsx
+```bash
curl -L -X POST '/admin/regions/' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
@@ -271,17 +271,17 @@ You can add a shipping option to a region by sending a request to the [Create Sh
```tsx
medusa.admin.shippingOptions.create({
- name: 'PostFake',
+ name: "PostFake",
region_id: regionId,
provider_id: "manual",
data: {
},
- price_type: 'flat_rate',
- amount: 1000
+ price_type: "flat_rate",
+ amount: 1000,
})
.then(({ shipping_option }) => {
- console.log(shipping_option.id);
-});
+ console.log(shipping_option.id)
+})
```
@@ -289,28 +289,28 @@ medusa.admin.shippingOptions.create({
```tsx
fetch(`/admin/shipping-options`, {
- credentials: 'include',
- method: 'POST',
+ credentials: "include",
+ method: "POST",
body: JSON.stringify({
- name: 'PostFake',
+ name: "PostFake",
region_id: regionId,
provider_id: "manual",
- price_type: 'flat_rate',
+ price_type: "flat_rate",
data: {
},
- amount: 1000
- })
+ amount: 1000,
+ }),
})
.then((response) => response.json())
.then(({ shipping_option }) => {
- console.log(shipping_option.id);
-});
+ console.log(shipping_option.id)
+})
```
-```tsx
+```bash
curl -L -X POST '/admin/shipping-options' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
@@ -360,8 +360,8 @@ You can delete a region by sending a request to the [Delete a Region](/api/admin
```tsx
medusa.admin.regions.delete(regionId)
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -369,19 +369,19 @@ medusa.admin.regions.delete(regionId)
```tsx
fetch(`/admin/regions/${regionId}`, {
- credentials: 'include',
- method: 'DELETE'
+ credentials: "include",
+ method: "DELETE",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
-```tsx
+```bash
curl -L -X DELETE '/admin/regions/' \
-H 'Authorization: Bearer '
```
@@ -397,7 +397,7 @@ This request requires the region ID as a path parameter. It deletes the region a
---
-## What’s Next
+## See Also
-- Learn more about [Regions’ architecture](../backend/regions/overview.md).
-- Learn [how to use Regions on the storefront](../storefront/use-regions.mdx).
\ No newline at end of file
+- [Regions Overview](../backend/regions/overview.md)
+- [Use Regions on the storefront](../storefront/use-regions.mdx)
\ No newline at end of file
diff --git a/docs/content/advanced/admin/order-edit.mdx b/docs/content/advanced/admin/order-edit.mdx
new file mode 100644
index 0000000000..dfc73fe224
--- /dev/null
+++ b/docs/content/advanced/admin/order-edit.mdx
@@ -0,0 +1,616 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Edit an Order
+
+In this document, you’ll learn how to create an order edit using the Admin API endpoints.
+
+:::note
+
+The Order Editing feature is currently in beta mode and guarded by a feature flag. To use Order Editing either:
+
+1. Enable the `MEDUSA_FF_ORDER_EDITING` environment variable;
+2. Or enable the `order_editing` key in the Medusa server's settings.
+
+You can learn more about enabling it in the [feature flags](../backend/feature-flags/toggle.md) documentation.
+
+:::
+
+## Overview
+
+The Admin API can be used to edit a customer’s order using the Order Editing feature.
+
+The following changes can be made on an order:
+
+- Add a new item to the original order
+- Edit an item’s quantity in the original order.
+- Delete an item from the original order.
+
+Medusa then takes care of the calculation of subtotals, taxes, and more.
+
+The Order Edit can then either be confirmed using the Storefront API as a customer, or force-confirmed using the Admin API as a merchant.
+
+The changes are only reflected on the original order once the Order Edit is confirmed.
+
+
+
+### Scenario
+
+You want to add or use the following admin functionalities related to Order Editing:
+
+- Create an order edit.
+- Add, edit, and delete items from an order.
+- Revert an item change in an order edit.
+- Move order edit into request state.
+- Force-confirm an order edit.
+
+:::note
+
+You can perform other functionalities related to order editing. To learn more, check out the [API reference](/api/admin/#tag/OrderEdit).
+
+:::
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../js-client/overview.md) installed and have [created an instance of the client](../../js-client/overview.md#configuration).
+
+### Authenticated Admin User
+
+You must be an authenticated admin user before following along with the steps in the tutorial.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+### Previous Steps
+
+You must have an existing order that you want to edit.
+
+---
+
+## Create an Order Edit
+
+Before you can start making changes to an order, you have to create a new order edit.
+
+To do that, send a request to the [Create an OrderEdit](/api/admin/#tag/OrderEdit/operation/PostOrderEdits) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.create({
+ order_id, // required
+})
+.then(({ order_edit }) => {
+ console.log(order_edit.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits`, {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ order_id,
+ }),
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.id)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/order-edits' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "order_id": ""
+}'
+```
+
+
+
+
+This endpoint has one required request body parameter `order_id` which is the ID of the order this edit is being created for.
+
+This request returns the Order Edit under the `order_edit` property.
+
+:::info
+
+You can only create one Order Edit at a time. So, if you try to create a new Order Edit for an order that is already being edited, you will receive an error.
+
+:::info
+
+---
+
+## Make Changes to an Order’s Items
+
+You can add new items into the original order, edit existing item in the original order, or delete items in the original order.
+
+:::info
+
+You can only make changes to items that have not been fulfilled yet in the order.
+
+:::
+
+### Add an Item
+
+To add a new item to the original order, send a request to the [Add Line Item](/api/admin/#tag/OrderEdit/operation/PostOrderEditsEditLineItems) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.addLineItem(orderEditId, {
+ quantity: 1,
+ variant_id,
+})
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits/${orderEditId}/items`, {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ quantity: 1,
+ variant_id,
+ }),
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/order-edits//items' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "quantity": 1,
+ "variant_id": ""
+}'
+```
+
+
+
+
+This request requires the ID of the order edit as a path parameter.
+
+In the body of the request, you pass the two parameters `quantity` and `variant_id` which will be used to add a new item into the original order.
+
+This request returns the Order Edit object. You can access returned item changes using `order_edit.changes`.
+
+### Update an Item
+
+You can edit an item’s quantity in the original order.
+
+To update an item, send a request to the [Update Line Item](/api/admin/#tag/OrderEdit/operation/PostOrderEditsEditLineItemsLineItem) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.updateLineItem(orderEditId, itemId, {
+ quantity: 2,
+})
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits/${orderEditId}/items/${itemId}`, {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ quantity: 2,
+ }),
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/order-edits//items/' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "quantity": 2
+}'
+```
+
+
+
+
+This request requires the ID of the order edit and the ID of the item in the original order as path parameters.
+
+In the body of the request, you can pass the `quantity` parameter, with its value being the new item quantity. In this example, you change the quantity of the item to `2`.
+
+This request returns the Order Edit object. You can access returned item changes using `order_edit.changes`.
+
+### Remove an Item
+
+You can remove an item from the original order by sending a request to the [Remove Line Item](/api/admin/#tag/OrderEdit/operation/DeleteOrderEditsOrderEditLineItemsLineItem) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.removeLineItem(orderEditId, itemId)
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits/${orderEditId}/items/${itemId}`, {
+ method: "DELETE",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+})
+```
+
+
+
+
+```bash
+curl -L -X DELETE '/admin/order-edits//items/' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request requires the order edit’s ID and the ID of the item in the original order as path parameters.
+
+This request returns the Order Edit object. You can access returned item changes using `order_edit.changes`.
+
+---
+
+## Revert an Item Change
+
+A merchant might make a mistake while making a change to the original order’s items. Using the Admin API, you can revert item changes previously created.
+
+To revert an item change, send a request to the [Delete Item Change](/api/admin/#tag/OrderEdit/operation/DeleteOrderEditsOrderEditItemChange) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.deleteItemChange(orderEditId, changeId)
+.then(({ id, object, deleted }) => {
+ console.log(id)
+})
+```
+
+
+
+
+```ts
+fetch(
+ `/admin/order-edits/${orderEditId}/changes/${changeId}`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ }
+)
+.then((response) => response.json())
+.then(({ id, object, deleted }) => {
+ console.log(id, object, deleted)
+})
+```
+
+
+
+
+```bash
+curl -L -X DELETE '/admin/order-edits//changes/' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request requires the order edit’s ID and the item change’s ID as path parameters.
+
+This request returns an object with the following properties:
+
+- `id`: The ID of the deleted object. In this case, it’s the ID of the item change.
+- `object`: A string indicating the type of deleted object. In this case, it’s `item_change`.
+- `deleted`: A boolean value indicating whether the item change was deleted.
+
+---
+
+## Move into Request State
+
+After an Order Edit is created and all the item changes are added, it must be moved into the request state.
+
+To move an Order Edit into the request state, send a request to the [Request Confirmation](/api/admin/#tag/OrderEdit/operation/PostOrderEditsOrderEditRequest) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.requestConfirmation(orderEditId)
+.then(({ order_edit }) => {
+ console.log(order_edit.requested_at, order_edit.requested_by)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits/${orderEditId}/request`, {
+ method: "POST",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.requested_at, order_edit.requested_by)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/order-edits//request' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request requires the order edit’s ID as a path parameter.
+
+It returns the Order Edit object. You can access the following properties related to the confirmation request:
+
+- `requested_at`: A timestamp indicating when the request confirmation was created.
+- `requested_by`: The ID of the user that requested this order edit.
+
+:::tip
+
+💡 This request triggers the event `order-edit.requested`. You can use a subscriber to send an email to the customer with a link to view the order edit on the storefront. You can learn more in the [Events reference](../backend/subscribers/events-list.md).
+
+:::
+
+---
+
+## Force-Confirm an Order Edit
+
+There are two ways to confirm an Order Edit:
+
+1. Using the Storefront API, which would confirm the Order Edit as a customer;
+2. Or using the Admin API, which would force-confirm the Order Edit as a merchant.
+
+Once an Order Edit is confirmed, the changes to the items defined in the Order Edit will be reflected on the original order. So, a change in the totals of the original order, such as the subtotal, will be reflected as well.
+
+This change can lead to either required additional payments from the customer, or a refund to be made to the customer.
+
+When the merchant force-confirms the order edit, however, it bypasses the payment flow. This means that the admin can’t capture any additional payment.
+
+This section covers how the Admin API can be used to force-confirm the Order Edit. You can refer to [this documentation to learn how to implement Order Edit confirmation on the storefront](../storefront/handle-order-edits.mdx).
+
+To confirm an Order Edit, send a request to the [Confirm Order Edit](/api/admin/#tag/OrderEdit/operation/PostOrderEditsOrderEditConfirm) endpoint:
+
+
+
+
+```ts
+medusa.admin.orderEdits.confirm(orderEditId)
+.then(({ order_edit }) => {
+ console.log(order_edit.confirmed_at, order_edit.confirmed_by)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/order-edits/${orderEditId}/confirm`, {
+ method: "POST",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.confirmed_at, order_edit.confirmed_by)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/order-edits//confirm' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request accepts the order edit ID as a path parameter.
+
+It returns the Order Edit object. You can access the following properties related to the order edit confirmation:
+
+- `confirmed_at`: A timestamp indicating when the order edit was confirmed.
+- `confirmed_by`: The ID of the user that confirmed the order edit.
+
+---
+
+## Receive Additional Payment
+
+When the total after the order edit is greater than the total of the original order, the merchant can capture the difference from the customer.
+
+For order edits that are confirmed by the customer, the customer authorizes the payment before confirming it. So, the merchant can capture the payment.
+
+For force-confirmed order edits, as the customer didn’t authorize the payment, the merchant can’t capture the payment. It has to be handled manually by the merchant.
+
+:::info
+
+You can learn how to allow customers to authorize payment on the storefront in [this documentation](../storefront/handle-order-edits.mdx).
+
+:::
+
+### Capture Payment
+
+If the payment is authorized by the customer, it can be captured by sending a request to the [Capture Payment](/api/admin/#tag/Payment/operation/PostPaymentsPaymentCapture) endpoint:
+
+
+
+
+```ts
+medusa.admin.payments.capturePayment(paymentId)
+.then(({ payment }) => {
+ console.log(payment.captured_at)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/payments/${paymentId}/capture`, {
+ method: "POST",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ payment }) => {
+ console.log(payment.captured_at)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/payments//capture' \
+-H 'Authorization: Bearer '
+```
+
+
+
+
+This request requires the ID of the payment as a path parameter. The payment can be retrieved from the order by accessing the array property `order.payments`.
+
+It returns in the response the full Payment object.
+
+## Refund Payment
+
+When the total after the order edit is less than the original order total, the merchant can refund the difference to the customer.
+
+To refund the difference to the customer, send a request to the [Refund Payment](/api/admin/#tag/Payment/operation/PostPaymentsPaymentRefunds) endpoint:
+
+
+
+
+```ts
+medusa.admin.payments.refundPayment(paymentId, {
+ amount,
+})
+.then(({ refund }) => {
+ console.log(refund.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/admin/payments/${paymentId}/refund`, {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ amount,
+ }),
+})
+.then((response) => response.json())
+.then(({ refund }) => {
+ console.log(refund.id)
+})
+```
+
+
+
+
+```bash
+curl -L -X POST '/admin/payments//refund' \
+-H 'Authorization: Bearer ' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+ "amount": 1000
+}'
+```
+
+
+
+
+This request requires the ID of the payment as a path parameter. The payment can be retrieved from the order by accessing the array property `order.payments`.
+
+In the request’s body parameters, the `amount` field parameter is required. It is the amount to be refunded.
+
+:::note
+
+Check out what other parameters can be sent in the [API reference](/api/admin/#tag/Payment/operation/PostPaymentsPaymentRefunds).
+
+:::
+
+It returns in the response the full Refund object.
+
+---
+
+## See Also
+
+- [Handle order edits on the storefront](../storefront/handle-order-edits).
+- [Order Edits API reference](/api/admin/#tag/OrderEdit).
diff --git a/docs/content/advanced/admin/use-customergroups-api.mdx b/docs/content/advanced/admin/use-customergroups-api.mdx
index 4447de5516..346a1e0a08 100644
--- a/docs/content/advanced/admin/use-customergroups-api.mdx
+++ b/docs/content/advanced/admin/use-customergroups-api.mdx
@@ -1,7 +1,7 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-# How to Use CustomerGroup APIs
+# How to Manage Customer Groups
In this document, you’ll learn how to use the customer groups admin APIs to manage customer groups and their associated customers and price lists.
@@ -19,7 +19,7 @@ This guide covers how to use these APIs to perform these tasks.
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
### JS Client
@@ -44,11 +44,11 @@ You can create a customer group by sending a request to the Create Customer Grou
```jsx
medusa.admin.customerGroups.create({
- name: 'VIP'
+ name: "VIP",
})
.then(({ customer_group }) => {
- console.log(customer_group.id);
-});
+ console.log(customer_group.id)
+})
```
@@ -56,19 +56,19 @@ medusa.admin.customerGroups.create({
```jsx
fetch(`/admin/customer-groups`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- name: 'VIP'
- })
+ name: "VIP",
+ }),
})
.then((response) => response.json())
.then(({ customer_group }) => {
console.log(customer_group.id)
-});
+})
```
@@ -100,8 +100,8 @@ You can get a list of all customer groups by sending a request to the List Custo
```jsx
medusa.admin.customerGroups.list()
.then(({ customer_groups, limit, offset, count }) => {
- console.log(customer_groups.length);
-});
+ console.log(customer_groups.length)
+})
```
@@ -109,12 +109,12 @@ medusa.admin.customerGroups.list()
```jsx
fetch(`/admin/customer-groups`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ customer_groups, limit, offset, count }) => {
console.log(customer_groups.length)
-});
+})
```
@@ -144,8 +144,8 @@ You can retrieve a single customer group by sending a request to the Get a Custo
```jsx
medusa.admin.customerGroups.retrieve(customerGroupId)
.then(({ customer_group }) => {
- console.log(customer_group.id);
-});
+ console.log(customer_group.id)
+})
```
@@ -153,12 +153,12 @@ medusa.admin.customerGroups.retrieve(customerGroupId)
```jsx
fetch(`/admin/customer-groups/${customerGroupId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ customer_group }) => {
console.log(customer_group.id)
-});
+})
```
@@ -186,12 +186,12 @@ You can update a customer group’s data by sending a request to the Update Cust
```jsx
medusa.admin.customerGroups.update(customerGroupId, {
metadata: {
- is_seller: true
- }
+ is_seller: true,
+ },
})
.then(({ customer_group }) => {
- console.log(customer_group.id);
-});
+ console.log(customer_group.id)
+})
```
@@ -199,21 +199,21 @@ medusa.admin.customerGroups.update(customerGroupId, {
```jsx
fetch(`/admin/customer-groups/${customerGroupId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
metadata: {
- is_seller: true
- }
- })
+ is_seller: true,
+ },
+ }),
})
.then((response) => response.json())
.then(({ customer_group }) => {
console.log(customer_group.id)
-});
+})
```
@@ -247,8 +247,8 @@ You can delete a customer group by sending a request to the Delete a Customer Gr
```jsx
medusa.admin.customerGroups.delete(customerGroupId)
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -256,13 +256,13 @@ medusa.admin.customerGroups.delete(customerGroupId)
```jsx
fetch(`/admin/customer-groups/${customerGroupId}`, {
- method: 'DELETE',
- credentials: 'include',
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
console.log(id)
-});
+})
```
@@ -293,37 +293,40 @@ You can add a customer to a group by sending a request to the Customer Group’s
medusa.admin.customerGroups.addCustomers(customerGroupId, {
customer_ids: [
{
- id: customerId
- }
- ]
+ id: customerId,
+ },
+ ],
})
.then(({ customer_group }) => {
- console.log(customer_group.id);
-});
+ console.log(customer_group.id)
+})
```
```jsx
-fetch(`/admin/customer-groups/${customerGroupId}/customers/batch`, {
- method: 'POST',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json'
- },
- body: JSON.stringify({
- customer_ids: [
- {
- id: customerId
- }
- ]
- })
-})
+fetch(
+ `/admin/customer-groups/${customerGroupId}/customers/batch`,
+ {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ customer_ids: [
+ {
+ id: customerId,
+ },
+ ],
+ }),
+ }
+)
.then((response) => response.json())
.then(({ customer_group }) => {
console.log(customer_group.id)
-});
+})
```
@@ -357,8 +360,8 @@ You can retrieve a list of all customers in a customer group using the List Cust
```jsx
medusa.admin.customerGroups.listCustomers(customerGroupId)
.then(({ customers, count, offset, limit }) => {
- console.log(customers.length);
-});
+ console.log(customers.length)
+})
```
@@ -366,12 +369,12 @@ medusa.admin.customerGroups.listCustomers(customerGroupId)
```jsx
fetch(`/admin/customer-groups/${customerGroupId}/customers`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ customers, count, offset, limit }) => {
console.log(customers.length)
-});
+})
```
@@ -404,37 +407,40 @@ You can remove customers from a customer group by sending a request to the Remov
medusa.admin.customerGroups.removeCustomers(customer_group_id, {
customer_ids: [
{
- id: customer_id
- }
- ]
+ id: customer_id,
+ },
+ ],
})
.then(({ customer_group }) => {
- console.log(customer_group.id);
-});
+ console.log(customer_group.id)
+})
```
```jsx
-fetch(`/admin/customer-groups/${customerGroupId}/customers/batch`, {
- method: 'DELETE',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json'
- },
- body: JSON.stringify({
- customer_ids: [
- {
- id: customerId
- }
- ]
- })
-})
+fetch(
+ `/admin/customer-groups/${customerGroupId}/customers/batch`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ customer_ids: [
+ {
+ id: customerId,
+ },
+ ],
+ }),
+ }
+)
.then((response) => response.json())
.then(({ customer_group }) => {
console.log(customer_group.id)
-});
+})
```
@@ -468,7 +474,7 @@ When you create or update a price list, you can specify one or more customer gro
---
-## What’s Next
+## See Also
-- Learn more about [Customer Groups](../backend/customer-groups/index.md).
-- Learn about [how to use Sales Channels](../backend/sales-channels/manage-admin.mdx).
\ No newline at end of file
+- [Customer Groups Overview](../backend/customer-groups/index.md).
+- [Use Sales Channels Admin APIs](../backend/sales-channels/manage-admin.mdx).
\ No newline at end of file
diff --git a/docs/content/advanced/backend/batch-jobs/create.md b/docs/content/advanced/backend/batch-jobs/create.md
index 17f3312b17..3cfc6d829a 100644
--- a/docs/content/advanced/backend/batch-jobs/create.md
+++ b/docs/content/advanced/backend/batch-jobs/create.md
@@ -17,11 +17,13 @@ Batch jobs can be used to perform long tasks in the background of your Medusa se
This documentation helps you learn how to create a batch job strategy. The batch job strategy used in this example changes the status of all draft products to `published`.
+---
+
## Prerequisites
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.mdx) to get started.
### Redis
@@ -31,29 +33,36 @@ Redis is required for batch jobs to work. Make sure you [install Redis](../../.
If you use SQLite during your development, it’s highly recommended that you use PostgreSQL when working with batch jobs. Learn how to [install PostgreSQL](../../../tutorial/0-set-up-your-development-environment.mdx#postgresql) and [configure it with your Medusa server](../../../usage/configurations.md#postgresql-configurations).
+---
+
## 1. Create a File
A batch job strategy is essentially a class defined in a TypeScript or JavaScript file. You should create this file in `src/strategies`.
Following the example used in this documentation, create the file `src/strategies/publish.ts`.
+---
+
## 2. Create Class
Batch job strategies must extend the abstract class `AbstractBatchJobStrategy` and implement its abstract methods.
Add the following content to the file you created:
-```tsx title=src/strategies/publish.ts
-import { AbstractBatchJobStrategy, BatchJobService } from '@medusajs/medusa'
-import { EntityManager } from 'typeorm'
+```ts title=src/strategies/publish.ts
+import {
+ AbstractBatchJobStrategy,
+ BatchJobService,
+} from "@medusajs/medusa"
+import { EntityManager } from "typeorm"
class PublishStrategy extends AbstractBatchJobStrategy {
protected batchJobService_: BatchJobService
processJob(batchJobId: string): Promise {
- throw new Error('Method not implemented.')
+ throw new Error("Method not implemented.")
}
buildTemplate(): Promise {
- throw new Error('Method not implemented.')
+ throw new Error("Method not implemented.")
}
protected manager_: EntityManager
protected transactionManager_: EntityManager
@@ -63,6 +72,8 @@ class PublishStrategy extends AbstractBatchJobStrategy {
export default PublishStrategy
```
+---
+
## 3. Define Required Properties
A batch job strategy class must have two static properties: the `identifier` and `batchType` properties. The `identifier` must be a unique string associated with your batch job strategy, and `batchType` must be the batch job's type.
@@ -71,15 +82,17 @@ You will use the `batchType` later when you [interact with the Batch Job APIs](#
Following the same example, add the following properties to the `PublishStrategy` class:
-```tsx
+```ts
class PublishStrategy extends AbstractBatchJobStrategy {
- static identifier = 'publish-products-strategy'
- static batchType = 'publish-products'
+ static identifier = "publish-products-strategy"
+ static batchType = "publish-products"
- //...
+ // ...
}
```
+---
+
## 4. Define Methods
### (Optional) prepareBatchJobForProcessing
@@ -88,10 +101,16 @@ Medusa runs this method before it creates the batch job to prepare the content o
Implementing this method is optional. For example:
-```tsx
-async prepareBatchJobForProcessing(batchJob: CreateBatchJobInput, req: Express.Request): Promise {
- //make changes to the batch job's fields...
- return batchJob
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ async prepareBatchJobForProcessing(
+ batchJob: CreateBatchJobInput,
+ req: Express.Request
+ ): Promise {
+ // make changes to the batch job's fields...
+ return batchJob
+ }
}
```
@@ -101,35 +120,38 @@ Medusa runs this method after it creates the batch job, but before it is confirm
For example, this implementation of the `preProcessBatchJob` method calculates how many draft products it will published and adds it to the `result` attribute of the batch job:
-```tsx
-async preProcessBatchJob(batchJobId: string): Promise {
- return await this.atomicPhase_(async (transactionManager) => {
- const batchJob = (await this.batchJobService_
- .withTransaction(transactionManager)
- .retrieve(batchJobId))
-
- const count = await this.productService_
- .withTransaction(transactionManager)
- .count({
- status: ProductStatus.DRAFT
- });
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ async preProcessBatchJob(batchJobId: string): Promise {
+ return await this.atomicPhase_(async (transactionManager) => {
+ const batchJob = (await this.batchJobService_
+ .withTransaction(transactionManager)
+ .retrieve(batchJobId))
+
+ const count = await this.productService_
+ .withTransaction(transactionManager)
+ .count({
+ status: ProductStatus.DRAFT,
+ })
- await this.batchJobService_
- .withTransaction(transactionManager)
- .update(batchJob, {
- result: {
- advancement_count: 0,
- count,
- stat_descriptors: [
- {
- key: 'product-publish-count',
- name: 'Number of products to publish',
- message: `${count} product(s) will be published.`
- }
- ]
- }
- })
- })
+ await this.batchJobService_
+ .withTransaction(transactionManager)
+ .update(batchJob, {
+ result: {
+ advancement_count: 0,
+ count,
+ stat_descriptors: [
+ {
+ key: "product-publish-count",
+ name: "Number of products to publish",
+ message: `${count} product(s) will be published.`,
+ },
+ ],
+ },
+ })
+ })
+ }
}
```
@@ -145,34 +167,37 @@ Medusa runs this method to process the batch job once it is confirmed.
For example, this implementation of the `processJob` method retrieves all draft products and changes their status to published:
-```tsx
-async processJob(batchJobId: string): Promise {
- return await this.atomicPhase_(
- async (transactionManager) => {
- const productServiceTx = this.productService_
- .withTransaction(transactionManager)
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ async processJob(batchJobId: string): Promise {
+ return await this.atomicPhase_(
+ async (transactionManager) => {
+ const productServiceTx = this.productService_
+ .withTransaction(transactionManager)
- const productList = await productServiceTx
- .list({
- status: [ProductStatus.DRAFT]
- })
-
- productList.forEach(async (product: Product) => {
- await productServiceTx
- .update(product.id, {
- status: ProductStatus.PUBLISHED
+ const productList = await productServiceTx
+ .list({
+ status: [ProductStatus.DRAFT],
})
- })
-
- await this.batchJobService_
- .withTransaction(transactionManager)
- .update(batchJobId, {
- result: {
- advancement_count: productList.length
- }
+
+ productList.forEach(async (product: Product) => {
+ await productServiceTx
+ .update(product.id, {
+ status: ProductStatus.PUBLISHED,
+ })
})
- }
- )
+
+ await this.batchJobService_
+ .withTransaction(transactionManager)
+ .update(batchJobId, {
+ result: {
+ advancement_count: productList.length,
+ },
+ })
+ }
+ )
+ }
}
```
@@ -188,9 +213,12 @@ This method can be used in cases where you provide a template file to download,
If not necessary to your use case, you can simply return an empty string:
-```tsx
-async buildTemplate(): Promise {
- return ''
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ async buildTemplate(): Promise {
+ return ""
+ }
}
```
@@ -202,9 +230,15 @@ By default, the `AbstractBatchJobStrategy` class implements this method and retu
If you would like to change that behavior, you can override this method to return a different value:
-```tsx
-protected async shouldRetryOnProcessingError(batchJob: BatchJob, err: unknown): Promise {
- return true
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ protected async shouldRetryOnProcessingError(
+ batchJob: BatchJob,
+ err: unknown
+ ): Promise {
+ return true
+ }
}
```
@@ -216,12 +250,21 @@ You can use this method as implemented in `AbstractBatchJobStrategy` at any poin
You can also override this method in your batch job strategy and change how it works:
-```tsx
-protected async handleProcessingError(batchJobId: string, err: unknown, result: T): Promise {
- //different implementation...
+```ts
+class PublishStrategy extends AbstractBatchJobStrategy {
+ // ...
+ protected async handleProcessingError(
+ batchJobId: string,
+ err: unknown,
+ result: T
+ ): Promise {
+ // different implementation...
+ }
}
```
+---
+
## 5. Run Build Command
After you create the batch job and before testing it out, you must run the build command in the directory of your Medusa server:
@@ -230,6 +273,8 @@ After you create the batch job and before testing it out, you must run the build
npm run build
```
+---
+
## Test your Batch Job Strategy
This section covers how to test and use your batch job strategy. Make sure to start your server first:
@@ -259,13 +304,13 @@ For example, this creates a batch job of the type `publish-products`:
```jsx
medusa.admin.batchJobs.create({
- type: 'publish-products',
+ type: "publish-products",
context: { },
- dry_run: true
+ dry_run: true,
})
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -273,21 +318,21 @@ medusa.admin.batchJobs.create({
```jsx
fetch(`/admin/batch-jobs`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- type: 'publish-products',
+ type: "publish-products",
context: { },
- dry_run: true
- })
+ dry_run: true,
+ }),
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -321,8 +366,8 @@ You can retrieve the batch job afterward to get its status and view details abou
```jsx
medusa.admin.batchJobs.retrieve(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -330,12 +375,12 @@ medusa.admin.batchJobs.retrieve(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status, batch_job.result);
-});
+ console.log(batch_job.status, batch_job.result)
+})
```
@@ -376,8 +421,8 @@ To process the batch job, send a request to [confirm the batch job](https://docs
```jsx
medusa.admin.batchJobs.confirm(batchJobId)
.then(( batch_job ) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -385,13 +430,13 @@ medusa.admin.batchJobs.confirm(batchJobId)
```jsx
fetch(`/admin/batch-jobs/${batchJobId}/confirm`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
- console.log(batch_job.status);
-});
+ console.log(batch_job.status)
+})
```
@@ -410,7 +455,9 @@ The batch job will start processing afterward. Based on the batch job strategy i
You can [retrieve the batch job](#optional-retrieve-batch-job) at any given point to check its status.
-## What’s Next
+---
-- Learn more about [batch jobs](./index.md).
-- Learn how to [import products using the Admin API](../../admin/import-products.mdx).
+## See Also
+
+- [Batch Jobs Overview](./index.md).
+- [Import products using the Admin API](../../admin/import-products.mdx).
diff --git a/docs/content/advanced/backend/batch-jobs/customize-import.md b/docs/content/advanced/backend/batch-jobs/customize-import.md
index caf919ca62..e1a656fa4b 100644
--- a/docs/content/advanced/backend/batch-jobs/customize-import.md
+++ b/docs/content/advanced/backend/batch-jobs/customize-import.md
@@ -8,11 +8,13 @@ Product Import Strategy is essentially a batch job strategy. Medusa provides the
Although this documentation specifically targets import strategies, you can use the same steps to overwrite any batch job strategy in Medusa, including export strategies.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.mdx) to get started.
### Redis
@@ -22,6 +24,8 @@ Redis is required for batch jobs to work. Make sure you [install Redis](../../.
If you use SQLite during your development, it’s highly recommended that you use PostgreSQL when working with batch jobs. Learn how to [install PostgreSQL](../../../tutorial/0-set-up-your-development-environment.mdx#postgresql) and [configure it with your Medusa server](../../../usage/configurations.md#postgresql-configurations).
+---
+
## Overwrite Batch Job Strategy
The steps required for overwriting a batch job strategy are essentially the same steps required to create a batch job strategy with a minor difference. For that reason, this documentation does not cover the basics of a batch job strategy.
@@ -103,13 +107,17 @@ Specifically, since you create batch jobs using the [Create Batch Job](https://d
If you overwrote the import functionality, you can follow [these steps to learn how to import products using the Admin APIs](../../admin/import-products.mdx).
+---
+
## Create Custom Batch Job Strategy
If you don’t want to overwrite Medusa’s batch job strategy, you can create a custom batch job strategy with a different `batchType` value. Then, use that type when you send a request to [Create a Batch Job](https://docs.medusajs.com/api/admin/#tag/Batch-Job).
For more details on creating custom batch job strategies, please check out the [Create Batch Job Strategy documentation](create.md).
+---
+
## What’s Next
-- Learn more about [batch jobs](./index.md).
-- Learn [how to use the Import Product APIs](../../admin/import-products.mdx).
+- [Batch Jobs Overview](./index.md).
+- [Use the Import Product APIs](../../admin/import-products.mdx).
diff --git a/docs/content/advanced/backend/batch-jobs/index.md b/docs/content/advanced/backend/batch-jobs/index.md
index c2e4122684..caf20ccd22 100644
--- a/docs/content/advanced/backend/batch-jobs/index.md
+++ b/docs/content/advanced/backend/batch-jobs/index.md
@@ -26,6 +26,8 @@ A batch job is stored in the database as a [BatchJob](https://docs.medusajs.com/
- `count`: A number that includes the total count of records related to the operation. For example, in the case of product exports, it is used to indicate the total number of products exported.
- `advancement_count`: A number that indicates the number of records processed so far. Can be helpful when retrying a batch job.
+---
+
## What are Batch Job Strategies
Batch jobs are handled by batch job strategies. A batch job strategy is a class that extends the `AbstractBatchJobStrategy` abstract class and implements the methods defined in that class to handle the different states of a batch job.
@@ -34,6 +36,8 @@ A batch job strategy must implement the necessary methods to handle the preparat
When you create a batch job strategy, the `batchType` class property indicates the batch job types this strategy handles. Then, when you create a new batch job, you set the batch job’s type to the value of `batchType` in your strategy.
+---
+
## How Batch Jobs Work
A batch job’s flow from creation to completion is:
@@ -56,6 +60,8 @@ If the batch job fails at any point in this flow, its status is changed to `fail
+---
+
## What’s Next
-- Learn about the [Batch Job’s events](../subscribers/events-list.md#batch-jobs-events).
+- [Batch Job’s Events Reference](../subscribers/events-list.md#batch-jobs-events).
diff --git a/docs/content/advanced/backend/customer-groups/index.md b/docs/content/advanced/backend/customer-groups/index.md
index a9349812bc..6823503e2e 100644
--- a/docs/content/advanced/backend/customer-groups/index.md
+++ b/docs/content/advanced/backend/customer-groups/index.md
@@ -24,7 +24,7 @@ A customer group is stored in the database as a [CustomerGroup](../../../refere
Similar to all entities in Medusa, you can use the `metadata` object attribute to store any custom data you want. For example, you can add some flag or tag to the customer group for a custom use case:
-```jsx noReport
+```js noReport
metadata: {
is_seller: true
}
@@ -54,7 +54,7 @@ The relation between the `PriceList` and `CustomerGroup` entities is available o
---
-## What’s Next
+## See Also
-- Learn [how to manage customer groups using the Admin APIs](../../admin/use-customergroups-api.mdx).
-- Learn more about [Price Lists and how they work](../price-lists/index.md).
+- [Manage customer groups using the Admin APIs](../../admin/use-customergroups-api.mdx).
+- [Price Lists Overview](../price-lists/index.md).
diff --git a/docs/content/advanced/backend/customers/index.md b/docs/content/advanced/backend/customers/index.md
new file mode 100644
index 0000000000..1f5d6cb104
--- /dev/null
+++ b/docs/content/advanced/backend/customers/index.md
@@ -0,0 +1,78 @@
+# Customers
+
+In this document, you’ll learn about Customers and their relation to other entities in Medusa.
+
+## Introduction
+
+Customers are individuals that make purchases in your store. In Medusa, there are two types of customers: registered customers and guests or unregistered customers.
+
+Both registered and unregistered customers can make purchases. However, only registered customers can log into their accounts and manage their details and orders.
+
+An admin user can view and manage their customers, their details, their orders, and what customer group they’re in.
+
+---
+
+## Customer Entity Overview
+
+A customer is stored in the database as a `Customer` entity. A customer has attributes related to the customer’s details such as `first_name`, `last_name`, and `phone`. However, the only required attribute is `email`.
+
+### has_account Attribute
+
+As mentioned earlier, customers can be either registered or unregistered. The type of customer is identified in the `has_account` attribute. This is a boolean attribute that indicates whether the customer is registered.
+
+For example, when a guest customer places an order, a new `Customer` record is created with the email used (if it doesn’t already exist) and the value for `has_account` is `false`. When the unregistered customer creates an account using the same email, a new `Customer` record will be created with the value of `has_account` set to `true`.
+
+### Email Uniqueness
+
+An email is unique to a type of customer. So, an email can be associated with only one registered customer (where `has_account` is `true`), and one unregistered customer (where `has_account` is `false`).
+
+In the example mentioned above, after the unregistered customer places an order with an email, then creates an account with the same email, two `Customer` records are created. Each of these records have different `has_account` value.
+
+:::info
+
+This architecture allows creating the Claim Order flow, where a registered customer can claim an order they placed as an unregistered customer. You can learn more about it in [this documentation](../../storefront/implement-claim-order.mdx).
+
+:::
+
+---
+
+## Relations to Other Entities
+
+### CustomerGroup
+
+Customer groups allow dividing customers into groups of similar attributes, then apply special pricing or rules for these customer groups.
+
+:::info
+
+You can learn more about customer groups in [this documentation](../customer-groups/index.md).
+
+:::
+
+A customer can belong to more than one customer group. The relation between the `Customer` and `CustomerGroup` entities is available on both entities:
+
+- You can access the customer groups of a customer by expanding the `groups` relation and accessing `customer.groups`.
+- You can access the customers in a customer group by expanding the `customers` relation and accessing `customerGroup.customers`.
+
+### Orders
+
+Customers can have more than one order. The relation between the `Customer` and `Order` entities is available on both entities:
+
+- You can access the orders of a customer by expanding the `orders` relation and accessing `customer.orders`.
+- You can access the customer that placed an order by expanding the `customer` relation and accessing `order.customer`.
+
+### Address
+
+A customer can have a billing address and more than one shipping address. Both billing and shipping addresses are represented by the `Address` entity.
+
+The relation between the `Customer` and `Address` entities is available on both entities:
+
+- You can access the billing address of a customer by expanding the `billing_address` relation and accessing `customer.billing_address`. You can also access the shipping addresses of a customer by expanding the `shipping_addresses` relation and accessing `customer.shipping_addresses`.
+- Likewise, you can access the customer that an address is associated with by expanding the `customer` relation and accessing `address.customer`.
+
+---
+
+## See Also
+
+- [Implement customer profiles in the storefront](../../storefront/customer-profiles.mdx)
+- [Manage customers using the admin APIs](../../admin/manage-customers.mdx)
+- Customers [Admin](/api/admin/#tag/Customer) and [Storefront](/api/store/#tag/Customer) API References
diff --git a/docs/content/advanced/backend/dependency-container/index.md b/docs/content/advanced/backend/dependency-container/index.md
index d5966b7b44..ea28a8462d 100644
--- a/docs/content/advanced/backend/dependency-container/index.md
+++ b/docs/content/advanced/backend/dependency-container/index.md
@@ -26,6 +26,8 @@ When you run the Medusa server, a container of the type `MedusaContainer` is cre
The server then registers all important resources in the container, which makes them accessible in classes and endpoints.
+---
+
## Registered Resources
The Medusa server scans the core Medusa package, plugins, and your files in the `dist` directory and registers the following resources:
@@ -550,6 +552,8 @@ Its camel-case name.
+---
+
## Loading Resources
This section covers how to load resources that the Medusa server registers when it starts running.
@@ -560,8 +564,8 @@ To load resources, such as services, in endpoints, use the `req.scope.resolve` f
For example:
-```typescript
-const logger = req.scope.resolve('logger');
+```ts
+const logger = req.scope.resolve("logger")
```
Please note that in endpoints some resources, such as repositories, are not available.
@@ -572,19 +576,21 @@ In classes such as services, strategies, or subscribers, you can load resources
For example:
-```typescript
-import { OrderService } from '@medusajs/medusa';
+```ts
+import { OrderService } from "@medusajs/medusa"
class OrderSubscriber {
- protected orderService: OrderService;
+ protected orderService: OrderService
constructor({ orderService }) {
- this.orderService = orderService;
+ this.orderService = orderService
}
}
```
-## What’s Next
+---
-- Learn [how to create services](../services/create-service.md).
-- Learn [how to create subscribers](../subscribers/create-subscriber.md).
+## See Also
+
+- [Create services](../services/create-service.md).
+- [Create subscribers](../subscribers/create-subscriber.md).
diff --git a/docs/content/advanced/backend/discounts/index.md b/docs/content/advanced/backend/discounts/index.md
index 2a1b0d7d9b..094f96c43e 100644
--- a/docs/content/advanced/backend/discounts/index.md
+++ b/docs/content/advanced/backend/discounts/index.md
@@ -98,7 +98,7 @@ Based on the value of `type`, one of the following relations can be used to retr
---
-## What’s Next
+## See Also
-- Learn [how to create a discount using the admin APIs](../../admin/manage-discounts.mdx)
-- Learn [how to use discounts on the storefront](../../storefront/use-discounts-in-checkout.mdx)
+- [Create a discount using the admin APIs](../../admin/manage-discounts.mdx)
+- [Use discounts on the storefront](../../storefront/use-discounts-in-checkout.mdx)
diff --git a/docs/content/advanced/backend/endpoints/add.md b/docs/content/advanced/backend/endpoints/add.md
index 86a204143b..e0cc102b78 100644
--- a/docs/content/advanced/backend/endpoints/add.md
+++ b/docs/content/advanced/backend/endpoints/add.md
@@ -6,6 +6,8 @@ In this document, you’ll learn how to create endpoints in your Medusa server.
Custom endpoints reside under the `src/api` directory in your Medusa Backend. They're defined in a TypeScript or JavaScript file that is named `index` (for example, `index.ts`). This file should export a function that returns an Express router.
+---
+
## Implementation
To create a new endpoint, start by creating a new file in `src/api` called `index.ts`. At its basic format, `index.ts` should look something like this:
@@ -42,6 +44,8 @@ By Medusa’s conventions:
You can also create endpoints that don't reside under these two prefixes, similar to the `hello` endpoint in the previous example.
+---
+
## CORS Configuration
If you’re adding a storefront or admin endpoint and you want to access these endpoints from the storefront or Medusa admin, you need to pass your endpoints Cross-Origin Resource Origin (CORS) options using the `cors` package.
@@ -58,12 +62,13 @@ Next, in the exported function, retrieve the CORS configurations of your server
```ts
export default (rootDirectory) => {
- //...
+ // ...
- const { configModule } = getConfigFile(rootDirectory, "medusa-config")
+ const { configModule } =
+ getConfigFile(rootDirectory, "medusa-config")
const { projectConfig } = configModule
- //....
+ // ....
}
```
@@ -90,10 +95,12 @@ Finally, for each route you add, create an `OPTIONS` request and add `cors`
```ts
router.options("/admin/hello", cors(corsOptions))
router.get("/admin/hello", cors(corsOptions), (req, res) => {
- //...
+ // ...
})
```
+---
+
## Create Multiple Endpoints
### Same File
@@ -185,6 +192,8 @@ export default () => {
}
```
+---
+
## Protected Routes
Protected routes are routes that should be accessible by logged-in customers or users only.
@@ -194,20 +203,24 @@ Protected routes are routes that should be accessible by logged-in customers or
To make a storefront route protected, first, import the `authenticate-customer` middleware:
```ts
-import authenticate from "@medusajs/medusa/dist/api/middlewares/authenticate-customer"
+import
+ authenticate
+from "@medusajs/medusa/dist/api/middlewares/authenticate-customer"
```
Then, add the middleware to your route:
```ts
router.options("/store/hello", cors(corsOptions))
-router.get("/store/hello", cors(corsOptions), authenticate(), async (req, res) => {
- if (req.user) {
- //user is logged in
- //to get customer id: req.user.customer_id
+router.get("/store/hello", cors(corsOptions), authenticate(),
+ async (req, res) => {
+ if (req.user) {
+ // user is logged in
+ // to get customer id: req.user.customer_id
+ }
+ // ...
}
- //...
-})
+)
```
Please note that the endpoint is still accessible by all users, however, you’ll be able to access the current logged-in customer if there’s any.
@@ -219,25 +232,31 @@ To disallow guest customers from accessing the endpoint, you can throw an error
To make an admin route protected, first, import the `authenticate` middleware:
```ts
-import authenticate from "@medusajs/medusa/dist/api/middlewares/authenticate"
+import
+ authenticate
+from "@medusajs/medusa/dist/api/middlewares/authenticate"
```
Then, add the middleware to your route:
```ts
router.options("/admin/products/count", cors(corsOptions))
-router.get("/admin/products/count", cors(corsOptions), authenticate(), async (req, res) => {
- //access current user
- const id = req.user.userId
- const userService = req.scope.resolve("userService")
-
- const user = await userService.retrieve(id)
- //...
-})
+router.get("/admin/products/count", cors(corsOptions), authenticate(),
+ async (req, res) => {
+ // access current user
+ const id = req.user.userId
+ const userService = req.scope.resolve("userService")
+
+ const user = await userService.retrieve(id)
+ // ...
+ }
+)
```
Now, only authenticated users can access this endpoint.
+---
+
## Use Services
Services in Medusa bundle a set of functionalities into one class. Then, you can use that class anywhere in your backend. For example, you can use the `ProductService` to retrieve products or perform operations like creating or updating a product.
@@ -247,19 +266,23 @@ You can retrieve any registered service in your endpoint using `req.scope.resol
Here’s an example of an endpoint that retrieves the count of products in your store:
```ts
-router.get("/admin/products/count", cors(corsOptions), authenticate(), (req, res) => {
- const productService = req.scope.resolve("productService")
+router.get("/admin/products/count", cors(corsOptions), authenticate(),
+ (req, res) => {
+ const productService = req.scope.resolve("productService")
- productService.count().then((count) => {
- res.json({
- count,
+ productService.count().then((count) => {
+ res.json({
+ count,
+ })
})
- })
-})
+ }
+)
```
The `productService` has a `count` method that returns a Promise. This Promise resolves to the count of the products. You return a JSON of the product count.
+---
+
## Building Files
Custom endpoints must be transpiled and moved to the `dist` directory. This happens when you run your server using `medusa develop` and while it’s running, and when you run the following command:
@@ -268,7 +291,10 @@ Custom endpoints must be transpiled and moved to the `dist` directory. This happ
npm run build
```
-## What’s Next
+---
-- Check out the available [Admin](https://docs.medusajs.com/api/admin/) and [Storefront](https://docs.medusajs.com/api/store/) APIs.
-- Learn how to create a [Service](./../services/create-service.md).
+## See Also
+
+- [Storefront API Reference](/api/store)
+- [Admin API Reference](/api/admin)
+- [Create a Service](./../services/create-service.md).
diff --git a/docs/content/advanced/backend/entities/index.md b/docs/content/advanced/backend/entities/index.md
index 89d63127e6..c7abea1ea1 100644
--- a/docs/content/advanced/backend/entities/index.md
+++ b/docs/content/advanced/backend/entities/index.md
@@ -6,15 +6,15 @@ In this document, you’ll learn how you can create an [Entity](overview.md).
To create an entity, create a TypeScript file in `src/models`. For example, here’s a `Post` entity defined in the file `src/models/post.ts`:
-```tsx title=src/models/post.ts
-import { BeforeInsert, Column, Entity, PrimaryColumn } from "typeorm";
-import { BaseEntity} from "@medusajs/medusa";
+```ts title=src/models/post.ts
+import { BeforeInsert, Column, Entity, PrimaryColumn } from "typeorm"
+import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"
@Entity()
export class Post extends BaseEntity {
- @Column({type: 'varchar'})
- title: string | null;
+ @Column({ type: "varchar" })
+ title: string | null
@BeforeInsert()
private beforeInsert(): void {
@@ -31,12 +31,12 @@ To generate an ID for your entity that matches the IDs generated for Medusa’s
If you want the entity to also be soft deletable then it should extend `SoftDeletableEntity` instead:
-```tsx
-import { SoftDeletableEntity } from "@medusajs/medusa";
+```ts
+import { SoftDeletableEntity } from "@medusajs/medusa"
@Entity()
export class Post extends SoftDeletableEntity {
- //...
+ // ...
}
```
@@ -52,7 +52,7 @@ You can learn more about Migrations, how to create them, and how to run them in
Entities data can be easily accessed and modified using Typeorm [Repositories](https://typeorm.io/working-with-repository). To create a repository, create a file in `src/repositories`. For example, here’s a repository `PostRepository` created in `src/repositories/post.ts`:
-```tsx title=src/repositories/post.ts
+```ts title=src/repositories/post.ts
import { EntityRepository, Repository } from "typeorm"
import { Post } from "../models/post"
@@ -69,6 +69,8 @@ Be careful with your file names as it can cause unclear errors in Typeorm. Make
:::
+---
+
## Access a Custom Entity
:::note
@@ -83,24 +85,25 @@ npm run build
You can access your custom entity data in the database in services or subscribers using the repository. For example, here’s a service that lists all posts:
-```tsx
-import { TransactionBaseService } from '@medusajs/medusa';
+```ts
+import { TransactionBaseService } from "@medusajs/medusa"
class PostService extends TransactionBaseService {
constructor({ postRepository, manager }) {
- super({ postRepository, manager });
+ super({ postRepository, manager })
- this.postRepository = postRepository;
- this.manager_ = manager;
+ this.postRepository = postRepository
+ this.manager_ = manager
}
async list() {
- const postRepository = this.manager_.getCustomRepository(this.postRepository);
- return await postRepository.find();
+ const postRepository = this.manager_
+ .getCustomRepository(this.postRepository)
+ return await postRepository.find()
}
}
-export default PostService;
+export default PostService
```
In the constructor, you can use dependency injection to get access to instances of services and repositories. Here, you initialize class fields `postRepository` and `manager`. The `manager` is a [Typeorm Entity Manager](https://typeorm.io/working-with-entity-manager).
@@ -121,12 +124,14 @@ This same usage of repositories can be done in subscribers as well.
To delete soft-deletable entities that extend the `SoftDeletableEntity` class, you can use the repository method `softDelete` method:
-```tsx
-await postRepository.softDelete(post.id);
+```ts
+await postRepository.softDelete(post.id)
```
-## What’s Next
+---
-- Check out Medusa's entities in the [Entities' reference](../../../references/entities/classes/Address.md).
-- Learn about [migrations](../migrations/overview.md).
-- Learn more about [Services](../services/create-service.md) and how to use them.
+## See Also
+
+- [Entities' reference](../../../references/entities/classes/Address.md)
+- [Migrations Overview](../migrations/overview.md)
+- [Create a Services](../services/create-service.md)
diff --git a/docs/content/advanced/backend/entities/overview.md b/docs/content/advanced/backend/entities/overview.md
index 8b32de6193..550e80da20 100644
--- a/docs/content/advanced/backend/entities/overview.md
+++ b/docs/content/advanced/backend/entities/overview.md
@@ -10,13 +10,17 @@ Aside from Medusa’s core entities, you can also create your own entities to us
Entities are TypeScript files and they are based on [Typeorm’s Entities](https://typeorm.io/entities) and use Typeorm decorators.
+---
+
## Base Entities
All entities must extend either the `BaseEntity` or `SoftDeletableEntity` classes. The `BaseEntity` class holds common columns including the `id`, `created_at`, and `updated_at` columns.
The `SoftDeletableEntity` class extends the `BaseEntity` class and adds another column `deleted_at`. If an entity can be soft deleted, meaning that a row in it can appear to the user as deleted but still be available in the database, it should extend `SoftDeletableEntity`.
-## What's Next
+---
-- Learn [how to create an entity](./index.md).
-- Check out Medusa's entities in the [Entities' reference](../../../references/entities/classes/Address.md).
\ No newline at end of file
+## See Also
+
+- [Create an entity](./index.md)
+- [Entities' reference](../../../references/entities/classes/Address.md)
\ No newline at end of file
diff --git a/docs/content/advanced/backend/feature-flags/toggle.md b/docs/content/advanced/backend/feature-flags/toggle.md
index a1f5a6904c..69cebd2c62 100644
--- a/docs/content/advanced/backend/feature-flags/toggle.md
+++ b/docs/content/advanced/backend/feature-flags/toggle.md
@@ -8,6 +8,8 @@ Feature flags are used in Medusa to guard beta features that aren’t ready for
To use these beta features, you must enable their feature flags.
+---
+
## Available Feature Flags
You can view a list of available feature flags that you can toggle in [the Medusa GitHub mono-repository](https://github.com/medusajs/medusa/tree/master/packages/medusa/src/loaders/feature-flags). In each feature flag file, you can find the default value of the feature flag, its name, environment variable name, and more.
@@ -18,6 +20,8 @@ If a feature flag is enabled/disabled by default, you don’t need to manually e
:::
+---
+
## Enable Feature Flags
:::caution
@@ -47,9 +51,9 @@ For example, to enable the Tax-Inclusive Pricing beta feature, add the following
```jsx title=medusa-config.js
module.exports = {
featureFlags: {
- tax_inclusive_pricing: true
+ tax_inclusive_pricing: true,
},
- //...
+ // ...
}
```
@@ -73,6 +77,8 @@ You can learn more about migrations in this documentation.
:::
+---
+
## Disable Feature Flags
Disabling feature flags follows the same process as enabling the feature flags. All you have to do is change the value in the environment variables or the server settings to `false`.
@@ -85,7 +91,9 @@ If you had the feature flag previously enabled, and you want to disable this fea
You can follow [this documentation to learn how to revert the last migration you ran](https://docs.medusajs.com/cli/reference#migrations).
-## What’s Next
+---
-- Learn more about [Migrations](../migrations/overview.md).
-- Learn how to [configure your Medusa server](../../../usage/configurations.md).
+## See Also
+
+- [Migrations Overview](../migrations/overview.md).
+- [Configure your Medusa server](../../../usage/configurations.md).
diff --git a/docs/content/advanced/backend/migrations/index.md b/docs/content/advanced/backend/migrations/index.md
index f555afdbf5..784bb8a317 100644
--- a/docs/content/advanced/backend/migrations/index.md
+++ b/docs/content/advanced/backend/migrations/index.md
@@ -20,12 +20,16 @@ You can alternatively use Typeorm's `generate` command to generate a Migration f
:::
+---
+
## Write Migration File
The migration file contains the necessary commands to create the database columns, foreign keys, and more.
You can learn more about writing the migration file in You can learn more about writing migrations in [Typeorm’s Documentation](https://typeorm.io/migrations).
+---
+
## Build Files
Before you can run the migrations you need to run the build command to transpile the TypeScript files to JavaScript files:
@@ -34,6 +38,8 @@ Before you can run the migrations you need to run the build command to transpile
npm run build
```
+---
+
## Run Migration
The last step is to run the migration with the command detailed earlier
@@ -44,6 +50,8 @@ medusa migrations run
If you check your database now you should see that the change defined by the migration has been applied successfully.
+---
+
## What’s Next
-- Learn more about [setting up your development server](../../../tutorial/0-set-up-your-development-environment.mdx).
+- [Set up your development server](../../../tutorial/0-set-up-your-development-environment.mdx).
diff --git a/docs/content/advanced/backend/migrations/overview.md b/docs/content/advanced/backend/migrations/overview.md
index eaee22ae25..743991da6d 100644
--- a/docs/content/advanced/backend/migrations/overview.md
+++ b/docs/content/advanced/backend/migrations/overview.md
@@ -22,6 +22,8 @@ Migrations are used to apply changes to the database schema. However, there are
:::
+---
+
## How to Run Migrations
Migrations in Medusa can be done in one of two ways:
@@ -48,7 +50,9 @@ npm run seed
This will use the underlying `seed` command provided by Medusa's CLI to seed your database with data from the file `data/seed.json` on your Medusa server.
-## What's Next
+---
-- Learn [how to create a migration](index.md)
-- Learn more about [setting up your development server](../../../tutorial/set-up-your-development-environment).
+## See Also
+
+- [Create a migration](index.md)
+- [Set up your development environment](../../../tutorial/set-up-your-development-environment)
diff --git a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md b/docs/content/advanced/backend/notification/how-to-create-notification-provider.md
index 395ea0ac47..ede8131a57 100644
--- a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md
+++ b/docs/content/advanced/backend/notification/how-to-create-notification-provider.md
@@ -10,10 +10,12 @@ If you’re unfamiliar with the Notification architecture in Medusa, it is recom
## Prerequisites
-Before you start creating a Notification Provider, you need to install a [Medusa server](../../../quickstart/quick-start.md).
+Before you start creating a Notification Provider, you need to install a [Medusa server](../../../quickstart/quick-start.mdx).
You also need to [setup Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with the Medusa server](../../../usage/configurations.md#redis).
+---
+
## Create a Notification Provider
Creating a Notification Provider is as simple as creating a TypeScript or JavaScript file in `src/services`. The name of the file is the name of the provider (for example, `sendgrid.ts`). A Notification Provider is essentially a Service that extends the `AbstractNotificationService` from `@medusajs/medusa`.
@@ -21,23 +23,39 @@ Creating a Notification Provider is as simple as creating a TypeScript or JavaS
For example, create the file `src/services/email-sender.ts` with the following content:
```ts title=src/services/email-sender.ts
-import { AbstractNotificationService } from "@medusajs/medusa";
-import { EntityManager } from "typeorm";
+import { AbstractNotificationService } from "@medusajs/medusa"
+import { EntityManager } from "typeorm"
class EmailSenderService extends AbstractNotificationService {
- protected manager_: EntityManager;
- protected transactionManager_: EntityManager;
+ protected manager_: EntityManager
+ protected transactionManager_: EntityManager
- sendNotification(event: string, data: unknown, attachmentGenerator: unknown): Promise<{ to: string; status: string; data: Record; }> {
- throw new Error("Method not implemented.");
+ sendNotification(
+ event: string,
+ data: unknown,
+ attachmentGenerator: unknown
+ ): Promise<{
+ to: string;
+ status: string;
+ data: Record;
+ }> {
+ throw new Error("Method not implemented.")
}
- resendNotification(notification: unknown, config: unknown, attachmentGenerator: unknown): Promise<{ to: string; status: string; data: Record; }> {
- throw new Error("Method not implemented.");
+ resendNotification(
+ notification: unknown,
+ config: unknown,
+ attachmentGenerator: unknown
+ ): Promise<{
+ to: string;
+ status: string;
+ data: Record;
+ }> {
+ throw new Error("Method not implemented.")
}
}
-export default EmailSenderService;
+export default EmailSenderService
```
Where `EmailSenderService` is the name of your Notification Provider Service.
@@ -61,7 +79,10 @@ The value of this property is also used later when you want to subscribe the Not
For example, in the class you created in the previous code snippet you can add the following property:
```ts
-static identifier = "email-sender";
+class EmailSenderService extends AbstractNotificationService {
+ static identifier = "email-sender"
+ // ...
+}
```
### constructor
@@ -81,23 +102,26 @@ You can learn more about plugins and how to create them in the [Plugins](../plug
Continuing on with the previous example, if you want to use the [`OrderService`](../../../references/services/classes/OrderService.md) later when sending notifications, you can inject it into the constructor:
```ts
-import { AbstractNotificationService, OrderService } from "@medusajs/medusa";
+import {
+ AbstractNotificationService,
+ OrderService,
+} from "@medusajs/medusa"
class EmailSenderService extends AbstractNotificationService {
- protected manager_: EntityManager;
- protected transactionManager_: EntityManager;
- static identifier = "email-sender";
- protected orderService: OrderService;
+ protected manager_: EntityManager
+ protected transactionManager_: EntityManager
+ static identifier = "email-sender"
+ protected orderService: OrderService
constructor(container, options) {
- super(container);
- //you can access options here in case you're
- //using a plugin
+ super(container)
+ // you can access options here in case you're
+ // using a plugin
- this.orderService = container.orderService;
+ this.orderService = container.orderService
}
- //...
+ // ...
}
```
@@ -127,23 +151,34 @@ This method must return an object containing two properties:
Continuing with the previous example you can have the following implementation of the `sendNotification` method:
```ts
-async sendNotification(event: string, data: any, attachmentGenerator: unknown): Promise<{ to: string; status: string; data: Record; }> {
- if (event === 'order.placed') {
- //retrieve order
- const order = await this.orderService.retrieve(data.id);
- //TODO send email
+class EmailSenderService extends AbstractNotificationService {
+ // ...
+ async sendNotification(
+ event: string,
+ data: any,
+ attachmentGenerator: unknown
+ ): Promise<{
+ to: string;
+ status: string;
+ data: Record;
+ }> {
+ if (event === "order.placed") {
+ // retrieve order
+ const order = await this.orderService.retrieve(data.id)
+ // TODO send email
- console.log('Notification sent');
- return {
- to: order.email,
- status: 'done',
- data: {
- //any data necessary to send the email
- //for example:
- subject: 'You placed a new order!',
- items: order.items
+ console.log("Notification sent")
+ return {
+ to: order.email,
+ status: "done",
+ data: {
+ // any data necessary to send the email
+ // for example:
+ subject: "You placed a new order!",
+ items: order.items,
+ },
}
- };
+ }
}
}
```
@@ -178,17 +213,29 @@ Similarly to the `sendNotification` method, this method must return an object co
Continuing with the previous example you can have the following implementation of the `resendNotification` method:
```ts
-async resendNotification(notification: any, config: any, attachmentGenerator: unknown): Promise<{ to: string; status: string; data: Record; }> {
- //check if the receiver of the notification should be changed
- const to: string = config.to ? config.to : notification.to;
+class EmailSenderService extends AbstractNotificationService {
+ // ...
+ async resendNotification(
+ notification: any,
+ config: any,
+ attachmentGenerator: unknown
+ ): Promise<{
+ to: string;
+ status: string;
+ data: Record;
+ }> {
+ // check if the receiver of the notification should be changed
+ const to: string = config.to ? config.to : notification.to
- //TODO resend the notification using the same data that is saved under notification.data
+ // TODO resend the notification using the same data
+ // that is saved under notification.data
- console.log('Notification resent');
- return {
- to,
- status: 'done',
- data: notification.data //you can also make changes to the data
+ console.log("Notification resent")
+ return {
+ to,
+ status: "done",
+ data: notification.data, // you can also make changes to the data
+ }
}
}
```
@@ -205,6 +252,8 @@ The `to` and `data` properties are used in the `NotificationService` in Medusa
:::
+---
+
## Create a Subscriber
After creating your Notification Provider Service, you must create a Subscriber that registers this Service as a notification handler of events.
@@ -220,11 +269,12 @@ Following the previous example, to make sure the `email-sender` Notification Pro
```ts title=src/subscribers/notification.js
class NotificationSubscriber {
constructor({ notificationService }) {
- notificationService.subscribe('order.placed', 'email-sender');
+ notificationService.subscribe("order.placed", "email-sender")
}
+ // ...
}
-export default NotificationSubscriber;
+export default NotificationSubscriber
```
This subscriber accesses the `notificationService` using dependency injection. The `notificationService` contains a `subscribe` method that accepts 2 parameters. The first one is the name of the event to subscribe to, and the second is the identifier of the Notification Provider that is subscribing to that event.
@@ -235,6 +285,8 @@ Notice that the value of the `identifier` static property defined in the `EmailS
:::
+---
+
## Test Sending Notifications with your Notification Provider
Make sure you've configured Redis with your Medusa server as explained in the Prerequisites section and that the Redis service is running.
@@ -249,12 +301,14 @@ Then, place an order either using the [REST APIs](https://docs.medusajs.com/api/
:::tip
-If you don’t have a storefront installed you can get started with either the [Next.js](../../../starters/nextjs-medusa-starter.md) or [Gatsby](../../../starters/gatsby-medusa-starter.md) starter storefronts in minutes.
+If you don’t have a storefront installed you can get started with either the [Next.js](../../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../../starters/gatsby-medusa-starter.mdx) starter storefronts in minutes.
:::
After placing an order, you can see in your console the message “Notification Sent”. If you added your own notification sending logic, you should receive an email or alternatively the type of notification you’ve set up.
+---
+
## Test Resending Notifications with your Notification Provider
To test resending a notification, first, retrieve the ID of the notification you just sent using the [List Notifications admin endpoint](https://docs.medusajs.com/api/admin/#tag/Notification/operation/GetNotifications). You can pass as a body parameter the `to` or `event_name` parameters to filter out the notification you just sent.
@@ -273,9 +327,12 @@ Then, send a request to the [Resend Notification](https://docs.medusajs.com/api/
This request returns the same notification object as the List Notifications endpoint, but it now has a new object in the `resends` array. This is the resent notification. If you supplied a `to` parameter in the request body, you should see its value in the `to` property of the resent notification object.
-## What’s Next
+---
-- Check out the [list of events](../subscribers/events-list.md) you can listen to.
-- Check out the [SendGrid](../../../add-plugins/sendgrid.mdx) plugin for easy integration of email notifications.
-- Learn how to [create your own plugin](../plugins/create.md).
-- Learn more about [Subscribers](../subscribers/create-subscriber.md) and [Services](../services/create-service.md).
+## See Also
+
+- [Events reference](../subscribers/events-list.md)
+- [SendGrid Plugin](../../../add-plugins/sendgrid.mdx)
+- [Create a Subscriber](../subscribers/create-subscriber.md)
+- [Create a Service](../services/create-service.md)
+- [Create a Plugin](../plugins/create.md)
diff --git a/docs/content/advanced/backend/notification/overview.md b/docs/content/advanced/backend/notification/overview.md
index 4183049aba..dd43920783 100644
--- a/docs/content/advanced/backend/notification/overview.md
+++ b/docs/content/advanced/backend/notification/overview.md
@@ -8,6 +8,8 @@ Medusa provides a Notification API to mainly handle sending and resending notifi
The Notification architecture is made up of two main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification.
+---
+
## Notification Provider
A Notification Provider is a provider that handles sending and resending of notifications. You can either create and integrate your own provider or install a Notification Provider through a third-party plugin.
@@ -32,6 +34,8 @@ The `NotificationProvider` entity only has 2 attributes: `id` and `is_installed`
If you installed a Notification provider and then removed the Service files or plugin that registered the Notification Provider, the Notification Provider remains in your database, but the value of the `is_installed` field changes to `false`.
+---
+
## Notification
A notification is a form of an alert sent to the customers or users to inform them of an action that has occurred. For example, if an order is placed, the notification, in this case, can be an email that confirms their order and lists the order details.
@@ -67,6 +71,8 @@ You can also access the specific resource using the `resource_id` property, whic
The `Notification` entity also includes properties related to the receiver of the Notification. In case the receiver is a customer, the `customer_id` property is used to identify which customer.
+---
+
## Automating Flows with Notifications
With Medusa you can create notifications as a reaction to a wide spectrum of events, allowing you to automate communication and processes.
@@ -78,10 +84,13 @@ An example of a flow that can be implemented using Medusa's Notification API is
- The customer returns the items triggering the `return.recieved` event.
- The Notification Provider listens to the `return.received` event and sends an email to the customer with confirmation that their items have been received and that a refund has been issued.
-## What’s Next
+---
+
+## See Also
+
+- [Create a Notification Provider](how-to-create-notification-provider.md)
+- [Events reference](../subscribers/events-list.md)
+- [SendGrid Plugin](../../../add-plugins/sendgrid.mdx)
+- [Subscribers Overview](../subscribers/create-subscriber.md)
+- [Services Overview](../services/create-service.md)
-- Learn how to [create your own Notification Provider](how-to-create-notification-provider.md).
-- Check out the [list of events](../subscribers/events-list.md) in Medusa.
-- Check the [`NotificationService`](../../../references/services/classes/NotificationService.md) API reference for more details on how it works.
-- Check out the [SendGrid](../../../add-plugins/sendgrid.mdx) Notification plugin.
-- Learn more about [Subscribers](../subscribers/create-subscriber.md) and [Services](../services/create-service.md) in Medusa.
diff --git a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md
index efb27405ad..da374726c3 100644
--- a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md
+++ b/docs/content/advanced/backend/payment/how-to-create-payment-provider.md
@@ -42,57 +42,68 @@ These methods are used at different points in the Checkout flow as well as when
+---
+
## Create a Payment Provider
The first step to create a payment provider is to create a JavaScript or TypeScript file in `src/services`. The file's name should be the name of the payment provider.
For example, create the file `src/services/my-payment.ts` with the following content:
+
+
```ts title=src/services/my-payment.ts
-import { AbstractPaymentService, Cart, Data, Payment, PaymentSession, PaymentSessionStatus, TransactionBaseService } from "@medusajs/medusa"
-import { EntityManager } from "typeorm";
+import {
+ AbstractPaymentService,
+ Cart, Data, Payment, PaymentSession,
+ PaymentSessionStatus, TransactionBaseService,
+} from "@medusajs/medusa"
+import { EntityManager } from "typeorm"
class MyPaymentService extends AbstractPaymentService {
- protected manager_: EntityManager;
- protected transactionManager_: EntityManager;
+ protected manager_: EntityManager
+ protected transactionManager_: EntityManager
getPaymentData(paymentSession: PaymentSession): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
updatePaymentData(paymentSessionData: Data, data: Data): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
createPayment(cart: Cart): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
retrievePayment(paymentData: Data): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
updatePayment(paymentSessionData: Data, cart: Cart): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
- authorizePayment(paymentSession: PaymentSession, context: Data): Promise<{ data: Data; status: PaymentSessionStatus; }> {
- throw new Error("Method not implemented.");
+ authorizePayment(
+ paymentSession: PaymentSession,
+ context: Data
+ ): Promise<{ data: Data; status: PaymentSessionStatus; }> {
+ throw new Error("Method not implemented.")
}
capturePayment(payment: Payment): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
refundPayment(payment: Payment, refundAmount: number): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
cancelPayment(payment: Payment): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
deletePayment(paymentSession: PaymentSession): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
getStatus(data: Data): Promise {
- throw new Error("Method not implemented.");
+ throw new Error("Method not implemented.")
}
}
-export default MyPaymentService;
+export default MyPaymentService
```
Where `MyPaymentService` is the name of your Payment Provider service. For example, Stripe’s Payment Provider Service is called `StripeProviderService`.
@@ -121,10 +132,16 @@ You can also use the constructor to initialize your integration with the third-p
Additionally, if you’re creating your Payment Provider as an external plugin to be installed on any Medusa server and you want to access the options added for the plugin, you can access it in the constructor. The options are passed as a second parameter:
+
+
```ts
-constructor({ productService }, options) {
- super();
- //you can access options here
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ constructor({ productService }, options) {
+ super()
+ // you can access options here
+ }
+ // ...
}
```
@@ -138,15 +155,20 @@ This method must return an object that is going to be stored in the `data` field
An example of a minimal implementation of `createPayment` that does not interact with any third-party providers:
+
+
```ts
import { Cart, Data } from "@medusajs/medusa"
-//...
+// ...
-async createPayment(cart: Cart): Promise {
- return {
- id: 'test-payment',
- status: 'pending'
- };
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async createPayment(cart: Cart): Promise {
+ return {
+ id: "test-payment",
+ status: "pending",
+ }
+ }
}
```
@@ -160,12 +182,17 @@ This method must return an object containing the data from the third-party provi
An example of a minimal implementation of `retrievePayment` where you don’t need to interact with the third-party provider:
+
+
```ts
import { Data } from "@medusajs/medusa"
-//...
+// ...
-async retrievePayment(paymentData: Data): Promise {
- return {};
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async retrievePayment(paymentData: Data): Promise {
+ return {}
+ }
}
```
@@ -187,12 +214,17 @@ This method returns a string that represents the status. The status must be one
An example of a minimal implementation of `getStatus` where you don’t need to interact with the third-party provider:
+
+
```ts
import { Data, PaymentSessionStatus } from "@medusajs/medusa"
-//...
+// ...
-async getStatus(data: Data): Promise {
- return PaymentSessionStatus.AUTHORIZED;
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async getStatus(data: Data): Promise {
+ return PaymentSessionStatus.AUTHORIZED
+ }
}
```
@@ -220,12 +252,17 @@ This method must return an object that will be stored in the `data` field of the
An example of a minimal implementation of `updatePayment` that does not need to make any updates on the third-party provider or the `data` field of the Payment Session:
-```ts
-import { Cart, Data } from "@medusajs/medusa";
-//...
+
-async updatePayment(paymentSessionData: Data, cart: Cart): Promise {
- return paymentSessionData;
+```ts
+import { Cart, Data } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async updatePayment(paymentSessionData: Data, cart: Cart): Promise {
+ return paymentSessionData
+ }
}
```
@@ -241,12 +278,20 @@ This method must return an object that will be stored in the `data` field of the
An example of a minimal implementation of `updatePaymentData` that returns the `updatedData` passed in the body of the request as-is to update the `data` field of the Payment Session.
-```ts
-import { Data } from "@medusajs/medusa";
-//...
+
-async updatePaymentData(paymentSessionData: Data, updatedData: Data): Promise {
- return updatedData;
+```ts
+import { Data } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async updatePaymentData(
+ paymentSessionData: Data,
+ updatedData: Data
+ ): Promise {
+ return updatedData
+ }
}
```
@@ -265,12 +310,17 @@ You can use this method to interact with the third-party provider to delete data
An example of a minimal implementation of `deletePayment` where no interaction with a third-party provider is required:
-```ts
-import { PaymentSession } from "@medusajs/medusa";
-//...
+
-async deletePayment(paymentSession: PaymentSession): Promise {
- return;
+```ts
+import { PaymentSession } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async deletePayment(paymentSession: PaymentSession): Promise {
+ return
+ }
}
```
@@ -303,17 +353,29 @@ You can utilize this method to interact with the third-party provider and perfor
An example of a minimal implementation of `authorizePayment` that doesn’t need to interact with any third-party provider:
-```ts
-import { Data, PaymentSession, PaymentSessionStatus } from "@medusajs/medusa";
-//...
+
-async authorizePayment(paymentSession: PaymentSession, context: Data): Promise<{ data: Data; status: PaymentSessionStatus; }> {
- return {
- status: PaymentSessionStatus.AUTHORIZED,
- data: {
- id: 'test'
+```ts
+import {
+ Data,
+ PaymentSession,
+ PaymentSessionStatus,
+} from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async authorizePayment(
+ paymentSession: PaymentSession,
+ context: Data
+ ): Promise<{ data: Data; status: PaymentSessionStatus; }> {
+ return {
+ status: PaymentSessionStatus.AUTHORIZED,
+ data: {
+ id: "test",
+ },
}
- };
+ }
}
```
@@ -327,12 +389,17 @@ This method must return an object to be stored in the `data` field of the Paymen
An example of a minimal implementation of `getPaymentData`:
-```ts
-import { Data, PaymentSession } from "@medusajs/medusa";
-//...
+
-async getPaymentData(paymentSession: PaymentSession): Promise {
- return paymentSession.data;
+```ts
+import { Data, PaymentSession } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async getPaymentData(paymentSession: PaymentSession): Promise {
+ return paymentSession.data
+ }
}
```
@@ -350,14 +417,19 @@ This method must return an object that will be stored in the `data` field of the
An example of a minimal implementation of `capturePayment` that doesn’t need to interact with a third-party provider:
-```ts
-import { Data, Payment } from "@medusajs/medusa";
-//...
+
-async capturePayment(payment: Payment): Promise {
- return {
- status: 'captured'
- };
+```ts
+import { Data, Payment } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async capturePayment(payment: Payment): Promise {
+ return {
+ status: "captured",
+ }
+ }
}
```
@@ -375,13 +447,21 @@ This method must return an object that is stored in the `data` field of the Paym
An example of a minimal implementation of `refundPayment` that doesn’t need to interact with a third-party provider:
-```ts
-import { Data, Payment } from "@medusajs/medusa";
-//...
+
-async refundPayment(payment: Payment, refundAmount: number): Promise {
- return {
- id: 'test'
+```ts
+import { Data, Payment } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async refundPayment(
+ payment: Payment,
+ refundAmount: number
+ ): Promise {
+ return {
+ id: "test",
+ }
}
}
```
@@ -403,17 +483,24 @@ This method must return an object that is stored in the `data` field of the Paym
An example of a minimal implementation of `cancelPayment` that doesn’t need to interact with a third-party provider:
-```ts
-import { Data, Payment } from "@medusajs/medusa";
-//...
+
-async cancelPayment(payment: Payment): Promise {
- return {
- id: 'test'
+```ts
+import { Data, Payment } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async cancelPayment(payment: Payment): Promise {
+ return {
+ id: "test",
+ }
}
}
```
+---
+
## Optional Methods
### retrieveSavedMethods
@@ -428,36 +515,43 @@ This method returns an array of saved payment methods retrieved from the third-p
:::note
-If you’re using Medusa’s [Next.js](../../../starters/nextjs-medusa-starter.md) or [Gatsby](../../../starters/gatsby-medusa-starter.md) storefront starters, note that the presentation of this method is not implemented. You’ll need to implement the UI and pages for this method based on your implementation and the provider you are using.
+If you’re using Medusa’s [Next.js](../../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../../starters/gatsby-medusa-starter.mdx) storefront starters, note that the presentation of this method is not implemented. You’ll need to implement the UI and pages for this method based on your implementation and the provider you are using.
:::
An example of the implementation of `retrieveSavedMethods` taken from Stripe’s Payment Provider:
+
+
```ts
import { Customer, Data } from "@medusajs/medusa"
-//...
+// ...
-/**
-* Fetches a customers saved payment methods if registered in Stripe.
-* @param {object} customer - customer to fetch saved cards for
-* @returns {Promise>} saved payments methods
-*/
-async retrieveSavedMethods(customer: Customer): Promise {
- if (customer.metadata && customer.metadata.stripe_id) {
- const methods = await this.stripe_.paymentMethods.list({
- customer: customer.metadata.stripe_id,
- type: "card",
- })
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ /**
+ * Fetches a customers saved payment methods if registered in Stripe.
+ * @param {object} customer - customer to fetch saved cards for
+ * @return {Promise>} saved payments methods
+ */
+ async retrieveSavedMethods(customer: Customer): Promise {
+ if (customer.metadata && customer.metadata.stripe_id) {
+ const methods = await this.stripe_.paymentMethods.list({
+ customer: customer.metadata.stripe_id,
+ type: "card",
+ })
- return methods.data
+ return methods.data
+ }
+
+ return Promise.resolve([])
}
-
- return Promise.resolve([])
}
```
-## What’s Next
+---
-- Check out the Payment Providers for [Stripe](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-stripe) and [PayPal](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-paypal) for implementation examples.
-- Learn more about the [frontend checkout flow](./../../storefront/how-to-implement-checkout-flow.mdx).
+## See Also
+
+- Implementation Examples: [Stripe](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-stripe) and [PayPal](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-paypal) payment providers.
+- [Implement checkout flow on the storefront](./../../storefront/how-to-implement-checkout-flow.mdx).
diff --git a/docs/content/advanced/backend/payment/overview.md b/docs/content/advanced/backend/payment/overview.md
index 82b0afd2bd..cfea8ef5b9 100644
--- a/docs/content/advanced/backend/payment/overview.md
+++ b/docs/content/advanced/backend/payment/overview.md
@@ -14,6 +14,8 @@ In Medusa, there are 3 main components in the payment architecture: Payment Prov
An important part in the Payment architecture to understand is the **Idempotency Key**. It’s a unique value that’s generated for a cart and is used to retry payments during checkout if they fail.
+---
+
## Payment Provider
A Payment Provider in Medusa is a method to handle payments in selected regions. It is not associated with a cart, customer, or order in particular. It provides the necessary implementation to create Payment Sessions and Payments, as well as authorize and capture payments, among other functionalities.
@@ -30,7 +32,7 @@ As a developer, you will mainly work with the Payment Provider when integrating
When you run your Medusa server, the Payment Provider will be registered on your server if it hasn’t been already.
-Once the Payment Provider is added to the server, the store operator will be able to choose on the [Medusa Admin](../../../admin/quickstart.md) the payment providers available in a region. These payment providers are shown to the customer at checkout to choose from and use.
+Once the Payment Provider is added to the server, the store operator will be able to choose on the [Medusa Admin](../../../admin/quickstart.mdx) the payment providers available in a region. These payment providers are shown to the customer at checkout to choose from and use.
:::caution
@@ -42,6 +44,8 @@ It’s important to choose a payment provider in the list of payment providers i
The [`PaymentProvider`](../../../references/entities/classes/PaymentProvider.md) entity only has 2 attributes: `is_installed` to indicate if the payment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Payment Provider service.
+---
+
## Payment Session
Payment Sessions are linked to a customer’s cart. Each Payment Session is associated with a payment provider that is available in the customer cart’s region.
@@ -80,6 +84,8 @@ The `status` attributes indicates the current status of the Payment Session. It
These statuses are important in the checkout flow to determine the current step the customer is at and which action should come next. For example, if there is an attempt to place the order but the status of the Payment Session is not `authorized`, an error will be thrown.
+---
+
## Payment
A Payment is used to represent the amount authorized for a customer’s purchase. It is associated with the order placed by the customer and will be used after that for all operations related to the order’s payment such as capturing or refunding the payment.
@@ -104,6 +110,8 @@ Similar to `PaymentSession`, `Payment` has a `data` attribute which is an objec
Additionally, `Payment` has the `captured_at` date-time attribute which is filled when the payment has been captured, and a `canceled_at` date-time attribute which is filled when the order has been canceled.
+---
+
## Idempotency Key
An Idempotency Key is a unique key associated with a cart. It is generated at the last step of checkout before authorization of the payment is attempted.
@@ -118,7 +126,9 @@ If then the request is interrupted for any reason or the payment fails, the clie
This prevents any payment issues from occurring with the customers and allows for secure retries of failed payments or interrupted connections.
-## What’s Next
+---
-- [Check out how the checkout flow is implemented on the frontend.](./../../storefront/how-to-implement-checkout-flow.mdx)
-- Check out payment plugins like [Stripe](../../../add-plugins/stripe.md), [Paypal](/add-plugins/paypal), and [Klarna](../../../add-plugins/klarna.md).
+## See Also
+
+- [Create a Payment Provider](./how-to-create-payment-provider.md)
+- [Implement the checkout flow in the storefront](./../../storefront/how-to-implement-checkout-flow.mdx)
diff --git a/docs/content/advanced/backend/plugins/create.md b/docs/content/advanced/backend/plugins/create.md
index c520e4c96a..f2f21a2886 100644
--- a/docs/content/advanced/backend/plugins/create.md
+++ b/docs/content/advanced/backend/plugins/create.md
@@ -16,6 +16,8 @@ If you run into any errors while installing the CLI tool, check out the [trouble
:::
+---
+
## Initialize Project
The recommended way to create a plugin is using the Medusa CLI. Run the following command to create a new Medusa project:
@@ -28,6 +30,8 @@ Where `medusa-plugin-custom` is the name of the plugin you’re creating. In Med
By convention, all plugin names start with `medusa` followed by a descriptive name of what the plugin does. For example, the Stripe plugin is named `medusa-payment-stripe`.
+---
+
## Changes to package.json
### Rename Project Name
@@ -145,6 +149,8 @@ npm install --save-dev cross-env
- `repository`: The repository that holds your plugin’s codebase.
- `keywords`: This should hold the keywords that are related to your plugin. It’s recommended that all plugins use the keywords `medusa-plugin` or `medusa`.
+---
+
## Develop your Plugin
Now, You can start developing your plugin. This can include adding services, endpoints, entities, or anything that's relevant to your plugin.
@@ -196,6 +202,8 @@ This guide doesn't cover how to create different files and components. If you’
- How to [create an entity](./../entities/index.md)
- How to [create a migration](../migrations/index.md)
+---
+
## Add Plugin Configuration
Plugins often allow developers that will later use them to enter their own configuration. For example, you can allow developers to specify the API key of a service you’re integrating.
@@ -204,7 +212,7 @@ To pass a plugin its configurations on a Medusa server, you have to add it to th
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-plugin-custom`,
options: {
@@ -217,19 +225,23 @@ const plugins = [
Then, you can have access to your plugin configuration in the constructor of services in your plugin:
```jsx title=src/service/test.ts
-//In a service in your plugin
-constructor({}, options) {
- //options contains plugin configurations
- this.name = options.name
+ // In a service in your plugin
+class MyService extends TransactionBaseService {
+ constructor(container, options) {
+ super(container)
+ // options contains plugin configurations
+ this.name = options.name
+ }
+ // ...
}
```
You can also have access to the configurations in endpoints in your plugin:
```jsx title=src/api/index.ts
-//in an endpoint in your plugin
+// in an endpoint in your plugin
export default (rootDirectory, options) => {
- //options contain the plugin configurations
+ // options contain the plugin configurations
const router = Router()
router.get("/hello-world", (req, res) => {
@@ -248,6 +260,8 @@ Make sure to include in the README of your plugin the configurations that can be
:::
+---
+
## Test Your Plugin
While you develop your plugin, you’ll need to test it on an actual Medusa server. This can be done by using the [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) command.
@@ -283,10 +297,10 @@ Then, add your plugin into the array of plugins in `medusa-config.js`:
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-plugin-custom`,
- //if your plugin has configurations
+ // if your plugin has configurations
options: {
name: "My Store",
},
@@ -354,6 +368,8 @@ It is safe to ignore any `cross-env: command not found` error you may receive.
:::
+---
+
## NPM Ignore File
Not all files that you use while developing your plugin are necessary to be published.
@@ -387,6 +403,8 @@ medusa-db.sql
develop.sh
```
+---
+
## Publish Plugin
Once you’re done developing your plugin you can publish the package on NPM’s registry so that other developers can benefit from it and use it.
@@ -439,6 +457,8 @@ Then, publish the new update:
npm publish
```
+---
+
## Add Plugin to Medusa’s Repository
All officially-supported plugins are available in the [`packages` directory of the Medusa GitHub repository](https://github.com/medusajs/medusa/tree/master/packages).
@@ -451,6 +471,8 @@ Before contributing to the Medusa repository, please check out the [contribution
:::
+---
+
## Install a Plugin
To install any published plugin, you can run the following command on any Medusa server project:
@@ -459,8 +481,10 @@ To install any published plugin, you can run the following command on any Medusa
npm install medusa-plugin-custom
```
-## What’s Next
+---
-- Check out [available Services in Medusa](references/services/../../../../../references/services/classes/AuthService.md) that you can use in your plugin.
-- Check out [available events](../subscribers/events-list.md) that you can listen to in Subscribers.
-- Check out [available official plugins](https://github.com/medusajs/medusa/tree/master/packages).
+## See Also
+
+- [Available official plugins](https://github.com/medusajs/medusa/tree/master/packages)
+- [Services reference](references/services/../../../../../references/services/classes/AuthService.md)
+- [Events reference](../subscribers/events-list.md)
diff --git a/docs/content/advanced/backend/plugins/overview.md b/docs/content/advanced/backend/plugins/overview.md
index aaad259683..2a3b68f267 100644
--- a/docs/content/advanced/backend/plugins/overview.md
+++ b/docs/content/advanced/backend/plugins/overview.md
@@ -14,6 +14,8 @@ An alternative approach is developing a custom way of handling payment on your e
Plugins run within the same process as the core Medusa server eliminating the need for extra server capacity, infrastructure, and maintenance. As a result, plugins can use all other services as dependencies and access the database.
+---
+
## Using Existing Plugins
### Official Plugins
@@ -48,7 +50,9 @@ If you’re installing an official plugin from the Medusa repository, you can fi
For community plugins, please refer to the installation instructions of that plugin to learn about any required configurations.
-## What’s Next
+---
-- Learn how to [create your own plugin](create.md).
-- Learn how to [create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md).
+## See Also
+
+- [Create your own plugin](create.md)
+- [Create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md)
diff --git a/docs/content/advanced/backend/price-lists/index.md b/docs/content/advanced/backend/price-lists/index.md
index 4784a019e9..f8b10cdba4 100644
--- a/docs/content/advanced/backend/price-lists/index.md
+++ b/docs/content/advanced/backend/price-lists/index.md
@@ -81,7 +81,7 @@ Since the line item belongs to a cart, there’s no need to pass the `region_id`
---
-## What’s Next
+## See Also
-- Learn more about [price selection strategies](../price-selection-strategy/index.md).
-- Learn [how to use the PriceList Admin APIs](./use-api.mdx).
+- [Price Selection Strategy Overview](../price-selection-strategy/index.md).
+- [Use the PriceList Admin APIs](./use-api.mdx).
diff --git a/docs/content/advanced/backend/price-lists/use-api.mdx b/docs/content/advanced/backend/price-lists/use-api.mdx
index 48bb7da30f..03b190f827 100644
--- a/docs/content/advanced/backend/price-lists/use-api.mdx
+++ b/docs/content/advanced/backend/price-lists/use-api.mdx
@@ -15,7 +15,7 @@ This document doesn't cover what price lists are and their basics. If you’re i
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.mdx) to get started.
### JS Client
@@ -37,6 +37,8 @@ When you create a price list, you can specify different conditions to control wh
In the body of your request, aside from the required fields, you can send the following fields to apply different conditions:
+
+
```js noReport
{
prices: [
@@ -70,28 +72,28 @@ For example, sending the following request creates a price list with two prices:
import { PriceListType } from "@medusajs/medusa"
medusa.admin.priceLists.create({
- name: 'New Price List',
- description: 'A new price list',
+ name: "New Price List",
+ description: "A new price list",
type: PriceListType.SALE,
- status: 'active',
+ status: "active",
prices: [
{
amount: 1000,
variant_id,
- currency_code: 'eur',
- max_quantity: 3
+ currency_code: "eur",
+ max_quantity: 3,
},
{
amount: 1500,
variant_id,
- currency_code: 'eur',
- min_quantity: 4
- }
- ]
+ currency_code: "eur",
+ min_quantity: 4,
+ },
+ ],
})
.then(({ price_list }) => {
- console.log(price_list.id);
-});
+ console.log(price_list.id)
+})
```
@@ -99,31 +101,31 @@ medusa.admin.priceLists.create({
```jsx
fetch(`/admin/price-lists`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- name: 'New Price List',
- description: 'A new price list',
- type: 'sale',
- status: 'active',
+ name: "New Price List",
+ description: "A new price list",
+ type: "sale",
+ status: "active",
prices: [
{
amount: 1000,
variant_id,
- currency_code: 'eur',
- max_quantity: 3
+ currency_code: "eur",
+ max_quantity: 3,
},
{
amount: 1500,
variant_id,
- currency_code: 'eur',
- min_quantity: 4
- }
- ]
- })
+ currency_code: "eur",
+ min_quantity: 4,
+ },
+ ],
+ }),
})
.then((response) => response.json())
.then(({ price_list }) => {
@@ -179,8 +181,8 @@ You can retrieve all of a price list’s details using the Get a Price List endp
```jsx
medusa.admin.priceLists.retrieve(priceListId)
.then(({ price_list }) => {
- console.log(price_list.id);
-});
+ console.log(price_list.id)
+})
```
@@ -188,7 +190,7 @@ medusa.admin.priceLists.retrieve(priceListId)
```jsx
fetch(`/admin/price-lists/${priceListId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ price_list }) => {
@@ -199,7 +201,7 @@ fetch(`/admin/price-lists/${priceListId}`, {
-```jsx
+```bash
curl -L -X GET '/admin/price-lists/{id}' \
-H 'Authorization: Bearer '
```
@@ -220,11 +222,11 @@ For example, by sending the following request the end date of the price list wil
```jsx
medusa.admin.priceLists.update(priceListId, {
- ends_at: '2022-10-11'
+ ends_at: "2022-10-11",
})
.then(({ price_list }) => {
- console.log(price_list.id);
-});
+ console.log(price_list.id)
+})
```
@@ -232,14 +234,14 @@ medusa.admin.priceLists.update(priceListId, {
```jsx
fetch(`/admin/price-lists/${priceListId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- ends_at: '2022-10-11'
- })
+ ends_at: "2022-10-11",
+ }),
})
.then((response) => response.json())
.then(({ price_list }) => {
@@ -287,13 +289,13 @@ medusa.admin.priceLists.addPrices(priceListId, {
{
amount: 1200,
variant_id,
- currency_code: 'eur'
- }
- ]
+ currency_code: "eur",
+ },
+ ],
})
.then(({ price_list }) => {
- console.log(price_list.id);
-});
+ console.log(price_list.id)
+})
```
@@ -301,20 +303,20 @@ medusa.admin.priceLists.addPrices(priceListId, {
```jsx
fetch(`/admin/price-lists/${priceListId}/prices/batch`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
prices: [
{
amount: 1200,
variant_id,
- currency_code: 'eur'
- }
- ]
- })
+ currency_code: "eur",
+ },
+ ],
+ }),
})
.then((response) => response.json())
.then(({ price_list }) => {
@@ -357,18 +359,23 @@ You can delete all the prices of a product’s variants using the [Delete Produc
```jsx
medusa.admin.priceLists.deleteProductPrices(priceListId, productId)
.then(({ ids, object, deleted }) => {
- console.log(ids.length);
-});
+ console.log(ids.length)
+})
```
+
+
```jsx
-fetch(`/admin/price-lists/${priceListId}/products/${productId}/prices`, {
- method: 'DELETE',
- credentials: 'include',
-})
+fetch(
+ `/admin/price-lists/${priceListId}/products/${productId}/prices`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ }
+)
.then((response) => response.json())
.then(({ ids, object, deleted }) => {
console.log(ids.length)
@@ -398,18 +405,23 @@ You can delete all the prices of a variant using the [Delete Variant Prices](htt
```jsx
medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId)
.then(({ ids, object, deleted }) => {
- console.log(ids);
-});
+ console.log(ids)
+})
```
+
+
```jsx
-fetch(`/admin/price-lists/${priceListId}/variants/${variantId}/prices`, {
- method: 'DELETE',
- credentials: 'include',
-})
+fetch(
+ `/admin/price-lists/${priceListId}/variants/${variantId}/prices`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ }
+)
.then((response) => response.json())
.then(({ ids, object, deleted }) => {
console.log(ids.length)
@@ -419,7 +431,7 @@ fetch(`/admin/price-lists/${priceListId}/variants/${variantId}/price
-```jsx
+```bash
curl -L -X DELETE '/admin/price-lists//variants//prices' \
-H 'Authorization: Bearer '
```
@@ -441,8 +453,8 @@ You can delete a price list, and subsequently all prices defined in it, using th
```jsx
medusa.admin.priceLists.delete(priceListId)
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -450,8 +462,8 @@ medusa.admin.priceLists.delete(priceListId)
```jsx
fetch(`/admin/price-lists/${priceListId}`, {
- method: 'DELETE',
- credentials: 'include',
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
@@ -462,7 +474,7 @@ fetch(`/admin/price-lists/${priceListId}`, {
-```jsx
+```bash
curl -L -X DELETE '/admin/price-lists/' \
-H 'Authorization: Bearer '
```
@@ -474,7 +486,7 @@ This request returns the ID of the deleted price list.
---
-## What’s Next
+## See Also
-- Learn more about [price lists](./index.md).
-- Learn how the [price selection strategy works](../price-selection-strategy/index.md).
\ No newline at end of file
+- [Price Lists Overview](./index.md).
+- [Price Selection Strategy Overview](../price-selection-strategy/index.md).
diff --git a/docs/content/advanced/backend/price-selection-strategy/index.md b/docs/content/advanced/backend/price-selection-strategy/index.md
index 4d552d81d5..1d4adcc7a7 100644
--- a/docs/content/advanced/backend/price-selection-strategy/index.md
+++ b/docs/content/advanced/backend/price-selection-strategy/index.md
@@ -60,7 +60,7 @@ The context that is passed to the `calculateVariantPrice` method is an object th
---
-## What’s Next
+## See Also
-- Learn [how to override the price selection strategy](./override.md).
-- Learn more about [price lists](./../price-lists/index.md).
+- [Override the Price Selection Strategy](./override.md)
+- [Price Lists Overview](./../price-lists/index.md)
diff --git a/docs/content/advanced/backend/price-selection-strategy/override.md b/docs/content/advanced/backend/price-selection-strategy/override.md
index a1274a2785..ad21f5949d 100644
--- a/docs/content/advanced/backend/price-selection-strategy/override.md
+++ b/docs/content/advanced/backend/price-selection-strategy/override.md
@@ -114,6 +114,6 @@ Then, try out your strategy using any of the [Products](https://docs.medusajs.co
---
-## What’s Next
+## See Also
-- Learn more about [price list selection strategy](./index.md).
+- [Price List Selection Strategy Overview](./index.md)
diff --git a/docs/content/advanced/backend/regions/overview.md b/docs/content/advanced/backend/regions/overview.md
index d374500bbb..5bf329ba4c 100644
--- a/docs/content/advanced/backend/regions/overview.md
+++ b/docs/content/advanced/backend/regions/overview.md
@@ -111,7 +111,7 @@ The relation between the `Region` and `TaxRate` entities is available on both en
---
-## What’s Next
+## See Also
-- Learn [how to use regions in a storefront using the store REST APIs](../../storefront/use-regions.mdx).
-- Learn how to [manage regions using the admin REST APIs](../../admin/manage-regions.mdx).
+- [Use Regions in a storefront](../../storefront/use-regions.mdx).
+- [Use Regions in the admin](../../admin/manage-regions.mdx).
diff --git a/docs/content/advanced/backend/sales-channels/index.md b/docs/content/advanced/backend/sales-channels/index.md
index 7d48c47d42..6101eaba79 100644
--- a/docs/content/advanced/backend/sales-channels/index.md
+++ b/docs/content/advanced/backend/sales-channels/index.md
@@ -68,7 +68,7 @@ The relation is implemented in the [Order](../../../references/entities/classes/
---
-## What’s Next
+## See Also
-- Learn how to [manage Sales Channels using the Admin APIs](./manage-admin.mdx).
-- Check out the [Sales Channel’s Admin APIs](https://docs.medusajs.com/api/admin/#tag/Sales-Channel).
+- [Manage Sales Channels using the Admin APIs](./manage-admin.mdx)
+- [Sales Channel’s Admin APIs Reference](/api/admin/#tag/Sales-Channel)
diff --git a/docs/content/advanced/backend/sales-channels/manage-admin.mdx b/docs/content/advanced/backend/sales-channels/manage-admin.mdx
index f907b18d46..2cb813ee95 100644
--- a/docs/content/advanced/backend/sales-channels/manage-admin.mdx
+++ b/docs/content/advanced/backend/sales-channels/manage-admin.mdx
@@ -1,7 +1,7 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-# How to Use SalesChannels APIs
+# How to Manage Sales Channels
In this document, you’ll learn how to manage sales channels and their products and orders using the Admin APIs.
@@ -23,7 +23,7 @@ This guide explains how to perform all these operations using the Admin APIs.
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.mdx) to get started.
### Enabled Feature Flags
@@ -57,12 +57,12 @@ You can create a sales channel by sending a request to the Create a Sales Channe
```jsx
medusa.admin.salesChannels.create({
- name: 'App',
- description: 'Mobile app'
+ name: "App",
+ description: "Mobile app",
})
.then(({ sales_channel }) => {
- console.log(sales_channel.id);
-});
+ console.log(sales_channel.id)
+})
```
@@ -70,20 +70,20 @@ medusa.admin.salesChannels.create({
```jsx
fetch(`/admin/sales-channels`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- name: 'App',
- description: 'Mobile app'
- })
+ name: "App",
+ description: "Mobile app",
+ }),
})
.then((response) => response.json())
.then(({ sales_channel }) => {
console.log(sales_channel.id)
-});
+})
```
@@ -118,8 +118,8 @@ You can list all sales channels by sending a request to the List Sales Channels
```jsx
medusa.admin.salesChannels.list()
.then(({ sales_channels, limit, offset, count }) => {
- console.log(sales_channels.length);
-});
+ console.log(sales_channels.length)
+})
```
@@ -127,12 +127,12 @@ medusa.admin.salesChannels.list()
```jsx
fetch(`/admin/sales-channels`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ sales_channels, limit, offset, count }) => {
console.log(sales_channels.length)
-});
+})
```
@@ -160,8 +160,8 @@ You can retrieve a sales channel’s details by its ID using the Get Sales Chann
```jsx
medusa.admin.salesChannels.retrieve(salesChannelId)
.then(({ sales_channel }) => {
- console.log(sales_channel.id);
-});
+ console.log(sales_channel.id)
+})
```
@@ -169,12 +169,12 @@ medusa.admin.salesChannels.retrieve(salesChannelId)
```jsx
fetch(`/admin/sales-channels/${salesChannelId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ sales_channels, limit, offset, count }) => {
console.log(sales_channels.length)
-});
+})
```
@@ -201,11 +201,11 @@ You can update a Sales Channel’s details and attributes by sending a request t
```jsx
medusa.admin.salesChannels.update(salesChannelId, {
- is_disabled: false
+ is_disabled: false,
})
.then(({ sales_channel }) => {
- console.log(sales_channel.id);
-});
+ console.log(sales_channel.id)
+})
```
@@ -213,19 +213,19 @@ medusa.admin.salesChannels.update(salesChannelId, {
```jsx
fetch(`/admin/sales-channels/${salesChannelId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- is_disabled: false
- })
+ is_disabled: false,
+ }),
})
.then((response) => response.json())
.then(({ sales_channel }) => {
console.log(sales_channel.id)
-});
+})
```
@@ -261,8 +261,8 @@ You can delete a sales channel by sending a request to the Delete Sales Channel
```jsx
medusa.admin.salesChannels.delete(salesChannelId)
.then(({ id, object, deleted }) => {
- console.log(id);
-});
+ console.log(id)
+})
```
@@ -270,13 +270,13 @@ medusa.admin.salesChannels.delete(salesChannelId)
```jsx
fetch(`/admin/sales-channels/${salesChannelId}`, {
- method: 'DELETE',
- credentials: 'include',
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
console.log(id)
-});
+})
```
@@ -307,37 +307,40 @@ To add a product to a sales channel, send a request to the Sales Channel’s Add
medusa.admin.salesChannels.addProducts(salesChannelId, {
product_ids: [
{
- id: productId
- }
- ]
+ id: productId,
+ },
+ ],
})
.then(({ sales_channel }) => {
- console.log(sales_channel.id);
-});
+ console.log(sales_channel.id)
+})
```
```jsx
-fetch(`/admin/sales-channels/${salesChannelId}/products/batch`, {
- method: 'POST',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json'
- },
- body: JSON.stringify({
- product_ids: [
- {
- id: productId
- }
- ]
- })
-})
+fetch(
+ `/admin/sales-channels/${salesChannelId}/products/batch`,
+ {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ product_ids: [
+ {
+ id: productId,
+ },
+ ],
+ }),
+ }
+)
.then((response) => response.json())
.then(({ sales_channel }) => {
console.log(sales_channel.id)
-});
+})
```
@@ -373,25 +376,28 @@ You can list the products available in a sales channel by sending a request to t
```jsx
medusa.admin.products.list({
sales_channel_id: [
- salesChannelId
- ]
+ salesChannelId,
+ ],
})
.then(({ products, limit, offset, count }) => {
- console.log(products.length);
-});
+ console.log(products.length)
+})
```
```jsx
-fetch(`/admin/products?sales_channel_id[0]=${salesChannelId}`, {
- credentials: 'include',
-})
+fetch(
+ `/admin/products?sales_channel_id[0]=${salesChannelId}`,
+ {
+ credentials: "include",
+ }
+)
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
console.log(products.length)
-});
+})
```
@@ -424,43 +430,46 @@ You can delete a product from a sales channel by sending a request to the Sales
medusa.admin.salesChannels.removeProducts(salesChannelId, {
product_ids: [
{
- id: productId
- }
- ]
+ id: productId,
+ },
+ ],
})
.then(({ sales_channel }) => {
- console.log(sales_channel.id);
-});
+ console.log(sales_channel.id)
+})
```
```jsx
-fetch(`/admin/sales-channels/${salesChannelId}/products/batch`, {
- method: 'DELETE',
- credentials: 'include',
- headers: {
- 'Content-Type': 'application/json'
- },
- body: JSON.stringify({
- product_ids: [
- {
- id: productId
- }
- ]
- })
-})
+fetch(
+ `/admin/sales-channels/${salesChannelId}/products/batch`,
+ {
+ method: "DELETE",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ product_ids: [
+ {
+ id: productId,
+ },
+ ],
+ }),
+ }
+)
.then((response) => response.json())
.then(({ sales_channel }) => {
console.log(sales_channel.id)
-});
+})
```
-```jsx
+```bash
curl -L -X DELETE '/admin/sales-channels//products/batch' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
@@ -492,14 +501,14 @@ You can filter orders by a specific sales channel by sending a request to the Li
```jsx
medusa.admin.orders.list({
sales_channel_id: [
- salesChannelId
+ salesChannelId,
],
limit: 50,
- offset: 0
+ offset: 0,
})
.then(({ orders, limit, offset, count }) => {
- console.log(orders.length);
-});
+ console.log(orders.length)
+})
```
@@ -507,18 +516,18 @@ medusa.admin.orders.list({
```jsx
fetch(`/admin/orders?sales_channel_id[0]=${salesChannelId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
console.log(orders.length)
-});
+})
```
-```jsx
+```bash
curl -L -X GET '/admin/orders?sales_channel_id[0]=' \
-H 'Authorization: Bearer '
```
@@ -530,6 +539,6 @@ The request returns an array of orders that are associated with the specified sa
---
-## What’s Next
+## See Also
-- Learn more about [Sales Channels and how they work](./index.md).
\ No newline at end of file
+- [Sales Channels Overview](./index.md).
\ No newline at end of file
diff --git a/docs/content/advanced/backend/scheduled-jobs/create.md b/docs/content/advanced/backend/scheduled-jobs/create.md
index 246f2be93d..86fcf8e7e8 100644
--- a/docs/content/advanced/backend/scheduled-jobs/create.md
+++ b/docs/content/advanced/backend/scheduled-jobs/create.md
@@ -8,16 +8,20 @@ Medusa allows you to create scheduled jobs that run at specific times during you
This guide explains how to create a scheduled job on your Medusa server. The scheduled job in this example will simply change the status of draft products to `published`.
+---
+
## Prerequisites
### Medusa Components
-It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../../quickstart/quick-start.mdx) to get started.
### Redis
Redis is required for scheduled jobs to work. Make sure you [install Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with your Medusa server](../../../usage/configurations.md#redis).
+---
+
## 1. Create a File
Each scheduled job should reside in a TypeScript or JavaScript file under the `src/loaders` directory.
@@ -26,29 +30,33 @@ Start by creating the `src/loaders` directory. Then, inside that directory, crea
For the example in this tutorial, you can create the file `src/loaders/publish.ts`.
+---
+
## 2. Create Cron Job
To create a scheduled job, add the following code in the file you created, which is `src/loaders/publish.ts` in this example:
```ts title=src/loaders/publish.ts
const publishJob = async (container, options) => {
- const jobSchedulerService = container.resolve("jobSchedulerService");
- jobSchedulerService.create("publish-products", {}, "0 0 * * *", async () => {
- //job to execute
- const productService = container.resolve("productService");
- const draftProducts = await productService.list({
- status: 'draft'
- });
+ const jobSchedulerService = container.resolve("jobSchedulerService")
+ jobSchedulerService.create("publish-products", {}, "0 0 * * *",
+ async () => {
+ // job to execute
+ const productService = container.resolve("productService")
+ const draftProducts = await productService.list({
+ status: "draft",
+ })
- for (const product of draftProducts) {
- await productService.update(product.id, {
- status: 'published'
- });
+ for (const product of draftProducts) {
+ await productService.update(product.id, {
+ status: "published",
+ })
+ }
}
- })
+ )
}
-export default publishJob;
+export default publishJob
```
:::info
@@ -81,14 +89,16 @@ For example:
```ts
jobSchedulerService.create("publish-products", {
data: {
- productId
- }
+ productId,
+ },
}, "0 0 * * *", async (job) => {
- console.log(job.data); // {productId: 'prod_124...'}
- //...
-});
+ console.log(job.data) // {productId: 'prod_124...'}
+ // ...
+})
```
+---
+
## 3. Run Medusa Server
:::info
@@ -129,6 +139,8 @@ To test the previous example out instantly, you can change the scheduled job exp
:::
-## What’s Next
+---
-- Learn more about [services and how you can use them](../services/overview.md).
+## See Also
+
+- [Services Overview](../services/overview.md).
diff --git a/docs/content/advanced/backend/services/create-service.md b/docs/content/advanced/backend/services/create-service.md
index 3b521eed30..5180c6adaa 100644
--- a/docs/content/advanced/backend/services/create-service.md
+++ b/docs/content/advanced/backend/services/create-service.md
@@ -9,12 +9,12 @@ To create a service, create a TypeScript or JavaScript file in `src/services` to
For example, if you want to create a service `helloService`, create the file `hello.ts` in `src/services` with the following content:
```ts title=/src/services/hello.ts
-import { TransactionBaseService } from '@medusajs/medusa';
-import { EntityManager } from 'typeorm';
+import { TransactionBaseService } from "@medusajs/medusa"
+import { EntityManager } from "typeorm"
class HelloService extends TransactionBaseService {
- protected manager_: EntityManager;
- protected transactionManager_: EntityManager;
+ protected manager_: EntityManager
+ protected transactionManager_: EntityManager
getMessage() {
return `Welcome to My Store!`
}
@@ -23,6 +23,8 @@ class HelloService extends TransactionBaseService {
export default HelloService
```
+---
+
## Service Constructor
As the service extends the `TransactionBaseService` class, all services in Medusa’s core, as well as all your custom services, will be available in your service’s constructor using dependency injection.
@@ -30,22 +32,30 @@ As the service extends the `TransactionBaseService` class, all services in Medus
So, if you want your service to use another service, simply add it as part of your constructor’s dependencies and set it to a field inside your service’s class:
```ts
-private productService: ProductService;
+class HelloService extends TransactionBaseService {
+ private productService: ProductService
-constructor(container) {
- super(container);
- this.productService = container.productService;
+ constructor(container) {
+ super(container)
+ this.productService = container.productService
+ }
+ // ...
}
```
Then, you can use that service anywhere in your custom service:
```ts
-async getProductCount() {
- return await this.productService.count();
+class HelloService extends TransactionBaseService {
+ // ...
+ async getProductCount() {
+ return await this.productService.count()
+ }
}
```
+---
+
## Use a Service
In this section, you'll learn how to use services throughout your Medusa server. This includes both Medusa's services and your custom services.
@@ -65,9 +75,12 @@ npm run build
To use your custom service in another custom service, you can have easy access to it in the dependencies injected to the constructor of your service:
```ts
-constructor(container) {
- super(container);
- this.helloService = container.helloService;
+class MyService extends TransactionBaseService {
+ constructor(container) {
+ super(container)
+ this.helloService = container.helloService
+ }
+ // ...
}
```
@@ -88,12 +101,17 @@ res.json({
To use your custom service in a subscriber, you can have easy access to it in the subscriber’s dependencies injected to the constructor of your subscriber:
```ts
-constructor({ helloService, eventBusService }) {
- this.helloService = helloService;
+class MySubscriber {
+ constructor({ helloService, eventBusService }) {
+ this.helloService = helloService
+ }
+ // ...
}
```
-## What’s Next
+---
-- Check out the [Services Reference](/references/services/classes/AuthService) to see a list of all services in Medusa.
-- [Learn How to Create an Endpoint.](../endpoints/add.md)
+## See Also
+
+- [Services Reference](/references/services/classes/AuthService)
+- [Create an Endpoint](../endpoints/add.md)
diff --git a/docs/content/advanced/backend/services/overview.md b/docs/content/advanced/backend/services/overview.md
index 4fe54a9f25..6d4209f895 100644
--- a/docs/content/advanced/backend/services/overview.md
+++ b/docs/content/advanced/backend/services/overview.md
@@ -18,7 +18,9 @@ For example, if the file name is `hello.ts`, the service will be registered as `
The registration name of the service is important, as you’ll be referring to it when you want to get access to the service using dependency injection or in routes.
-## What's Next
+---
-- Learn [how to create a service](./create-service.md)
-- Check out the [Services Reference](/references/services/classes/AuthService) to see a list of all services in Medusa.
+## See Also
+
+- [Create a Service](./create-service.md)
+- [Services Reference](/references/services/classes/AuthService)
diff --git a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md b/docs/content/advanced/backend/shipping/add-fulfillment-provider.md
index 7bc75b204a..3d41fa456c 100644
--- a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md
+++ b/docs/content/advanced/backend/shipping/add-fulfillment-provider.md
@@ -19,6 +19,8 @@ Also, the fulfillment provider class should have a static property `identifier`.
Fulfillment providers are loaded and installed on the server startup.
+---
+
## Create a Fulfillment Provider
The first step is to create a JavaScript or TypeScript file under `src/services`. For example, create the file `src/services/my-fulfillment.ts` with the following content:
@@ -30,7 +32,7 @@ class MyFulfillmentService extends FulfillmentService {
}
-export default MyFulfillmentService;
+export default MyFulfillmentService
```
Fulfillment provider services must extend the `FulfillmentService` class imported from `medusa-interfaces`.
@@ -53,10 +55,10 @@ The value of this property will also be used to reference the fulfillment provid
import { FulfillmentService } from "medusa-interfaces"
class MyFulfillmentService extends FulfillmentService {
- static identifier = 'my-fulfillment';
+ static identifier = "my-fulfillment"
}
-export default MyFulfillmentService;
+export default MyFulfillmentService
```
### constructor
@@ -70,9 +72,12 @@ Additionally, if you’re creating your fulfillment provider as an external plug
For example:
```ts
-constructor({ productService }, options) {
- super();
- //you can access options here
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ constructor(container, options) {
+ super(container)
+ // you can access options here
+ }
}
```
@@ -87,15 +92,18 @@ These fulfillment options are defined in the `getFulfillmentOptions` method. Thi
For example:
```ts
-async getFulfillmentOptions () {
- return [
- {
- id: 'my-fulfillment'
- },
- {
- id: 'my-fulfillment-dynamic'
- }
- ];
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ async getFulfillmentOptions() {
+ return [
+ {
+ id: "my-fulfillment",
+ },
+ {
+ id: "my-fulfillment-dynamic",
+ },
+ ]
+ }
}
```
@@ -114,8 +122,11 @@ This method returns a boolean. If the result is false, an error is thrown and th
For example, you can use this method to ensure that the `id` in the `data` object is correct:
```ts
-async validateOption (data) {
- return data.id == 'my-fulfillment';
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ async validateOption(data) {
+ return data.id == "my-fulfillment"
+ }
}
```
@@ -142,13 +153,16 @@ If everything is valid, this method must return a value that will be stored in t
For example:
```ts
-async validateFulfillmentData(optionData, data, cart) {
- if (data.id !== "my-fulfillment") {
- throw new Error("invalid data");
- }
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ async validateFulfillmentData(optionData, data, cart) {
+ if (data.id !== "my-fulfillment") {
+ throw new Error("invalid data")
+ }
- return {
- ...data
+ return {
+ ...data,
+ }
}
}
```
@@ -171,14 +185,17 @@ You can use the `data` property in the shipping method (first parameter) to acce
Here is a basic implementation of `createFulfillment` for a fulfillment provider that does not interact with any third-party provider to create the fulfillment:
```ts
-createFulfillment(
- methodData,
- fulfillmentItems,
- fromOrder,
- fulfillment
-) {
- // No data is being sent anywhere
- return Promise.resolve({})
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ createFulfillment(
+ methodData,
+ fulfillmentItems,
+ fromOrder,
+ fulfillment
+ ) {
+ // No data is being sent anywhere
+ return Promise.resolve({})
+ }
}
```
@@ -204,8 +221,11 @@ This method receives as a parameter the `data` object sent with the request that
For example:
```ts
-canCalculate(data) {
- return data.id === 'my-fulfillment-dynamic';
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ canCalculate(data) {
+ return data.id === "my-fulfillment-dynamic"
+ }
}
```
@@ -222,16 +242,22 @@ This method receives three parameters:
If your fulfillment provider does not provide any dynamically calculated rates you can keep the function empty:
```ts
-calculatePrice() {
-
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ calculatePrice() {
+ // leave empty
+ }
}
```
Otherwise, you can use it to calculate the price with a custom logic. For example:
```ts
-calculatePrice (optionData, data, cart) {
- return cart.items.length * 1000;
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ calculatePrice(optionData, data, cart) {
+ return cart.items.length * 1000
+ }
}
```
@@ -248,8 +274,11 @@ It receives the return created as a parameter. The value it returns is set to th
This is the basic implementation of the method for a fulfillment provider that does not contact with a third-party provider to fulfill the return:
```ts
-createReturn(returnOrder) {
- return Promise.resolve({})
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ createReturn(returnOrder) {
+ return Promise.resolve({})
+ }
}
```
@@ -264,12 +293,16 @@ This method receives the fulfillment being cancelled as a parameter.
This is the basic implementation of the method for a fulfillment provider that does not interact with a third-party provider to cancel the fulfillment:
```ts
-cancelFulfillment(fulfillment) {
- return Promise.resolve({})
+class MyFulfillmentService extends FulfillmentService {
+ // ...
+ cancelFulfillment(fulfillment) {
+ return Promise.resolve({})
+ }
}
```
-## What’s Next
+---
-- Check out the [Webshipper plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-webshipper) for an example of a fulfillment provider that interacts with a third-party providers.
-- Check out the [manual fulfillment plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-manual) for a basic implementation of a fulfillment provider.
+## See Also
+
+- Example Implementations: [Webshipper plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-webshipper) and the [manual fulfillment plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-manual)
diff --git a/docs/content/advanced/backend/shipping/overview.md b/docs/content/advanced/backend/shipping/overview.md
index c14919ef26..e5c9f1384e 100644
--- a/docs/content/advanced/backend/shipping/overview.md
+++ b/docs/content/advanced/backend/shipping/overview.md
@@ -10,6 +10,8 @@ The distinction between the four is important. It has been carefully planned and
It’s also constructed to support multiple regions, provide different shipment configurations and options for different product types, provide promotional shipments for your customers, and much more.
+---
+
## Summary
- **Fulfillment Provider:** Fulfillment providers are plugins or [Services](../services/create-service.md) used to ship the products to your customers, whether physically or virtually. An example of a fulfillment provider would be FedEx.
@@ -19,6 +21,8 @@ It’s also constructed to support multiple regions, provide different shipment
+---
+
## Fulfillment Provider
A Fulfillment Provider in Medusa is a method to handle shipping products in selected regions. It is not associated with a cart, customer, or order in particular.
@@ -37,12 +41,14 @@ As a developer, you will mainly work with the Fulfillment Provider when integrat
When you run your Medusa server, the Fulfillment Provider will be registered on your server if it hasn’t been already.
-Once the Fulfillment Provider is added to the server, the store operator will be able to associate on the [Medusa Admin](../../../quickstart/quick-start.md) the Fulfillment Provider with shipping options.
+Once the Fulfillment Provider is added to the server, the store operator will be able to associate on the [Medusa Admin](../../../quickstart/quick-start.mdx) the Fulfillment Provider with shipping options.
### FulfillmentProvider Entity Overview
The [`FulfillmentProvider`](../../../references/entities/classes/FulfillmentProvider.md) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service.
+---
+
## Shipping Profile
Shipping profiles are the highest in the hierarchy in the shipping architecture.
@@ -69,6 +75,8 @@ The `ShippingProfile` has a `type` attribute that can be `default`, `gift_ca
The `ShippingProfile` entity also has an array of `ShippingOption` instances.
+---
+
## Shipping Option
After the admin adds a shipping profile, they can add shipping options that belong to that shipping profile from the admin dashboard.
@@ -105,6 +113,8 @@ The `data` attribute is used to specify any data necessary for fulfilling the
The `data` attribute does not have any specific format. It’s up to you to choose whatever data is included here.
+---
+
## Shipping Method
Unlike the previous two components, a shipping method is not created by the admin. It’s created when a `POST` request is sent to `/store/carts/:id/shipping-methods` after the customer chooses a shipping option.
@@ -135,7 +145,9 @@ The `ShippingMethod` also belongs to the `Order` entity. This association is
The `ShippingMethod` instance holds a `price` attribute, which will either be the flat rate price or the calculated price.
-## What’s Next
+---
-- [Learn how to Create a Fulfillment Provider.](./add-fulfillment-provider.md)
-- Check out [available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages).
+## See Also
+
+- [Create a Fulfillment Provider](./add-fulfillment-provider.md)
+- [Available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages)
diff --git a/docs/content/advanced/backend/subscribers/create-subscriber.md b/docs/content/advanced/backend/subscribers/create-subscriber.md
index 7a63a2151d..75dc810e03 100644
--- a/docs/content/advanced/backend/subscribers/create-subscriber.md
+++ b/docs/content/advanced/backend/subscribers/create-subscriber.md
@@ -8,6 +8,8 @@ Medusa's event system works by pushing data to a Queue that each handler then ge
You can learn how to [install Redis](../../../tutorial/0-set-up-your-development-environment.mdx#redis) and [configure it with Medusa](../../../usage/configurations.md#redis) before you get started.
+---
+
## Implementation
A subscriber is a TypeScript or JavaScript file that is created under `src/subscribers`. Its file name, by convension, should be the class name of the subscriber without the word `Subscriber`. For example, if the subscriber is `HelloSubscriber`, the file name should be `hello.ts`.
@@ -16,20 +18,20 @@ After creating the file under `src/subscribers`, in the constructor of your subs
The `eventBusService.subscribe` method receives the name of the event as a first parameter and as a second parameter a method in your subscriber that will handle this event.
-For example, here is the `OrderNotifierSubscriber` class created in `src/subscribers/orderNotifier.js`:
+For example, here is the `OrderNotifierSubscriber` class created in `src/subscribers/orderNotifier.ts`:
-```ts title=src/subscribers/orderNotifier.js
+```ts title=src/subscribers/orderNotifier.ts
class OrderNotifierSubscriber {
constructor({ eventBusService }) {
- eventBusService.subscribe("order.placed", this.handleOrder);
+ eventBusService.subscribe("order.placed", this.handleOrder)
}
handleOrder = async (data) => {
console.log("New Order: " + data.id)
- };
+ }
}
-export default OrderNotifierSubscriber;
+export default OrderNotifierSubscriber
```
This subscriber registers the method `handleOrder` as one of the handlers of the `order.placed` event. The method `handleOrder` will be executed every time an order is placed. It receives the order ID in the `data` parameter. You can then use the order’s details to perform any kind of task you need.
@@ -40,6 +42,8 @@ The `data` object won't contain other order data. Only the ID of the order. You
:::
+---
+
## Using Services in Subscribers
You can access any service through the dependencies injected to your subscriber’s constructor.
@@ -47,19 +51,25 @@ You can access any service through the dependencies injected to your subscriber
For example:
```ts
-constructor({ productService, eventBusService }) {
- this.productService = productService;
+class OrderNotifierSubscriber {
+ constructor({ productService, eventBusService }) {
+ this.productService = productService
- eventBusService.subscribe("order.placed", this.handleOrder);
+ eventBusService.subscribe("order.placed", this.handleOrder)
+ }
+ // ...
}
```
You can then use `this.productService` anywhere in your subscriber’s methods. For example:
```ts
-handleOrder = async (data) => {
- //...
- const product = this.productService.list()
+class OrderNotifierSubscriber {
+ // ...
+ handleOrder = async (data) => {
+ // ...
+ const product = this.productService.list()
+ }
}
```
@@ -69,7 +79,9 @@ When using attributes defined in the subscriber, such as the `productService` in
:::
-## What’s Next
+---
-- [View the list of all events](events-list.md)
-- [Learn how to create a service.](/advanced/backend/services/create-service)
+## See Also
+
+- [Events reference](events-list.md)
+- [Create a Service](../services/create-service)
diff --git a/docs/content/advanced/backend/subscribers/events-list.md b/docs/content/advanced/backend/subscribers/events-list.md
index 02953731bc..ee1144a7ef 100644
--- a/docs/content/advanced/backend/subscribers/events-list.md
+++ b/docs/content/advanced/backend/subscribers/events-list.md
@@ -6,6 +6,8 @@ This document details all events in Medusa, when they are triggered, and what da
It is assumed you’re already familiar with [Subscribers in Medusa and how to listen to events](create-subscriber.md). You can then use the name of events from this documentation in your subscriber to listen to events.
+---
+
## Legend
Events in this document are listed under the entity they’re associated with. They’re listed in a table of three columns:
@@ -14,6 +16,8 @@ Events in this document are listed under the entity they’re associated with. T
2. **Description:** When this event is triggered.
3. **Event Data Payload**: The data your handler receives as a parameter.
+---
+
## Batch Jobs Events
This section holds all events related to batch jobs.
@@ -47,7 +51,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -68,7 +72,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -89,7 +93,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -112,7 +116,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -135,7 +139,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -156,7 +160,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -177,7 +181,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -198,7 +202,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of batch job
+ id // string ID of batch job
}
```
@@ -208,6 +212,8 @@ Object of the following format:
+---
+
## Cart Events
This section holds all events related to a cart.
@@ -256,7 +262,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of cart
+ id // string ID of cart
}
```
@@ -284,6 +290,8 @@ An object with at least the ID of the cart, however, in most cases the entire ca
+---
+
## Claim Events
This section holds all events related to claims.
@@ -321,8 +329,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -346,8 +354,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -371,8 +379,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -396,9 +404,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- fulfillment_id, //string ID of the fulfillment created
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ fulfillment_id, // string ID of the fulfillment created
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -422,9 +430,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- fulfillment_id, //string ID of the fulfillment created
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ fulfillment_id, // string ID of the fulfillment created
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -448,8 +456,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of claim
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of claim
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -459,6 +467,8 @@ Object of the following format:
+---
+
## Claim Item Events
This section holds all events related to claim items.
@@ -495,7 +505,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of claim item
+ id // string ID of claim item
}
```
@@ -519,7 +529,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of claim item
+ id // string ID of claim item
}
```
@@ -543,7 +553,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of claim item
+ id // string ID of claim item
}
```
@@ -553,6 +563,8 @@ Object of the following format:
+---
+
## Currency Events
This section holds all events related to currencies.
@@ -589,7 +601,7 @@ Object of the following format:
```js noReport noCopy
{
- code //string 3 character ISO code of the updated currency.
+ code // string 3 character ISO code of the updated currency.
}
```
@@ -599,6 +611,8 @@ Object of the following format:
+---
+
## Customer Events
This section holds all events related to customers.
@@ -671,11 +685,11 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of customer
- email, //string email of the customer
- first_name, //string first name of the customer
- last_name, //string last name of the customer
- token //string reset password token
+ id, // string ID of customer
+ email, // string email of the customer
+ first_name, // string first name of the customer
+ last_name, // string last name of the customer
+ token // string reset password token
}
```
@@ -685,6 +699,8 @@ Object of the following format:
+---
+
## Draft Order Events
This section holds all events related to draft orders.
@@ -721,7 +737,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of draft order
+ id // string ID of draft order
}
```
@@ -745,7 +761,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of draft order
+ id // string ID of draft order
}
```
@@ -755,6 +771,8 @@ Object of the following format:
+---
+
## Gift Card Events
This section holds all events related to gift cards.
@@ -802,6 +820,8 @@ Object of the following format:
+---
+
## Invite Events
This section holds all events related to invites.
@@ -838,9 +858,9 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of invite
- token, //string token generated to validate the invited user
- user_email //string email of invited user
+ id // string ID of invite
+ token, // string token generated to validate the invited user
+ user_email // string email of invited user
}
```
@@ -849,6 +869,8 @@ Object of the following format:
+---
+
## Note Events
This section holds all events related to notes.
@@ -885,7 +907,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of note
+ id // string ID of note
}
```
@@ -909,7 +931,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of note
+ id // string ID of note
}
```
@@ -933,7 +955,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of note
+ id // string ID of note
}
```
@@ -943,6 +965,8 @@ Object of the following format:
+---
+
## App Authentication Events
This section holds all events related to app authentications.
@@ -1008,6 +1032,8 @@ The returned data from the method `refreshToken` in the auth handler service of
+---
+
## Order Events
This section holds all events related to orders.
@@ -1044,8 +1070,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1069,8 +1095,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- no_notification //(optional) boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ no_notification // (optional) boolean indicating whether a notification should be sent
}
```
@@ -1094,8 +1120,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1119,8 +1145,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1168,7 +1194,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of order
+ id // string ID of order
}
```
@@ -1192,8 +1218,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1217,10 +1243,10 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- payment_id, //string ID of Payment
- error, //string error message
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ payment_id, // string ID of Payment
+ error, // string error message
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1244,9 +1270,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- fulfillment_id, //string ID of fulfillment
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ fulfillment_id, // string ID of fulfillment
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1270,9 +1296,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- fulfillment_id, //string ID of fulfillment
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ fulfillment_id, // string ID of fulfillment
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1296,9 +1322,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- fulfillment_id, //string ID of fulfillment
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ fulfillment_id, // string ID of fulfillment
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1322,9 +1348,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- return_id, //string ID of return
- no_notification //(optional) boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ return_id, // string ID of return
+ no_notification // (optional) boolean indicating whether a notification should be sent
}
```
@@ -1348,9 +1374,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- return_id, //string ID of return
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ return_id, // string ID of return
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1374,9 +1400,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- return_id, //string ID of return
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ return_id, // string ID of return
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1400,9 +1426,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of order
- refund_id, //string ID of refund
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of order
+ refund_id, // string ID of refund
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -1460,6 +1486,8 @@ Object of the following format:
+---
+
## Order Edit Events
This section holds all events related to order edits.
@@ -1603,7 +1631,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of order edit
+ id // string ID of order edit
}
```
@@ -1637,6 +1665,8 @@ Object of the following format:
+---
+
## Order Edit Item Changes Events
This section holds all events related to order edit item changes.
@@ -1682,7 +1712,7 @@ Triggered when an order edit item change is created.
```js noReport noCopy
{
- id //string ID of item change
+ id // string ID of item change
}
```
@@ -1704,7 +1734,7 @@ Triggered when an order edit item change is deleted.
```js noReport noCopy
{
- id //string ID of item change
+ id // string ID of item change
}
```
@@ -1714,6 +1744,8 @@ Triggered when an order edit item change is deleted.
+---
+
## Payment Events
This section holds all events related to payment.
@@ -1859,6 +1891,8 @@ The entire payment passed as an object. You can refer to the [Payment entity](..
+---
+
## Payment Collection Events
This section holds all events related to payment collections.
@@ -1954,6 +1988,8 @@ The entire payment collection passed as an object. You can refer to the [Payment
+---
+
## Product Events
This section holds all events related to products.
@@ -1991,7 +2027,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of product
+ id // string ID of product
}
```
@@ -2017,8 +2053,8 @@ In one case, when the `/admin/products/{id}` endpoint is used to update the prod
```js noReport noCopy
{
- id, //id of product
- fields //an array of field names that were updated
+ id, // id of product
+ fields // an array of field names that were updated
}
```
@@ -2042,7 +2078,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of product
+ id // string ID of product
}
```
@@ -2052,6 +2088,8 @@ Object of the following format:
+---
+
## Product Variant Events
This section holds all events related to product variants.
@@ -2088,8 +2126,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of variant
- product_id //string ID of product
+ id, // string ID of variant
+ product_id // string ID of product
}
```
@@ -2113,9 +2151,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of variant
- product_id, //string ID of product
- fields //array of names of updated fields
+ id, // string ID of variant
+ product_id, // string ID of product
+ fields // array of names of updated fields
}
```
@@ -2139,9 +2177,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of variant
- product_id, //string ID of product
- metadata //object of the `metadata` field of the variant
+ id, // string ID of variant
+ product_id, // string ID of product
+ metadata // object of the `metadata` field of the variant
}
```
@@ -2151,6 +2189,8 @@ Object of the following format:
+---
+
## Publishable API Key Events
This section holds all events related to publishable API keys.
@@ -2199,7 +2239,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of publishable API key
+ id // string ID of publishable API key
}
```
@@ -2223,7 +2263,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of publishable API key
+ id // string ID of publishable API key
}
```
@@ -2233,6 +2273,8 @@ Object of the following format:
+---
+
## Region Events
This section holds all events related to regions.
@@ -2269,7 +2311,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of region
+ id // string ID of region
}
```
@@ -2293,8 +2335,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of region
- fields //array of names of updated fields
+ id, // string ID of region
+ fields // array of names of updated fields
}
```
@@ -2318,7 +2360,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of region
+ id // string ID of region
}
```
@@ -2327,6 +2369,8 @@ Object of the following format:
+---
+
## Sales Channel Events
This section holds all events related to sales channels.
@@ -2374,7 +2418,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of sales channel
+ id // string ID of sales channel
}
```
@@ -2422,7 +2466,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of sales channel
+ id // string ID of sales channel
}
```
@@ -2431,6 +2475,8 @@ Object of the following format:
+---
+
## Swap Events
This section holds all events related to swaps.
@@ -2467,8 +2513,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2492,9 +2538,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- order_id, //string ID of order
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ order_id, // string ID of order
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2518,9 +2564,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- fulfillment_id, //string ID of fulfillment
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ fulfillment_id, // string ID of fulfillment
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2544,9 +2590,9 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- fulfillment_id, //string ID of fulfillment
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ fulfillment_id, // string ID of fulfillment
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2570,8 +2616,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2595,8 +2641,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2620,8 +2666,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2645,8 +2691,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2670,8 +2716,8 @@ Object of the following format:
```js noReport noCopy
{
- id, //string ID of swap
- no_notification //boolean indicating whether a notification should be sent or not
+ id, // string ID of swap
+ no_notification // boolean indicating whether a notification should be sent
}
```
@@ -2681,6 +2727,8 @@ Object of the following format:
+---
+
## Token Events
This section holds all events related to tokens.
@@ -2730,6 +2778,8 @@ Object of the following format:
+---
+
## User Events
This section holds all events related to users.
@@ -2766,7 +2816,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of user
+ id // string ID of user
}
```
@@ -2790,7 +2840,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of user
+ id // string ID of user
}
```
@@ -2814,8 +2864,8 @@ Object of the following format:
```js noReport noCopy
{
- email, //string email of user requesting to reset their password
- token //token create to reset the password
+ email, // string email of user requesting to reset their password
+ token // token create to reset the password
}
```
@@ -2839,7 +2889,7 @@ Object of the following format:
```js noReport noCopy
{
- id //string ID of user
+ id // string ID of user
}
```
@@ -2848,7 +2898,9 @@ Object of the following format:
-## What’s Next
+---
-- Learn how you can [use services in subscribers](create-subscriber.md#using-services-in-subscribers).
-- Learn how to [create notifications](../notification/overview.md) in Medusa.
+## See Also
+
+- [Use services in subscribers](create-subscriber.md#using-services-in-subscribers)
+- [Create a notification provider](../notification/overview.md)
diff --git a/docs/content/advanced/backend/subscribers/overview.md b/docs/content/advanced/backend/subscribers/overview.md
index 2fd87d677f..ea8f46aa6d 100644
--- a/docs/content/advanced/backend/subscribers/overview.md
+++ b/docs/content/advanced/backend/subscribers/overview.md
@@ -10,6 +10,8 @@ The purpose of these events is to allow other parts of the platform, or third-pa
Medusa's queuing and events system is handled by Redis. So, you must have [Redis configured](../../../tutorial/0-set-up-your-development-environment.mdx#redis) on your server to use subscribers.
+---
+
## What are Subscribers
Subscribers register handlers for an events and allows you to perform an action when that event occurs. For example, if you want to send your customer an email when they place an order, then you can listen to the `order.placed` event and send the email when the event is emitted.
@@ -20,7 +22,9 @@ Custom subscribers are TypeScript or JavaScript files in your project's `src/sub
Whenever an event is emitted, the subscriber’s registered handler method is executed. The handler method receives as a parameter an object that holds data related to the event. For example, if an order is placed the `order.placed` event will be emitted and all the handlers will receive the order id in the parameter object.
-## What's Next
+---
-- Learn [how to create a Subscriber](create-subscriber.md).
-- [View the list of all events](events-list.md).
+## See Also
+
+- [Create a Subscriber](create-subscriber.md).
+- [Events reference](events-list.md).
diff --git a/docs/content/advanced/backend/taxes/inclusive-pricing.md b/docs/content/advanced/backend/taxes/inclusive-pricing.md
index 73e55952cd..a106fea87b 100644
--- a/docs/content/advanced/backend/taxes/inclusive-pricing.md
+++ b/docs/content/advanced/backend/taxes/inclusive-pricing.md
@@ -21,6 +21,8 @@ This can be useful when some countries have the same currency but have different
Then, Medusa handles calculating the tax amount using the tax rate and the tax-inclusive price. This is managed in the backend and relayed to accounting and analytics tools.
+---
+
## How is Tax Inclusivity Defined
Tax inclusivity can be toggled for regions, currencies, price lists, and shipping options either during creation or while editing. This is represented by the boolean attribute `includes_tax` available in the entities `Region`, `Currency`, `PriceList`, and `ShippingOption`. By default, this attribute is set to `false`.
@@ -54,6 +56,8 @@ When a shipping option is selected, a shipping method is created based on that s
The `ShippingMethod` entity also has the `includes_tax` attribute. Its value is the same as the value of `includes_tax` of the shipping option the method is associated with.
+---
+
## Tax Amount Calculation Formula
When a price is tax-inclusive, the tax amount is calculated using the following formula:
@@ -66,6 +70,8 @@ Where `taxRate` is the tax rate to be applied to the price, and `taxInclusivePri
For example, if the tax rate is `0.25` and the price of a product is `100`, the resulting tax amount calculated by Medusa will be `0.25 * 100 / 1.25 = 20`.
+---
+
## Retrieving Tax Amounts
This section covers at which point tax amounts are calculated for different entities, how they are calculated when the price is tax inclusive, and what fields can be returned in the endpoints relative to each of the entities.
@@ -120,7 +126,9 @@ Where `amount` is the amount of the variant’s price in the price list, `taxRat
Here is an example of these fields when tax inclusivity is enabled for both the currency and the price list:
-```jsx noReport
+
+
+```js noReport
{
original_price: 110,
calculated_price: 100,
@@ -187,7 +195,9 @@ The relevant fields are:
During the calculation of the totals of different components of the cart or order, such as shipping or line items, if tax inclusivity is enabled on that component, a process similar to those explained above will be applied to retrieve the total.
-## What’s Next
+---
-- Learn how to [calculate taxes manually](manual-calculation.md).
-- [Check out the API reference](https://docs.medusajs.com/api/store/).
+## See Also
+
+- [Calculate taxes manually](manual-calculation.md)
+- [Storefront API reference](/api/store)
diff --git a/docs/content/advanced/backend/taxes/manual-calculation.md b/docs/content/advanced/backend/taxes/manual-calculation.md
index c3bbedeb85..a73d5e6712 100644
--- a/docs/content/advanced/backend/taxes/manual-calculation.md
+++ b/docs/content/advanced/backend/taxes/manual-calculation.md
@@ -8,6 +8,8 @@ By default, taxes are automatically calculated by Medusa during checkout. This b
If you disable this behavior, you must manually trigger taxes calculation. When taxes are calculated, this means that requests will be sent to the tax provider to retrieve the tax rates.
+---
+
## How to Manually Calculate Taxes in Checkout
This section explores different ways you can calculate taxes based on your purpose.
@@ -27,7 +29,7 @@ You can, however, force calculating the taxes of the cart by passing in the thir
For example:
```jsx
-cartService.retrieve('cart_01G8Z...', { }, { force_taxes: true });
+cartService.retrieve("cart_01G8Z...", { }, { force_taxes: true })
```
:::tip
@@ -43,20 +45,20 @@ Another way you can use the `CartService` to calculate taxes is using the method
```jsx
export default () => {
- //...
+ // ...
router.get("/store/line-taxes", async (req, res) => {
- //example of retrieving cart
- const cartService = req.scope.resolve("cartService");
+ // example of retrieving cart
+ const cartService = req.scope.resolve("cartService")
const cart = await cartService.retrieve(cart_id)
- //...
- //retrieve taxes of line items
+ // ...
+ // retrieve taxes of line items
const data = await decorateTotals(cart, {
- force_taxes: true
+ force_taxes: true,
})
- return res.status(200).json({ cart: data });
+ return res.status(200).json({ cart: data })
})
}
```
@@ -70,7 +72,7 @@ You can calculate and retrieve taxes of line items using the `getLineItemTotals`
```jsx
const itemTotals = await totalsService
.getLineItemTotals(item, cart, {
- include_tax: true
+ include_tax: true,
})
```
@@ -80,7 +82,9 @@ You can learn how to [retrieve and use services](../services/create-service.md#u
:::
-## What’s Next
+---
-- Learn about [tax-inclusive pricing](inclusive-pricing.md).
-- Learn about available methods in [CartsService](../../../references/services/classes/CartService.md) and [TotalsService](../../../references/services/classes/TotalsService.md).
+## See Also
+
+- [Tax-Inclusive Pricing Overview](inclusive-pricing.md)
+- [CartsService](../../../references/services/classes/CartService.md) and [TotalsService](../../../references/services/classes/TotalsService.md)
diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-0.md b/docs/content/advanced/backend/upgrade-guides/1-3-0.md
index a4710f6264..62768e48e8 100644
--- a/docs/content/advanced/backend/upgrade-guides/1-3-0.md
+++ b/docs/content/advanced/backend/upgrade-guides/1-3-0.md
@@ -20,6 +20,8 @@ TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `` with your PostgreSQL database URL.
+---
+
## Environment Variables
In previous versions of Medusa, The server automatically loads all environment variables in the `.env` file at the root of the Medusa server.
@@ -33,31 +35,34 @@ If you use a `.env` file to load environment variables on your server, you need
You can add the following code snippet at the top of the file which uses the [dotenv](https://www.npmjs.com/package/dotenv) package to load the environment variables based on the current Node environment:
```jsx
-const dotenv = require('dotenv')
+const dotenv = require("dotenv")
- let ENV_FILE_NAME = '';
+ let ENV_FILE_NAME = ""
switch (process.env.NODE_ENV) {
- case 'production':
- ENV_FILE_NAME = '.env.production';
- break;
- case 'staging':
- ENV_FILE_NAME = '.env.staging';
- break;
- case 'test':
- ENV_FILE_NAME = '.env.test';
- break;
- case 'development':
+ case "production":
+ ENV_FILE_NAME = ".env.production"
+ break
+ case "staging":
+ ENV_FILE_NAME = ".env.staging"
+ break
+ case "test":
+ ENV_FILE_NAME = ".env.test"
+ break
+ case "development":
default:
- ENV_FILE_NAME = '.env';
- break;
+ ENV_FILE_NAME = ".env"
+ break
}
try {
- dotenv.config({ path: process.cwd() + '/' + ENV_FILE_NAME });
+ dotenv.config({ path: process.cwd() + "/" + ENV_FILE_NAME })
} catch (e) {
+ // handle error
}
```
+---
+
## Line Item Adjustments
This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities.
@@ -76,6 +81,8 @@ For that reason, it’s essential to run the data migration script after upgradi
node ./node_modules/@medusajs/medusa/dist/scripts/line-item-adjustment-migration.js
```
+---
+
## Advanced Discount Conditions
This new version of Medusa holds advanced promotions functionalities to provide store operators with even more customization capabilities when creating discounts. You can now add even more conditions to your discounts to make them specific for a set of products, collections, customer groups, and more.
diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-6.md b/docs/content/advanced/backend/upgrade-guides/1-3-6.md
index c0a2bd0def..7f021aef8a 100644
--- a/docs/content/advanced/backend/upgrade-guides/1-3-6.md
+++ b/docs/content/advanced/backend/upgrade-guides/1-3-6.md
@@ -26,6 +26,8 @@ TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `` with your PostgreSQL database URL.
+---
+
## Sales Channels
Sales Channels were introduced in v1.3.5 guarded by a [feature flag](../feature-flags/toggle.md). By enabling Sales Channels, developers and users can associate products and other entities with a specific Sales Channel.
diff --git a/docs/content/advanced/backend/upgrade-guides/1-3-8.md b/docs/content/advanced/backend/upgrade-guides/1-3-8.md
index 95a151edfe..15fd523957 100644
--- a/docs/content/advanced/backend/upgrade-guides/1-3-8.md
+++ b/docs/content/advanced/backend/upgrade-guides/1-3-8.md
@@ -10,6 +10,8 @@ Updating your medusa server to version `1.3.8` may cause issues when using NPM.
It's highly recommended to use [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update.
+---
+
## Resolving Update Issues with NPM
### Update All Medusa Dependencies
diff --git a/docs/content/advanced/backend/upgrade-guides/1-6-1.md b/docs/content/advanced/backend/upgrade-guides/1-6-1.md
index 77b23ece1c..8c6d2a7365 100644
--- a/docs/content/advanced/backend/upgrade-guides/1-6-1.md
+++ b/docs/content/advanced/backend/upgrade-guides/1-6-1.md
@@ -12,6 +12,8 @@ As the new version `1.6.1` make changes to the database schema, it is required t
Without running the migrations, you might have trouble accessing and using the Medusa admin.
+---
+
## Actions Required
After updating your server, run migrations with the following command:
diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-0.md b/docs/content/advanced/backend/upgrade-guides/1-7-0.md
index a5eebd7e95..d6ef8caa9d 100644
--- a/docs/content/advanced/backend/upgrade-guides/1-7-0.md
+++ b/docs/content/advanced/backend/upgrade-guides/1-7-0.md
@@ -12,6 +12,8 @@ In this new version, the method [`retrieveByEmail` in the Customer Service](../.
In addition, after introducing the Claim Order feature, this version of Medusa introduces changes in the database that allows two customers having the same email based on the value of the `has_account` field. This change requires running migrations after the update.
+---
+
## Actions Required
### Run Migrations
@@ -29,19 +31,19 @@ Instead of using `customerService.retrieveByEmail`, you should now use the metho
The `customerService.retrieveRegisteredByEmail` method allows you to retrieve a registered customer by email:
```ts
-customerService.retrieveRegisteredByEmail("example@gmail.com");
+customerService.retrieveRegisteredByEmail("example@gmail.com")
```
On the other hand, the `retrieveUnregisteredByEmail` method allows to retrieve guest customers by email:
```jsx
-customerService.retrieveUnregisteredByEmail("example@gmail.com");
+customerService.retrieveUnregisteredByEmail("example@gmail.com")
```
To retrieve a customer by email regardless of whether they are registered or not, you can use the `customerService.list` method instead:
```ts
customerService.list({
- email: "example@gmail.com"
+ email: "example@gmail.com",
})
```
diff --git a/docs/content/advanced/backend/upgrade-guides/1-7-1.md b/docs/content/advanced/backend/upgrade-guides/1-7-1.md
new file mode 100644
index 0000000000..1a1f2d617c
--- /dev/null
+++ b/docs/content/advanced/backend/upgrade-guides/1-7-1.md
@@ -0,0 +1,128 @@
+---
+description: 'Actions Required for v.1.7.1'
+---
+
+# v1.7.1
+
+Version `1.7.1` of Medusa introduces the `JobSchedulerService` which changes how scheduled/cron jobs are created.
+
+## Overview
+
+Version `1.7.1` of Medusa introduces a new service `JobSchedulerService` that handles all logic and functionality related to created scheduled (previously named cron jobs).
+
+With this introduction, the previous use of `EventBus` to create a cron job has been deprecated of using the `JobSchedulerService`.
+
+In addition, this version features some fixes to gift cards that requires running migrations, and changes to how payment providers are implemented.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+In the directory of your Medusa server, run the following command after updating the server:
+
+```bash
+medusa migrations run
+```
+
+### Run Migration Script
+
+Following the fix gift cards calculation, you also need to run a migration script after updating the server.
+
+Start by adding the following environment variables in `.env`:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=
+TYPEORM_USERNAME=
+TYPEORM_PASSWORD=
+TYPEORM_DATABASE=
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+Make sure to replace ``, ``, ``, and `` with your database connection details.
+
+Then, run the following command in the root directory of your Medusa server:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/gift-card-tax-rate-migration.js
+```
+
+### Change to JobSchedulerService
+
+In your loader file that creates a cron job, replace the use of `eventBus` to `jobSchedulerService`:
+
+```ts
+const myJob = async (container, options) => {
+ const jobSchedulerService = container.resolve("jobSchedulerService")
+ jobSchedulerService.create("my-job", {}, "0 0 * * *", async () => {
+ // ...
+ })
+}
+
+export default myJob
+```
+
+You can learn more in the [How to Create a Scheduled Job](../scheduled-jobs/create.md) documentation.
+
+### Change to Payment Provider
+
+This version of Medusa introduces a change in how payment providers are implemented. Mainly, the signature of the `createPayment` and `updatePayment` methods have changed, and the old signature is now deprecated.
+
+Although this change is currently backwards compatible, it is recommended to change the signature of these methods to the following:
+
+
+
+```ts
+import { PaymentContext, PaymentSessionResponse } from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentService {
+ // ...
+ async createPayment(
+ context: PaymentContext
+ ): Promise {
+ // ...
+ }
+
+ async updatePayment(
+ paymentSessionData: PaymentSessionData,
+ context: PaymentContext
+ ): Promise {
+ // ...
+ }
+}
+```
+
+Where `context` in both `createPayment` and `updatePayment` is made up of the following properties:
+
+```ts
+type PaymentContext = {
+ cart: {
+ context: Record
+ id: string
+ email: string
+ shipping_address: Address | null
+ shipping_methods: ShippingMethod[]
+ }
+ currency_code: string
+ amount: number
+ resource_id?: string
+ customer?: Customer
+}
+```
+
+So, you can pass the previous `cart` parameter inside the new `context` paramter.
+
+Furthermore, these methods are now expected to return `PaymentSessionResponse`. It is made up of the following properties:
+
+```ts
+type PaymentSessionResponse = {
+ update_requests: { customer_metadata: Record }
+ session_data: Record
+}
+```
+
+Where `session_data` would include the previously returned data from these methods. The property `update_requests` allows you to pass data from the payment provider plugin to the core to update internal resources. Currently, it can only be used to update the `metadata` field of the customer entity.
diff --git a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md
index ffe9ddc266..07b20e27f0 100644
--- a/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md
+++ b/docs/content/advanced/backend/upgrade-guides/admin/admin-vite.md
@@ -12,6 +12,8 @@ Medusa Admin previously was built using Gatsby. As of a recent update, the Admin
This introduced breaking changes related to environment variables used and the published directory. Read below for actions required following this update.
+---
+
## Required Node.js Version
@@ -20,6 +22,8 @@ Following the change to Vite 3, the required Node.js version for the Admin has c
+---
+
## Changed Environment Variables
Previously, the Medusa Admin used the environment variables `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` to store the Medusa server’s URL.
@@ -36,6 +40,8 @@ Change your `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` environment variab
MEDUSA_BACKEND_URL=
```
+---
+
## Changed Publish Directory
Previously, the build output of the Medusa Admin was placed in the `dist` directory. After this update, the build output is placed in the `public` directory.
diff --git a/docs/content/advanced/ecommerce/handle-order-claim-event.md b/docs/content/advanced/ecommerce/handle-order-claim-event.md
index 5b5d08a750..2b394871ba 100644
--- a/docs/content/advanced/ecommerce/handle-order-claim-event.md
+++ b/docs/content/advanced/ecommerce/handle-order-claim-event.md
@@ -14,11 +14,13 @@ When the customer requests to claim the order, the event `order-update-token.cre
In this document, you’ll learn how to handle the `order-update-token.created` event on the server to send the customer a confirmation email.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
### Redis
@@ -30,6 +32,8 @@ To send an email or another type of notification method, you must have a notific
This document has an example using the [SendGrid](../../add-plugins/sendgrid.mdx) plugin.
+---
+
## Step 1: Create a Subscriber
To subscribe to and handle an event, you must create a subscriber.
@@ -43,7 +47,7 @@ You can learn more about subscribers in the [Subscribers](../backend/subscribers
Create the file `src/subscribers/claim-order.ts` with the following content:
```ts title=src/subscribers/claim-order.ts
-import { EventBusService } from "@medusajs/medusa";
+import { EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService,
@@ -55,7 +59,7 @@ class ClaimOrderSubscriber {
}
}
-export default ClaimOrderSubscriber;
+export default ClaimOrderSubscriber
```
If you want to add any other dependencies, you can add them to the `InjectedDependencies` type.
@@ -66,13 +70,21 @@ You can learn more about dependency injection in [this documentation](../backend
:::
+---
+
## Step 2: Subscribe to the Event
In the subscriber you created, add the following in the `constructor`:
```ts title=src/subscribers/claim-order.ts
-constructor({ eventBusService }: InjectedDependencies) {
- eventBusService.subscribe("order-update-token.created", this.handleRequestClaimOrder);
+class ClaimOrderSubscriber {
+ constructor({ eventBusService }: InjectedDependencies) {
+ eventBusService.subscribe(
+ "order-update-token.created",
+ this.handleRequestClaimOrder
+ )
+ }
+ // ...
}
```
@@ -84,14 +96,14 @@ In the subscriber, add a new method `handleRequestClaimOrder`:
```ts title=src/subscribers/claim-order.ts
class ClaimOrderSubscriber {
- //...
+ // ...
- handleRequestClaimOrder = async (data) {
- //TODO: handle event
+ handleRequestClaimOrder = async (data) => {
+ // TODO: handle event
}
}
-export default ClaimOrderSubscriber;
+export default ClaimOrderSubscriber
```
The `handleRequestClaimOrder` event receives a `data` object as a parameter. This object holds the following properties:
@@ -105,12 +117,14 @@ In this method, you should typically send an email to the customer’s old email
The page would then send a request to the server to verify that the `token` is valid and associate the order with the customer. You can read more about how to implement this in your storefront in [this documentation](../storefront/implement-claim-order.mdx).
+---
+
## Example: Using SendGrid
For example, you can implement this subscriber to send emails using SendGrid:
```ts title=src/subscribers/claim-order.ts
-import { EventBusService } from "@medusajs/medusa";
+import { EventBusService } from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService,
@@ -118,32 +132,37 @@ type InjectedDependencies = {
}
class ClaimOrderSubscriber {
- protected sendGridService: any;
+ protected sendGridService: any
constructor({ eventBusService, sendgridService }: InjectedDependencies) {
- this.sendGridService = sendgridService;
- eventBusService.subscribe("order-update-token.created", this.handleRequestClaimOrder);
+ this.sendGridService = sendgridService
+ eventBusService.subscribe(
+ "order-update-token.created",
+ this.handleRequestClaimOrder
+ )
}
handleRequestClaimOrder = async (data) => {
this.sendGridService.sendEmail({
- templateId: 'order-claim-confirmation',
- from: 'hello@medusajs.com',
+ templateId: "order-claim-confirmation",
+ from: "hello@medusajs.com",
to: data.old_email,
data: {
- link: `http://example-storefront.com/confirm-order-claim/${data.token}`,
- //other data...
- }
+ link: `http://example.com/confirm-order-claim/${data.token}`,
+ // other data...
+ },
})
}
}
-export default ClaimOrderSubscriber;
+export default ClaimOrderSubscriber
```
Notice how the `token` is passed to the storefront link as a parameter.
+---
+
## See Also
-- Learn [how to implement claim-order flow in your storefront](../storefront/implement-claim-order.mdx).
\ No newline at end of file
+- [Implement claim-order flow in your storefront](../storefront/implement-claim-order.mdx)
diff --git a/docs/content/advanced/storefront/customer-profiles.mdx b/docs/content/advanced/storefront/customer-profiles.mdx
new file mode 100644
index 0000000000..d950a13b8d
--- /dev/null
+++ b/docs/content/advanced/storefront/customer-profiles.mdx
@@ -0,0 +1,550 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Implement Customer Profiles
+
+In this document, you’ll learn how to implement customer account functionalities in a storefront.
+
+## Overview
+
+Medusa provides the necessary functionalities and endpoints to allow integrating essential customer features. Customers can create accounts to manage their information and keep track of their orders.
+
+### Scenario
+
+You want to implement the following features in a storefront:
+
+- Customer registration
+- Customer login and logout
+- Allow customers to reset their password
+- Allow customers to manage their basic information and shipping addresses
+- Show customers their orders
+
+:::note
+
+You can use Medusa’s Store APIs to achieve more functionalities as well. Check out the [API reference](/api/store/#tag/Customer) to learn more.
+
+:::
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
+
+It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client and JavaScript’s Fetch API.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration).
+
+---
+
+## Register a Customer
+
+A customer can register with an email and a password to store and manage their data.
+
+You can register a new customer by sending a request to the [Create a Customer](/api/store/#tag/Customer/operation/PostCustomers) endpoint:
+
+
+
+
+```ts
+medusa.customers.create({
+ email,
+ password,
+ first_name,
+ last_name,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ email,
+ password,
+ first_name,
+ last_name,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires the following body parameters:
+
+- `email`: An email used to log in after registration. This email must be unique. You can check if an email is unique using the “[Check if email exists](/api/store/#tag/Auth/operation/GetAuthEmail)” endpoint.
+- `password`: A password used to log in after registration.
+- `first_name`: The customer’s first name.
+- `last_name`: The customer’s last name.
+
+This request also accepts optional body parameters, which you can check out in the [API reference](/api/store/#tag/Customer/operation/PostCustomers).
+
+It returns the created customer object in the response.
+
+---
+
+## Log in a Customer
+
+A customer can log in to your store to manage their data and make purchases using their account.
+
+You can log in a customer into your store by sending a request to the [Customer Login](/api/store/#tag/Auth/operation/PostAuth) endpoint:
+
+
+
+
+```ts
+medusa.auth.authenticate({
+ email,
+ password,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/auth`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ email,
+ password,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires the body parameters `email` and `password`. It returns the customer object in the response.
+
+If you’re using the Medusa JS Client, the customer’s session will already be set and used in all future requests.
+
+However, if you’re using the Fetch API, you must include the option `credentials` with the value `include` to make sure all future requests are authenticated.
+
+---
+
+## Log out a Customer
+
+You can log out a customer by sending a request to the [Customer Logout](/api/store/#tag/Auth/operation/DeleteAuth) endpoint:
+
+
+
+
+```ts
+medusa.auth.deleteSession()
+.then(() => {
+ // success
+})
+```
+
+
+
+
+```ts
+fetch(`/store/auth`, {
+ method: "DELETE",
+ credentials: "include",
+})
+.then(() => {
+ // success
+})
+```
+
+
+
+
+If this request is successful, the customer’s session will be deleted and they’ll be logged out.
+
+---
+
+## Reset Password
+
+Customers might need to reset their password in case they forget it. To reset a customer’s password, you need to implement two steps.
+
+### Step 1: Request Password Reset
+
+The customer must first enter their account’s email. Then, if an account with that email address exists, an email will be sent to that email address with a link that points the customer to step 2.
+
+You can request to reset a customer’s password by sending a request to the [Request Password Reset](/api/store/#tag/Customer/operation/PostCustomersCustomerPasswordToken) endpoint:
+
+
+
+
+```ts
+medusa.customers.generatePasswordToken({
+ email,
+})
+.then(() => {
+ // successful
+})
+.catch(() => {
+ // failed
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/password-token`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ email,
+ }),
+})
+.then(() => {
+ // successful
+})
+.catch(() => {
+ // failed
+})
+```
+
+
+
+
+This request requires the body parameter `email`. Its value must be the email associated with the customer’s account.
+
+If the request has been processed successfully, it returns a `204` status code in the response. In case it fails, an error will be thrown.
+
+:::note
+
+If the customer doesn’t receive an email after this request, make sure that you’ve set up a Notification provider like [SendGrid](../../add-plugins/sendgrid.mdx) successfully. You also need to add a subscriber that handles the [customer.password_reset](../backend/subscribers/events-list.md#customer-events) event and sends the email.
+
+:::
+
+### Step 2: Verify and Reset Password
+
+After the first step, the customer should receive an email with a link to a page in the storefront. This page should accept a `token` query parameter. Then, the customer should be prompted to enter their email and password.
+
+You can then reset the customer’s password to the new password they enter by sending a request to the [Reset Password](/api/store/#tag/Customer/operation/PostCustomersResetPassword) endpoint:
+
+
+
+
+```ts
+medusa.customers.resetPassword({
+ email,
+ password,
+ token,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/password-reset`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ email,
+ password,
+ token,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires the following body parameters:
+
+- `email`: The email of the customer. This must be the email associated with the account.
+- `password`: The new password the customer wants to use for their account.
+- `token`: The token passed as a query into the page.
+
+If successful, this request returns the customer object in the response.
+
+---
+
+## Edit a Customer’s Info
+
+A logged-in customer can edit their info, such as their first name or email address.
+
+You can edit a customer’s info using the [Update Customer](/api/store/#tag/Customer/operation/PostCustomersCustomer) endpoint:
+
+
+
+
+```ts
+medusa.customers.update({
+ first_name,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/me`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ first_name,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request accepts any of the customer’s details that should be updated as body parameters. In the example above, the `first_name` of the customer is updated. You can check out the [API reference](/api/store/#tag/Customer/operation/PostCustomersCustomer) for a full list of accepted body parameters.
+
+It returns in the response the updated customer object.
+
+---
+
+## Manage Shipping Addresses
+
+A logged-in customer uses their shipping addresses during the checkout process. They can have more than one shipping address, and they can choose one of them when placing an order.
+
+:::tip
+
+The customer object returned in the requests mentioned in this document include a `shipping_addresses` property. It’s an array of the customer’s shipping addresses. You can access it to display the customer’s shipping addresses.
+
+:::
+
+### Add a Shipping Address
+
+You can add a shipping address to a customer’s account by sending a request to the [Add a Shipping Address](/api/store/#tag/Customer/operation/PostCustomersCustomerAddresses) endpoint:
+
+
+
+
+```ts
+medusa.customers.addresses.addAddress({
+ address: {
+ first_name,
+ last_name,
+ address_1,
+ city,
+ country_code,
+ postal_code,
+ phone,
+ company,
+ address_2,
+ province,
+ metadata,
+ },
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/me/addresses`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ address: {
+ first_name,
+ last_name,
+ address_1,
+ city,
+ country_code,
+ postal_code,
+ phone,
+ company,
+ address_2,
+ province,
+ metadata,
+ },
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires an `address` object as a body parameter. The `address` object must have the following properties:
+
+- `first_name`: The first name associated with the shipping address
+- `last_name`: The last name associated with the shipping address
+- `address_1`: The first address line of the shipping address.
+- `city`: The city of the shipping address.
+- `country_code`: The 2 character ISO code of the country in lower case.
+- `postal_code`: The postal code of the shipping address
+
+It also accepts other optional body parameters, which you can learn more about in the [API reference](/api/store/#tag/Customer/operation/PostCustomersCustomerAddresses).
+
+This request returns the updated customer object in the response.
+
+### Edit a Shipping Address
+
+You can edit a customer’s shipping address using the [Update a Shipping Address](/api/store/#tag/Customer/operation/PostCustomersCustomerAddressesAddress) endpoint:
+
+
+
+
+```ts
+medusa.customers.addresses.updateAddress(addressId, {
+ first_name,
+})
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/me/addresses/${addressId}`, {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ first_name,
+ }),
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires the address’s ID as a path parameter. It accepts as a body parameter any of the address’s properties. In the example above, the `first_name` of the shipping address is updated. You can check the [API reference](/api/store/#tag/Customer/operation/PostCustomersCustomerAddressesAddress) for all the available body parameters.
+
+This request returns the updated customer object in the response.
+
+### Delete a Shipping Address
+
+You can delete a shipping address by sending a request to the [Delete an Address](/api/store/#tag/Customer/operation/DeleteCustomersCustomerAddressesAddress) endpoint:
+
+
+
+
+```ts
+medusa.customers.addresses.deleteAddress(addressId)
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/me/addresses/${addressId}`, {
+ method: "DELETE",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ customer }) => {
+ console.log(customer.id)
+})
+```
+
+
+
+
+This request requires the address’s ID as a path parameter. It returns in the response the updated customer object.
+
+---
+
+## Retrieve a Customer’s Orders
+
+Logged-in customers can see their orders along with the orders’ details.
+
+You can retrieve a customer’s orders by sending a request to the [List Orders](/api/store/#tag/Customer/operation/GetCustomersCustomerOrders) endpoint:
+
+
+
+
+```ts
+medusa.customers.listOrders()
+.then(({ orders, limit, offset, count }) => {
+ console.log(orders)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/customers/me/orders`, {
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ orders, limit, offset, count }) => {
+ console.log(orders)
+})
+```
+
+
+
+
+This request doesn’t require any path or query parameters. You can, however, send optional query parameters used for filters, pagination, and sorting. You can learn more in the [API reference](/api/store/#tag/Customer/operation/GetCustomersCustomerOrders).
+
+It returns the following data in the response:
+
+- `orders`: An array of orders.
+- `limit`: The maximum number of orders that can be returned in the request.
+- `offset`: The number of orders skipped in the result.
+- `count`: The total number of orders available.
+
+:::info
+
+You can learn more about pagination in the [API reference](/api/store/#section/Pagination).
+
+:::
+
+---
+
+## See Also
+
+- [Implement order-claim flow](./implement-claim-order.mdx)
+- [Customers Store API reference](/api/store)
+- [Customers overview](../backend/customers/index.md)
+- [Manage customers using the admin APIs](../admin/manage-customers.mdx)
diff --git a/docs/content/advanced/storefront/handle-order-edits.mdx b/docs/content/advanced/storefront/handle-order-edits.mdx
new file mode 100644
index 0000000000..91ddeb5cda
--- /dev/null
+++ b/docs/content/advanced/storefront/handle-order-edits.mdx
@@ -0,0 +1,358 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Handle an Order Edit
+
+In this document, you’ll learn how to allow a customer to confirm or decline an Order Edit.
+
+:::note
+
+The Order Editing feature is currently in beta mode and guarded by a feature flag. To use Order Editing either:
+
+1. Enable the `MEDUSA_FF_ORDER_EDITING` environment variable;
+2. Or enable the `order_editing` key in the Medusa server's settings.
+
+You can learn more about enabling it in the [feature flags](../backend/feature-flags/toggle.md) documentation.
+
+:::
+
+---
+
+## Overview
+
+A merchant can request to edit an order to make changes to its items. The change can include removing an item, adding a new item, and changing the quantity of an item in the original order.
+
+When the Order Edit is in the “request” state, it requires either a confirmation from the customer, or it can be force-confirmed by the merchant.
+
+This guide focuses on how to use the Storefront APIs to implement the flow that allows a customer to either confirm or decline an Order Edit.
+
+:::note
+
+You can check out how to implement order editing using the Admin APIs in [this documentation](../admin/order-edit.mdx).
+
+:::
+
+### Scenarios
+
+You want to implement the following functionalities in your storefront:
+
+- List and show customers order-edit requests.
+- Confirm order edits and authorize any additional payment if necessary.
+- Decline order edits.
+
+:::note
+
+You can perform other functionalities related to order editing. To learn more, check out the API reference.
+
+:::
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
+
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client and JavaScript’s Fetch API.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration).
+
+### Previous Steps
+
+You must have an existing order edit in the “request” state.
+
+---
+
+## Retrieve an Order Edit
+
+You can retrieve a single order edit by its ID by sending a request to the [Get Order Edit](/api/store/#tag/OrderEdit/operation/GetOrderEditsOrderEdit) endpoint:
+
+
+
+
+```ts
+medusa.orderEdits.retrieve(orderEditId)
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+ // show changed items to the customer
+})
+```
+
+
+
+
+```ts
+fetch(`/store/order-edits/${orderEditId}`)
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.changes)
+ // show changed items to the customer
+})
+```
+
+
+
+
+The request requires the order edit’s ID as a path parameter.
+
+It returns the Order Edit as an object. Some of its important fields are:
+
+- `order_id`: The ID of the order that this Order Edit belongs to.
+- `difference_due`: The amount to either be refunded or paid. If the amount is greater than 0, then the customer is required to pay an additional amount. If the amount is less than 0, then the merchant has to refund the difference to the customer.
+- `payment_collection_id`: The ID of the payment collection. This will be used to authorize additional payment if necessary.
+
+:::note
+
+You can learn more about what fields to expect in the [API reference](/api/store/#tag/OrderEdit/operation/GetOrderEditsOrderEdit).
+
+:::
+
+### Show Changed Items
+
+All data about changes to the original order’s items can be found in `order_edit.changes`. `changes` is an array of item changes. Each item change includes the following fields:
+
+
+
+```ts
+{
+ type: string,
+ line_item: LineItem | null,
+ original_line_item: LineItem | null
+}
+```
+
+`type` can be either:
+
+- `item_add`: In this case, a new item is being added. `line_item` will be an item object and `original_line_item` will be `null`.
+- `item_update`: In this case, an item’s quantity in the original order is updated. `line_item` will be the updated item, and `original_line_item` will be the item in the original order. You can either just use `line_item` to show the new quantity, or show the customer a comparison between the old and new quantity using `original_line_item` as well.
+- `item_remove`: In this case, an item in the original order is removed. The `original_line_item` will be the item in the original order, and `line_item` will be `null`.
+
+Here’s an example of how you can use this data to show the customer the requested edits to the order:
+
+```jsx
+
+
+
+```ts
+medusa.paymentCollections.managePaymentSession(paymentCollectionId, {
+ provider_id,
+})
+.then(({ payment_collection }) => {
+ console.log(payment_collection.payment_sessions)
+})
+```
+
+
+
+
+```ts
+fetch(
+ `/store/payment-collections/${paymentCollectionId}/sessions`,
+ {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ provider_id,
+ }),
+ }
+)
+.then((response) => response.json())
+.then(({ payment_collection }) => {
+ console.log(payment_collection.payment_sessions)
+})
+```
+
+
+
+
+1. Show the customer the payment details form based on the payment session’s provider. For example, if the provider ID of a payment session is `stripe`, you must show Stripe’s card component to enter the customer’s card details.
+2. Authorize the payment using the payment provider. The [Authorize Payment Session](/api/store/#tag/Payment/operation/PostPaymentCollectionsSessionsSessionAuthorize) endpoint accepts the payment collection’s ID and the ID of the payment session as path parameters:
+
+
+
+
+```ts
+medusa.paymentCollection
+ .authorizePaymentSession(paymentCollectionId, paymentSessionId)
+.then(({ payment_session }) => {
+ console.log(payment_session.id)
+})
+```
+
+
+
+
+```ts
+fetch(
+ `/store/payment-collection/${paymentCollectionId}` +
+ `/sessions/${paymentSessionId}/authorize`,
+ {
+ method: "POST",
+ credentials: "include",
+ }
+)
+.then((response) => response.json())
+.then(({ payment_session }) => {
+ console.log(payment_session.id)
+})
+```
+
+
+
+
+After performing the above steps, you can [complete the Order Edit](#complete-the-order-edit).
+
+---
+
+## Complete the Order Edit
+
+To confirm and complete the order edit, send a request to the [Complete Order Edit](/api/store/#tag/OrderEdit/operation/PostOrderEditsOrderEditComplete) endpoint:
+
+
+
+
+```ts
+medusa.orderEdits.complete(orderEditId)
+.then(({ order_edit }) => {
+ console.log(order_edit.confirmed_at)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/order-edits/${orderEditId}/complete`, {
+ method: "POST",
+ credentials: "include",
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.confirmed_at)
+})
+```
+
+
+
+
+This request accepts the order edit’s ID as a path parameter.
+
+It returns the full Order Edit object. You can find properties related to the order confirmation, such as `order_edit.confirmed_at`.
+
+After completing the order edit, the changes proposed in the Order Edit are reflected in the original order.
+
+:::info
+
+If the payment isn’t authorized first, the order edit completion will fail.
+
+:::
+
+---
+
+## Decline an Order Edit
+
+If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit endpoint:
+
+
+
+
+```ts
+medusa.orderEdits.decline(orderEditId, {
+ decline_reason: "I am not satisfied",
+})
+.then(({ order_edit }) => {
+ console.log(order_edit.declined_at)
+})
+```
+
+
+
+
+```ts
+fetch(`/store/order-edits/${orderEditId}/decline`, {
+ method: "POST",
+ credentials: "include",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ decline_reason: "I am not satisfied",
+ }),
+})
+.then((response) => response.json())
+.then(({ order_edit }) => {
+ console.log(order_edit.declined_at)
+})
+```
+
+
+
+
+The request requires passing the order edit’s ID as a path parameter.
+
+In the request body parameters, you can optionally pass the `decline_reason` parameter. It’s a string that indicates to the merchant the reason the customer declined the order edit.
+
+If the Order Edit is declined, the changes requested in the Order Edit aren't reflected on the original order and no refund or additional payments are required.
+
+---
+
+## See Also
+
+- [Order Edit API reference](/api/store/#tag/OrderEdit)
+- [Edit an order using Admin APIs](../admin/order-edit.mdx)
diff --git a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx b/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx
index f6f8a99602..307d7c276b 100644
--- a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx
+++ b/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx
@@ -17,13 +17,15 @@ It’s recommended to go through the [Shipping Architecture Overview](../backend
:::
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -37,6 +39,8 @@ This document assumes you’ve already taken care of the add-to-cart flow. So, y
You can learn how to implement the cart flow using [this documentation](../../guides/carts-in-medusa.mdx).
+---
+
## Shipping Step
In this step, the customer generally enters their shipping info, then chooses the available shipping option based on the entered info.
@@ -60,11 +64,11 @@ medusa.carts.update(cartId, {
country_code,
province,
postal_code,
- phone
+ phone,
},
})
.then(({ cart }) => {
- console.log(cart.shipping_address);
+ console.log(cart.shipping_address)
})
```
@@ -73,8 +77,8 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
shipping_address: {
company,
@@ -86,17 +90,17 @@ fetch(`/store/carts/${cartId}`, {
country_code,
province,
postal_code,
- phone
+ phone,
},
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then((response) => response.json())
.then(({ cart }) => {
- console.log(cart.shipping_address);
-});
+ console.log(cart.shipping_address)
+})
```
@@ -106,6 +110,8 @@ This request accepts the ID of the cart as a path parameter and the new shipping
The request returns the updated cart, with the new shipping address available in `cart.shipping_address`.
+---
+
### List Shipping Options
After updating the cart with the customer’s address, the list of available [shipping options](../backend/shipping/overview.md#shipping-option) for that cart might change. So, you should retrieve the updated list of options.
@@ -118,7 +124,7 @@ You can retrieve the list of shipping options by sending a `GET` request to the
```jsx
medusa.shippingOptions.listCartOptions(cartId)
.then(({ shipping_options }) => {
- console.log(shipping_options.length);
+ console.log(shipping_options.length)
})
```
@@ -127,11 +133,11 @@ medusa.shippingOptions.listCartOptions(cartId)
```jsx
fetch(`/store/shipping-options/${cartId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ shipping_options }) => {
- console.log(shipping_options.length);
+ console.log(shipping_options.length)
})
```
@@ -149,7 +155,7 @@ Once the customer chooses one of the available shipping options, send a `POST` r
```jsx
medusa.carts.addShippingMethod(cartId, {
- option_id: shippingOptionId //the ID of the selected option
+ option_id: shippingOptionId, // the ID of the selected option
})
.then(({ cart }) => {
console.log(cart.shipping_methods)
@@ -161,14 +167,14 @@ medusa.carts.addShippingMethod(cartId, {
```jsx
fetch(`/store/carts/${cartId}/shipping-methods`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
- option_id: shippingOptionId //the ID of the selected option
+ option_id: shippingOptionId, // the ID of the selected option
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then((response) => response.json())
.then(({ cart }) => {
@@ -183,6 +189,8 @@ The request accepts the ID of the cart as a path parameter and its body the ID o
It returns the updated cart, with the created shipping method available in the array `cart.shipping_methods`.
+---
+
## Payment Step
In this step, the customer generally chooses a payment method to complete their purchase. The implementation of payment providers is done differently for each provider, so this section will just show the general steps you should follow when implementing this step.
@@ -208,8 +216,8 @@ medusa.carts.createPaymentSessions(cartId)
```jsx
fetch(`/store/carts/${cartId}/payment-sessions`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ cart }) => {
@@ -231,7 +239,8 @@ When the customer chooses the payment provider they want to complete purchase wi
```jsx
medusa.carts.setPaymentSession(cartId, {
- provider_id: paymentProviderId // retrieved from the payment session selected by the customer
+ // retrieved from the payment session selected by the customer
+ provider_id: paymentProviderId,
})
.then(({ cart }) => {
console.log(cart.payment_session)
@@ -243,14 +252,15 @@ medusa.carts.setPaymentSession(cartId, {
```jsx
fetch(`/store/carts/${cartId}/payment-session`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
- provider_id: paymentProviderId // retrieved from the payment session selected by the customer
+ // retrieved from the payment session selected by the customer
+ provider_id: paymentProviderId,
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then((response) => response.json())
.then(({ cart }) => {
@@ -283,10 +293,10 @@ If you need to update that data at any point before the purchase is made, send a
```jsx
medusa.carts.updatePaymentSession(cartId, paymentProviderId, {
data: {
- //pass any data you want to add in the `data` attribute
- //for example:
- "test": true
- }
+ // pass any data you want to add in the `data` attribute
+ // for example:
+ "test": true,
+ },
})
.then(({ cart }) => {
console.log(cart.payment_session.data)
@@ -296,21 +306,26 @@ medusa.carts.updatePaymentSession(cartId, paymentProviderId, {
+
+
```jsx
-fetch(`/store/carts/${cartId}/payment-sessions/${paymentProviderId}`, {
- method: 'POST',
- credentials: 'include',
- body: JSON.stringify({
- data: {
- //pass any data you want to add in the `data` attribute
- //for example:
- "test": true
- }
- }),
- headers: {
- 'Content-Type': 'application/json'
+fetch(
+ `/store/carts/${cartId}/payment-sessions/${paymentProviderId}`,
+ {
+ method: "POST",
+ credentials: "include",
+ body: JSON.stringify({
+ data: {
+ // pass any data you want to add in the `data` attribute
+ // for example:
+ "test": true,
+ },
+ }),
+ headers: {
+ "Content-Type": "application/json",
+ },
}
-})
+)
.then((response) => response.json())
.then(({ cart }) => {
console.log(cart.payment_session.data)
@@ -336,7 +351,7 @@ To complete a cart, send a `POST` request to the [Complete a Cart](/api/store/#t
```jsx
medusa.carts.complete(cartId)
.then(({ type, data }) => {
- console.log(type, data);
+ console.log(type, data)
})
```
@@ -345,15 +360,15 @@ medusa.carts.complete(cartId)
```jsx
fetch(`/store/carts/${cartId}/complete`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then((response) => response.json())
.then(({ type, data }) => {
- console.log(type, data);
+ console.log(type, data)
})
```
@@ -366,8 +381,11 @@ The request returns two properties: `type` and `data`. If the order was placed s
If an error occurred while placing the order, `type` will be `cart` and `data` will be the cart's data.
-## What’s Next
+---
-- Learn more about the [JS Client and how to use it](../../js-client/overview.md).
+## See Also
+
+- [Medusa JS Client Overview](../../js-client/overview.md).
- Check out available plugins for popular payment providers such as [Stripe](../../add-plugins/stripe.md) and [PayPal](/add-plugins/paypal.md).
-- Learn more about the [Payment](../backend/payment/overview.md) and [Shipping](../backend/shipping/overview.md) Architectures.
+- [Payment Architecture](../backend/payment/overview.md)
+- [Shipping Architecture](../backend/shipping/overview.md)
diff --git a/docs/content/advanced/storefront/implement-claim-order.mdx b/docs/content/advanced/storefront/implement-claim-order.mdx
index 00ba56203a..ea62a6dd7c 100644
--- a/docs/content/advanced/storefront/implement-claim-order.mdx
+++ b/docs/content/advanced/storefront/implement-claim-order.mdx
@@ -32,13 +32,15 @@ In this document, you’ll learn how to implement two parts of this flow:
1. Allow customers to claim their orders.
2. Verify a claim to an order.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -58,6 +60,8 @@ It is assumed you already have an order placed by a guest customer. You can refe
In addition, it is assumed you already have a logged-in customer before performing the steps in this document. You can refer to the [API reference](/api/store/#tag/Auth/operation/PostAuth) for more details on that.
+---
+
## Request to Claim an Order
When the customer wants to claim an order, they must supply its ID.
@@ -78,7 +82,7 @@ medusa.orders.claimOrders({
})
.catch(() => {
// an error occurred
-});
+})
```
@@ -86,23 +90,23 @@ medusa.orders.claimOrders({
```tsx
fetch(`/store/orders/batch/customer/token`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
order_ids: [
order_id,
],
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then(() => {
- //successful
+ // successful
})
.catch(() => {
- //display an error to the customer
-});
+ // display an error to the customer
+})
```
@@ -114,6 +118,8 @@ If the customer’s request has been processed successfully, the request returns
The customer at this point will receive an email with a link to verify their claim on the order.
+---
+
## Manually Verify a Claim to an Order
The link in the email that the customer receives should be a page in your storefront that accepts a `token` query parameter.
@@ -125,14 +131,14 @@ Then, you send a request to the Verify Claim Order endpoint:
```tsx
medusa.orders.confirmRequest({
- token
+ token,
})
.then(() => {
// successful
})
.catch(() => {
// an error occurred
-});
+})
```
@@ -140,21 +146,21 @@ medusa.orders.confirmRequest({
```tsx
fetch(`/store/orders/customer/confirm`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
- token
+ token,
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then(() => {
- //successful
+ // successful
})
.catch(() => {
- //display an error to the customer
-});
+ // display an error to the customer
+})
```
@@ -164,6 +170,8 @@ This request accepts as a body parameter the string `token`. This would be the t
If the verification is successful, the order will now be associated with the customer and the customer will be able to see it among their orders.
+---
+
## See Also
-- Learn [how to send a confirmation email to claim an order](../ecommerce/handle-order-claim-event.md).
+- [Send a confirmation email to claim an order](../ecommerce/handle-order-claim-event.md)
diff --git a/docs/content/advanced/storefront/use-discounts-in-checkout.mdx b/docs/content/advanced/storefront/use-discounts-in-checkout.mdx
index 0ba1288532..e7398ffaaa 100644
--- a/docs/content/advanced/storefront/use-discounts-in-checkout.mdx
+++ b/docs/content/advanced/storefront/use-discounts-in-checkout.mdx
@@ -17,17 +17,19 @@ Customers can use discounts during checkout to benefit from promotions that the
In this document, you’ll learn how to add a discount to a cart, how to display details related to the discount, and how to remove a discount from a cart.
-## Scenario
+### Scenario
You want to implement discount functionality in your store to allow customers to apply discount codes to their cart and remove them from the cart. You also want to display the discount details for the customer.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -41,6 +43,8 @@ This document assumes you’ve already taken care of the add-to-cart flow. So, y
You can learn how to implement the cart flow using [this documentation](../../guides/carts-in-medusa.mdx).
+---
+
## Add Discount to Cart
The customer can enter a discount code during the checkout flow to benefit from a promotion.
@@ -54,17 +58,17 @@ You can add a discount to a customer’s cart by sending the [Update Cart reques
medusa.carts.update(cartId, {
discounts: [
{
- code
- }
- ]
+ code,
+ },
+ ],
})
.then(({ cart }) => {
console.log(cart.discounts)
})
.catch((e) => {
- //display an error to the customer
- alert('Discount is invalid')
-});
+ // display an error to the customer
+ alert("Discount is invalid")
+})
```
@@ -72,27 +76,27 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
discounts: [
{
- code
- }
+ code,
+ },
],
}),
headers: {
- 'Content-Type': 'application/json'
- }
+ "Content-Type": "application/json",
+ },
})
.then((response) => response.json())
.then(({ cart }) => {
- console.log(cart.discounts);
+ console.log(cart.discounts)
})
.catch((e) => {
- //display an error to the customer
- alert('Discount is invalid')
-});
+ // display an error to the customer
+ alert("Discount is invalid")
+})
```
@@ -110,6 +114,8 @@ If the discount is applied successfully, the entire cart object will be returned
In case the customer enters an invalid discount or the discount cannot be applied to the cart because it doesn’t meet its conditions, the request will return an error. You can handle the error in the `catch` method.
+---
+
## Display Discount Details
After the customer enters a discount code and it is applied to the cart, you can display the discount details to the customer. This shows the customer how much they benefitted from the discount.
@@ -201,6 +207,8 @@ The returned `cart` object has the following properties that can be used to disp
- The `shipping_total` property is the total shipping amount. If a Free Shipping discount is applied to the cart, `shipping_total` and `discount_total` will be 0.
- The `total` property is the total amount of the cart after applying the discount.
+---
+
## Remove Discount from Cart
The customer can choose to remove a discount from their cart.
@@ -214,7 +222,7 @@ You can remove a discount from a customer’s cart using the [Remove Discount re
medusa.carts.deleteDiscount(cartId, code)
.then(({ cart }) => {
console.log(cart.discounts)
-});
+})
```
@@ -222,13 +230,13 @@ medusa.carts.deleteDiscount(cartId, code)
```jsx
fetch(`/store/carts/${cartId}/discounts/${code}`, {
- method: 'DELETE',
- credentials: 'include'
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ cart }) => {
- console.log(cart.discounts);
-});
+ console.log(cart.discounts)
+})
```
@@ -238,7 +246,9 @@ This request accepts the cart ID and the code of the discount to remove. If the
The totals of the cart and its items will be updated as well.
-## What’s Next
+---
-- Learn [how to implement the checkout flow](./how-to-implement-checkout-flow.mdx).
-- Learn [how to create discounts using the admin APIs](/api/admin/#tag/Discount/operation/PostDiscounts).
\ No newline at end of file
+## See Also
+
+- [Implement the checkout flow in a storefront](./how-to-implement-checkout-flow.mdx).
+- [Manage discounts using the admin APIs](../admin/manage-discounts.mdx).
diff --git a/docs/content/advanced/storefront/use-regions.mdx b/docs/content/advanced/storefront/use-regions.mdx
index afd29ea9c4..64f0be708f 100644
--- a/docs/content/advanced/storefront/use-regions.mdx
+++ b/docs/content/advanced/storefront/use-regions.mdx
@@ -23,9 +23,9 @@ You want to implement the following in your storefront:
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -47,9 +47,9 @@ You can retrieve available regions by sending a request to the [List Regions](/a
```tsx
medusa.regions.list()
.then(({ regions }) => {
- console.log(regions.length);
- //show customers available regions
-});
+ console.log(regions.length)
+ // show customers available regions
+})
```
@@ -57,13 +57,13 @@ medusa.regions.list()
```tsx
fetch(`/store/regions`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ regions }) => {
- console.log(regions.length);
- //show customers available regions
-});
+ console.log(regions.length)
+ // show customers available regions
+})
```
@@ -86,12 +86,12 @@ For example:
```tsx
medusa.products.list({
- region_id: regionId
+ region_id: regionId,
})
.then(({ products, limit, offset, count }) => {
- console.log(products.length);
- //show customer the products
-});
+ console.log(products.length)
+ // show customer the products
+})
```
@@ -99,13 +99,13 @@ medusa.products.list({
```tsx
fetch(`/store/products?region_id=${regionId}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
- console.log(products.length);
- //show customer the products
-});
+ console.log(products.length)
+ // show customer the products
+})
```
@@ -136,11 +136,11 @@ For example:
```tsx
medusa.carts.update(cartId, {
- region_id: regionId
+ region_id: regionId,
})
.then(({ cart }) => {
- console.log(cart.id);
-});
+ console.log(cart.id)
+})
```
@@ -148,16 +148,16 @@ medusa.carts.update(cartId, {
```tsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
body: JSON.stringify({
- region_id: regionId
- })
+ region_id: regionId,
+ }),
})
.then((response) => response.json())
.then(({ cart }) => {
- console.log(cart.id);
-});
+ console.log(cart.id)
+})
```
@@ -169,7 +169,7 @@ This request returns the full object of the updated cart.
---
-## What’s Next
+## See Also
-- Learn [how to implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx)
-- Learn [how to implement checkout in your storefront](./how-to-implement-checkout-flow.mdx)
\ No newline at end of file
+- [Implement cart functionalities in your storefront](../../guides/carts-in-medusa.mdx)
+- [Implement checkout in your storefront](./how-to-implement-checkout-flow.mdx)
diff --git a/docs/content/advanced/storefront/use-sales-channels.mdx b/docs/content/advanced/storefront/use-sales-channels.mdx
index 2473bf5455..712b53898f 100644
--- a/docs/content/advanced/storefront/use-sales-channels.mdx
+++ b/docs/content/advanced/storefront/use-sales-channels.mdx
@@ -11,13 +11,15 @@ In your storefront, you can filter products by sales channels. You can also asso
This guide explains how to perform these operations using the Storefront APIs.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.md) or [Gatsby](../../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -25,6 +27,8 @@ This guide includes code snippets to send requests to your Medusa server using M
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../js-client/overview.md) and have [created an instance of the client](../../js-client/overview.md#configuration).
+---
+
## Filter Products by Sales Channel
To filter products by a specific sales channel, pass the `sales_channel_id` query parameter to the List Products endpoint:
@@ -35,12 +39,12 @@ To filter products by a specific sales channel, pass the `sales_channel_id` quer
```jsx
medusa.products.list({
sales_channel_id: [
- salesChannelId
- ]
+ salesChannelId,
+ ],
})
.then(({ products, limit, offset, count }) => {
- console.log(products.length);
-});
+ console.log(products.length)
+})
```
@@ -51,7 +55,7 @@ fetch(`/store/products?sales_channel_id[0]=${salesChannelId}`)
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
console.log(products.length)
-});
+})
```
@@ -61,6 +65,8 @@ The `sales_channel_id` query parameter is an array of sales channel IDs. You can
The request returns an array of products. These are the products that are available in the sales channel.
+---
+
## Associate a Cart with a Sales Channel
### When Creating a Cart
@@ -73,11 +79,11 @@ To associate a sales channel with a cart while creating it, you can pass the `sa
```jsx
medusa.carts.create({
- sales_channel_id: salesChannelId
+ sales_channel_id: salesChannelId,
+})
+.then(({ cart }) => {
+ console.log(cart.id)
})
-.then(({cart}) => {
- console.log(cart.id);
-});
```
@@ -85,18 +91,18 @@ medusa.carts.create({
```jsx
fetch(`/store/carts`, {
- method: 'POST',
+ method: "POST",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- sales_channel_id: salesChannelId
- })
+ sales_channel_id: salesChannelId,
+ }),
})
.then((response) => response.json())
-.then(({cart}) => {
- console.log(cart.id);
-});
+.then(({ cart }) => {
+ console.log(cart.id)
+})
```
@@ -113,11 +119,11 @@ You can update the sales channel of an existing cart by passing the `sales_chann
```jsx
medusa.carts.update(cartId, {
- sales_channel_id: salesChannelId
+ sales_channel_id: salesChannelId,
+})
+.then(({ cart }) => {
+ console.log(cart.id)
})
-.then(({cart}) => {
- console.log(cart.id);
-});
```
@@ -125,16 +131,16 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
+ method: "POST",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- sales_channel_id: salesChannelId
- })
+ sales_channel_id: salesChannelId,
+ }),
})
.then((response) => response.json())
-.then(({cart}) => console.log(cart.id));
+.then(({ cart }) => console.log(cart.id))
```
@@ -142,7 +148,9 @@ fetch(`/store/carts/${cartId}`, {
The request returns the updated cart.
-## What’s Next 🚀
+---
-- Learn how to [Implement the Cart functionality in a storefront](../../guides/carts-in-medusa.mdx).
-- Learn how to [Implement the Checkout functionality in a storefront](./how-to-implement-checkout-flow.mdx).
\ No newline at end of file
+## See Also
+
+- [Implement the Cart functionality in a storefront](../../guides/carts-in-medusa.mdx)
+- [Implement the Checkout functionality in a storefront](./how-to-implement-checkout-flow.mdx)
diff --git a/docs/content/cli/reference.md b/docs/content/cli/reference.md
index 24adca335c..be638b79e3 100644
--- a/docs/content/cli/reference.md
+++ b/docs/content/cli/reference.md
@@ -8,6 +8,8 @@ The Medusa CLI serves as a tool that allows you to perform important commands wh
To use Medusa, it is required to install the CLI tool as it is used to create a new Medusa server.
+---
+
## How to Install CLI Tool
To install the CLI tool, run the following command in your terminal:
@@ -28,6 +30,8 @@ The CLI tool is then available under the `medusa` command. You can see all comma
medusa --help
```
+---
+
## Common Options
The following options can be used with all available commands.
@@ -84,6 +88,8 @@ If used inside a Medusa project, the version of the Medusa CLI and Medusa projec
medusa --version
```
+---
+
## Available Commands
### new
@@ -206,7 +212,9 @@ medusa telemetry
| `--enable` | Enable telemetry (default) |
| `--disable` | Disable telemetry |
-## What’s Next
+---
-- Learn more about [anonymous usage data collection](../usage.md).
-- Learn how to [configure your Medusa server](../usage/configurations.md).
+## See Also
+
+- [Configure your Medusa server](../usage/configurations.md)
+- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx)
diff --git a/docs/content/contribution-guidelines.md b/docs/content/contribution-guidelines.md
index 644a48550c..30d3fda391 100644
--- a/docs/content/contribution-guidelines.md
+++ b/docs/content/contribution-guidelines.md
@@ -14,27 +14,37 @@ The documentation website is built with [Docusaurus](https://docusaurus.io/), a
The documentation codebase is hosted as part of the [medusa repository](https://github.com/medusajs/medusa) on GitHub. You’ll find the code that runs the docusaurus website under the [www/docs](https://github.com/medusajs/medusa/tree/master/www/docs) directory.
+---
+
## Documentation Content
The documentation content is written in Markdown format and is located in the [docs/content](https://github.com/medusajs/medusa/tree/master/docs/content) directory of the same repository. If you’re not familiar with Markdown, check out [this cheat sheet](https://www.markdownguide.org/cheat-sheet/) for a quick start.
You’ll also find MDX files. MDX files combine the power of Markdown with React. So, the content of the file can contain JSX components and import statements, among other features. You can learn more about [MDX in docusaurus’s guide.](https://docusaurus.io/docs/markdown-features/react)
+---
+
## What You Can Contribute To
- You can contribute to the Docusaurus codebase to add a new feature or fix a bug in the documentation website.
- You can contribute to the documentation content either by fixing errors you find or by adding documentation pages.
+---
+
## What You Can’t Contribute To
The [Services Reference](/references/services/classes/AuthService) is an automatically generated API reference using Typedoc. So, you can’t contribute to it by making changes to its markdown files.
You can, however, contribute to the script generating it if you find any issues in it.
+---
+
## Style Guide
When you contribute to the documentation content, make sure to follow the [documentation style guide](https://www.notion.so/Style-Guide-Docs-fad86dd1c5f84b48b145e959f36628e0).
+---
+
## How to Contribute
If you’re fixing errors in an existing documentation page, you can scroll down to the end of the page and click on the “Edit this page” link. You’ll be redirected to the GitHub edit form of that page and you can make edits directly and submit a pull request (PR).
@@ -63,6 +73,8 @@ In the body of the PR, explain clearly what the PR does. If the PR solves an iss
+---
+
## Sidebar
When you add a new page to the documentation, you must add the new page in `www/docs/sidebars.js` under the `docsSidebar`. You can learn more about the syntax used [here](https://docusaurus.io/docs/sidebar/items).
@@ -77,6 +89,8 @@ When the documentation page is tutorial documentation, the label in the sidebar
The character count of the sidebar item's label must be at most twenty-seven characters. For the API Reference, the sidebar item's label must be at most twenty-five characters.
+---
+
## Notes and Additional Information
When displaying notes and additional information on a documentation page, use [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions). Make sure the type of admonition used matches the note’s importance to the current document.
@@ -89,10 +103,14 @@ If the note displays helpful information and tips use the `tip` admonition.
If the admonition does not match any of the mentioned criteria, always default to the `note` admonition.
+---
+
## Images
If you are adding images to a documentation page, you can host the image on [Imgur](https://imgur.com) for free.
+---
+
## Code Blocks
### Use Tabs with Code Blocks
@@ -112,10 +130,10 @@ import TabItem from '@theme/TabItem';
```jsx
-medusa.admin.uploads.create(file) //file is an instance of File
+medusa.admin.uploads.create(file) // file is an instance of File
.then(({ uploads }) => {
- const key = uploads[0].key;
-});
+ const key = uploads[0].key
+})
```
@@ -139,7 +157,10 @@ If you want to add a title to a code block with tabs, add the `codeTitle` prop t
For example:
```md
-
+
```
### Add Title to Code Block without Tabs
@@ -176,6 +197,8 @@ medusa new my-medusa-store --seed
```
~~~
+---
+
## NPM and Yarn Code Blocks
If you’re adding code blocks that use NPM and Yarn, you must use the [npm2yarn syntax](https://docusaurus.io/docs/markdown-features/code-blocks#npm2yarn-remark-plugin).
@@ -216,11 +239,13 @@ When a command uses the global option `-g`, add it at the end of the NPM command
npm install @medusajs/medusa-cli -g
```
+---
+
## Linting with Vale
Medusa uses Vale to lint documentation pages and perform checks on incoming PRs into the repository.
-### Result of PR Checks
+### Result of Vale PR Checks
You can check the result of running the "lint" action on your PR by clicking the Details link next to it. You can find there all errors that you need to fix.
@@ -269,6 +294,66 @@ Medusa supports Node versions 14 and 16.
If you use this in your PR, you must justify its usage.
+---
+
+## Linting with ESLint
+
+Medusa uses Eslint to lint code blocks in the documentation and perform checks on incoming PRs into the repository.
+
+### Result of ESLint PR Checks
+
+You can check the result of running the "eslint" action on your PR by clicking the Details link next to it. You can find there all errors that you need to fix.
+
+### Running ESLint locally
+
+If you want to check your work locally, you can do that by:
+
+1. Installing the dependencies in the root directory:
+
+```bash
+yarn install
+```
+
+2\. Run the lint command:
+
+```bash
+yarn lint:docs
+```
+
+You can also pass the `--fix` option to automatically fix errors.
+
+### ESLint Exceptions
+
+If some code blocks have errors that can't or shouldn't be fixed, you can add the following command before the code block:
+
+~~~md
+
+
+```js
+console.log("This block isn't linted")
+```
+
+```js
+console.log("This block is linted")
+```
+~~~
+
+You can also disable specific rules. For example:
+
+~~~md
+
+
+```js
+console.log("This block can use semicolons");
+```
+
+```js
+console.log("This block can't use semi colons")
+```
+~~~
+
+---
+
## Need Additional Help
If you need any additional help while contributing, you can join Medusa's [Discord server](https://discord.gg/medusajs) and ask Medusa’s core team as well as the community any questions.
diff --git a/docs/content/deployments/admin/deploying-on-netlify.md b/docs/content/deployments/admin/deploying-on-netlify.md
index 29b5a0185e..975c442e3f 100644
--- a/docs/content/deployments/admin/deploying-on-netlify.md
+++ b/docs/content/deployments/admin/deploying-on-netlify.md
@@ -16,7 +16,7 @@ Alternatively, you can use this button to deploy the Medusa Admin to Netlify dir
### Medusa Components
-Before proceeding with this documentation, it is assumed you already have a Medusa Admin installed locally. If not, please go through the [quickstart guide](../../admin/quickstart.md) first.
+Before proceeding with this documentation, it is assumed you already have a Medusa Admin installed locally. If not, please go through the [quickstart guide](../../admin/quickstart.mdx) first.
Additionally, this documentation does not cover how to deploy the Medusa server. If you want to deploy the Medusa server, check out one of the [deployment documentation related to the Medusa server](../server/index.mdx).
@@ -35,6 +35,8 @@ If you want to use another Git Provider, it’s possible to follow along with th
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
+---
+
## Create GitHub Repository
Before you can deploy your Medusa Admin you need to create a GitHub repository and push the code base to it.
@@ -74,6 +76,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to Netlify
This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool.
@@ -236,7 +240,6 @@ For the rest of the steps, you can keep most of the default values provided by N
? Directory to deploy (blank for current dir): public
```
-
#### Set Environment Variables
After the previous command has finished running, your Netlify website will be created. The next step is to add an environment variable that points to your Medusa server.
@@ -285,6 +288,8 @@ The Medusa Admin will then open in your browser.
Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa server.
+---
+
## Configure CORS Variable on the Medusa Server
To send requests to the Medusa server from the Medusa Admin, you must set the `ADMIN_CORS` environment variable on your server to the Medusa Admin’s URL.
@@ -305,7 +310,9 @@ Where `` is the URL of your Medusa Admin that you just deployed.
Then, restart your Medusa server. Once the server is running again, you can log in to the Medusa Admin and use it.
-## What’s Next
+---
-- Learn how to [deploy your storefront](../storefront/index.mdx).
-- Learn more about [how you can configure Medusa](../../usage/configurations.md).
+## See Also
+
+- [Deploy your storefront](../storefront/index.mdx)
+- [Configure your Medusa server](../../usage/configurations.md)
diff --git a/docs/content/deployments/server/deploying-on-digital-ocean.md b/docs/content/deployments/server/deploying-on-digital-ocean.md
index 617449359f..dffef96150 100644
--- a/docs/content/deployments/server/deploying-on-digital-ocean.md
+++ b/docs/content/deployments/server/deploying-on-digital-ocean.md
@@ -12,7 +12,7 @@ DigitalOcean is a reliable hosting provider that provides different ways to host
### Medusa Server
-It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.md).
+It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.mdx).
Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](../../usage/configurations.md) to learn how to do that.
@@ -31,6 +31,8 @@ If you want to use another Git Provider supported by DigitalOcean, it’s possib
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
+---
+
## Changes to package.json
Change the `start` script in `package.json` to the following:
@@ -41,6 +43,8 @@ Change the `start` script in `package.json` to the following:
This ensures that Migrations are run everytime the Medusa server is restarted.
+---
+
## Changes to medusa-config.js
In `medusa-config.js`, the `DATABASE_URL` variable is set to the environment variable `DATABASE_URL`. This needs to be changed as DigitalOcean provides the different details of the database connection separately.
@@ -48,13 +52,15 @@ In `medusa-config.js`, the `DATABASE_URL` variable is set to the environment var
Replace the previous declaration of `DATABASE_URL` in `medusa-config.js` with the following:
```js
-const DB_USERNAME = process.env.DB_USERNAME;
-const DB_PASSWORD = process.env.DB_PASSWORD;
-const DB_HOST = process.env.DB_HOST;
-const DB_PORT = process.env.DB_PORT;
-const DB_DATABASE = process.env.DB_DATABASE;
+const DB_USERNAME = process.env.DB_USERNAME
+const DB_PASSWORD = process.env.DB_PASSWORD
+const DB_HOST = process.env.DB_HOST
+const DB_PORT = process.env.DB_PORT
+const DB_DATABASE = process.env.DB_DATABASE
-const DATABASE_URL = `postgres://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}`;
+const DATABASE_URL =
+ `postgres://${DB_USERNAME}:${DB_PASSWORD}` +
+ `@${DB_HOST}:${DB_PORT}/${DB_DATABASE}`
```
In addition, you must add to `projectConfig` in the exported object a new property `database_extra`:
@@ -62,12 +68,14 @@ In addition, you must add to `projectConfig` in the exported object a new proper
```js
module.exports = {
projectConfig: {
- //...
- database_extra: { ssl: { rejectUnauthorized: false } }
+ // ...
+ database_extra: { ssl: { rejectUnauthorized: false } },
},
-};
+}
```
+---
+
## Create GitHub Repository
Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it.
@@ -107,6 +115,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to DigitalOcean App
After logging into your account, click on the Create button at the top right, then choose App.
@@ -240,6 +250,8 @@ In the new page, click on the Previously Created DigitalOcean Database radio but
Once you’re done click Attach Database. This will add the Redis database to the list of resources of your App and will trigger a redeploy of the App.
+---
+
## Test your Server
Once the redeployment is complete, copy the URL of the App which can be found under the App’s name.
@@ -250,6 +262,8 @@ Then, go to `/store/products`. If the deployment was successful, y
+---
+
## Run Commands on Your Server
To run commands on your server, you can access the console on the App’s page by choosing the Console tab. This opens a console in your browser where you can run commands on your server.
@@ -265,6 +279,8 @@ Make sure to replace `` and `` with the credentials you want to
+---
+
## Add Environment Variables
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
@@ -279,7 +295,9 @@ Then, scroll down and find Environment Variables. You can expand the environment
Once you click Save, the environment variables will be saved and a redeployment will be triggered.
-## What’s Next
+---
-- Learn [how to deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md).
-- Learn [how to deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md).
+## See Also
+
+- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md).
+- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md).
diff --git a/docs/content/deployments/server/deploying-on-heroku.mdx b/docs/content/deployments/server/deploying-on-heroku.mdx
index 9e2faad99d..57df2d8de9 100644
--- a/docs/content/deployments/server/deploying-on-heroku.mdx
+++ b/docs/content/deployments/server/deploying-on-heroku.mdx
@@ -26,7 +26,7 @@ Alternatively, you can use this button to deploy the Medusa server to Heroku dir
### Medusa Server
-It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.md).
+It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.mdx).
Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](../../usage/configurations.md) to learn how to do that.
@@ -39,6 +39,8 @@ Furthermore, your Medusa server should be configured to work with PostgreSQL and
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
- Heroku's CLI tool. You can follow [Heroku's documentation to learn how to install it for your operating system](https://devcenter.heroku.com/articles/heroku-cli).
+---
+
## Deploy to Heroku
### 1. Login to Heroku from your CLI
@@ -185,7 +187,7 @@ module.exports = {
: {},
},
plugins,
-};
+}
```
#### package.json
@@ -238,6 +240,8 @@ heroku logs -n 500000 --remote heroku --tail -a
Where `` is the name of the app.
+---
+
## Run Commands on Your Server
To run commands on your server, you can use the following command:
@@ -256,6 +260,8 @@ heroku run -a -- medusa user -e "" -p ""
Where `` is the name of your Heroku app, and `` and `` are the credentials you want to use to log in to the Medusa admin dashboard.
+---
+
## Add Environment Variables
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
@@ -268,7 +274,9 @@ heroku config:set = -a
Where `` is the name of your Heroku app, `` is the name of the environment variable, and `` is the value.
-## What's Next
+---
-- Learn how to [deploy your Medusa admin](../admin/index.mdx).
-- Learn how to [deploy your storefront](../storefront/index.mdx).
+## See Also
+
+- [Deploy your Medusa admin](../admin/index.mdx)
+- [Deploy your storefront](../storefront/index.mdx)
diff --git a/docs/content/deployments/server/deploying-on-qovery.md b/docs/content/deployments/server/deploying-on-qovery.md
index 1f2147459e..20e094a7fc 100644
--- a/docs/content/deployments/server/deploying-on-qovery.md
+++ b/docs/content/deployments/server/deploying-on-qovery.md
@@ -20,7 +20,7 @@ This tutorial explains how to deploy Medusa to a Qovery organization with an AWS
### Medusa Server
-It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.md).
+It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.mdx).
Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](../../usage/configurations.md) to learn how to do that.
@@ -42,6 +42,8 @@ If you want to use another [Git Provider supported by Qovery](https://hub.qovery
- Terraform’s CLI tool. You can follow [this guide to install it based on your operating system](https://www.terraform.io/downloads).
- Qovery’s CLI tool. You can follow [this guide to install it based on your operating system](https://hub.qovery.com/docs/using-qovery/interface/cli/#install).
+---
+
## Create GitHub Repository
Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it.
@@ -81,6 +83,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to Qovery
In this section, you’ll learn how to deploy your Medusa server to Qovery with the help of Terraform.
@@ -473,6 +477,8 @@ If you run into any errors while running this command, you can just re-run it af
:::
+---
+
## Test your Server
Once the command finishes and the deployment is successful, you can access your server in the [Qovery Console](https://console.qovery.com/). Go to the project, environment, then the app that you created using Terraform and Qovery. In the app, click the Open button at the top right to open your website in a new tab.
@@ -481,6 +487,8 @@ Once the command finishes and the deployment is successful, you can access your
You can access any of the endpoints on your server using the server URL. For example, you can get the list of products using the endpoint `/store/products`.
+---
+
## Run Commands on Your Server
To run commands on your server, run the following command:
@@ -498,6 +506,8 @@ npm install @medusajs/medusa-cli -g
medusa user --email --password
```
+---
+
## Add Environment Variables
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
@@ -506,7 +516,9 @@ To add environment variables, in your [Qovery Console](https://console.qovery.co
-## What’s Next
+---
-- Learn how to [deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md).
-- Learn how to [deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md).
+## See Also
+
+- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md)
+- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md)
diff --git a/docs/content/deployments/server/deploying-on-railway.md b/docs/content/deployments/server/deploying-on-railway.md
index 7cc16cd2a6..65305be3e4 100644
--- a/docs/content/deployments/server/deploying-on-railway.md
+++ b/docs/content/deployments/server/deploying-on-railway.md
@@ -12,11 +12,13 @@ In this document, you’ll learn how to deploy your Medusa server to Railway.
Railway provides a free plan that allows you to deploy your Medusa server along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes.
+---
+
## Prerequisites
### Medusa Server
-It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.md).
+It is assumed that you already have a Medusa server installed locally. If you don’t, please follow the [quickstart guide](../../quickstart/quick-start.mdx).
Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](./../../usage/configurations.md) to learn how to do that.
@@ -29,12 +31,16 @@ Furthermore, your Medusa server should be configured to work with PostgreSQL and
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](./../../tutorial/0-set-up-your-development-environment.mdx#git).
+---
+
## Changes to Medusa Server Codebase
By default, Railway looks for a Dockerfile in the root of the codebase. If there is one, it will try to deploy your server using it.
As this guide doesn't use Docker, make sure to delete `Dockerfile` from the root of your Medusa server.
+---
+
## Create GitHub Repository
Before you can deploy your Medusa server you need to create a GitHub repository and push the code base to it.
@@ -74,6 +80,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to Railway
In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the server from the GitHub repository.
@@ -172,6 +180,8 @@ The last step is to add a domain name to your Medusa server. To do that:
2. Click on the Settings tab and scroll down to the Domains section.
3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain.
+---
+
## Test your Server
Every change you make to the settings redeploys the server. You can check the Deployments of the server by clicking on the GitHub repository’s card and choosing the Deployments tab.
@@ -184,6 +194,8 @@ If you generated a random domain, you can find it by clicking on the GitHub repo
:::
+---
+
## Troubleshooting
If you run into any issues or a problem with your deployed server, you can check the logs in your Railway container instance by:
@@ -192,13 +204,17 @@ If you run into any issues or a problem with your deployed server, you can check
2. Click on the Deployments tab.
3. Click on the View Logs button.
+---
+
## Run Commands on Server
To run commands on your server, you can use [Railway’s CLI tool to run a local shell and execute commands](https://docs.railway.app/develop/cli#local-shell).
For example, you can run commands on the server to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.md).
-## What’s Next
+---
-- Learn [how to deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md).
-- Learn [how to deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md).
+## See Also
+
+- [Deploy the Medusa Admin to Netlify](../admin/deploying-on-netlify.md)
+- [Deploy the Gatsby Storefront to Netlify](../storefront/deploying-gatsby-on-netlify.md)
diff --git a/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md b/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md
index d8863caf04..4c2905868e 100644
--- a/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md
+++ b/docs/content/deployments/storefront/deploying-gatsby-on-netlify.md
@@ -12,11 +12,13 @@ Alternatively, you can use this button to deploy the Gatsby Storefront to Netlif
+---
+
## Prerequisites
### Medusa Components
-Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally. If not, please go through the [quickstart guide](../../starters/gatsby-medusa-starter.md) first.
+Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally. If not, please go through the [quickstart guide](../../starters/gatsby-medusa-starter.mdx) first.
Additionally, this documentation does not cover how to deploy the Medusa server. If you want to deploy the Medusa server, [check out one of the deployment documentation related to the Medusa server](../server/index.mdx).
@@ -35,6 +37,8 @@ If you want to use another Git Provider, it’s possible to follow along with th
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
+---
+
## Create GitHub Repository
Before you can deploy your Gatsby storefront you need to create a GitHub repository and push the code base to it.
@@ -74,6 +78,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to Netlify
This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool.
@@ -291,6 +297,8 @@ The Gatsby storefront will then open in your browser.
Before you can use the Gatsby storefront, you must add the URL as an environment variable on your deployed Medusa server.
+---
+
## Configure CORS Variable on the Medusa Server
To send requests to the Medusa server from the Gatsby storefront, you must set the `STORE_CORS` environment variable on your server to the Gatsby storefront’s URL.
@@ -311,7 +319,9 @@ Where `` is the URL of your Gatsby storefront that you just depl
Then, restart your Medusa server. Once the server is running again, you can use your Gatsby storefront.
-## What’s Next
+---
-- Learn how to [deploy the Medusa Admin](../admin/index.mdx).
-- Learn more about [Medusa’s configurations](../../usage/configurations.md).
+## See Also
+
+- [Deploy the Medusa Admin](../admin/index.mdx)
+- [Configure your Medusa server](../../usage/configurations.md)
diff --git a/docs/content/guides/carts-in-medusa.mdx b/docs/content/guides/carts-in-medusa.mdx
index 3edf44438e..979a74e2c9 100644
--- a/docs/content/guides/carts-in-medusa.mdx
+++ b/docs/content/guides/carts-in-medusa.mdx
@@ -21,13 +21,15 @@ This document does not cover implementing the checkout flow. You can refer to [t
- **Line Item**: When products are added to the cart in Medusa, they are referred to as line items. Line items have, by default, the same properties and attributes as a product. However, you can customize line items specifically for a cart if necessary.
+---
+
## Prerequisites
### Medusa Components
-It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../quickstart/quick-start.md) to get started.
+It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../quickstart/quick-start.mdx) to get started.
-It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
+It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install either the [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](../starters/gatsby-medusa-starter.mdx) storefronts.
### JS Client
@@ -35,6 +37,8 @@ This guide includes code snippets to send requests to your Medusa server using M
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../js-client/overview.md) and have [created an instance of the client](../js-client/overview.md#configuration).
+---
+
## Create a Cart
You can create a cart with the following code snippet:
@@ -45,10 +49,10 @@ You can create a cart with the following code snippet:
```jsx
medusa.carts.create()
.then(({ cart }) => {
- localStorage.setItem('cart_id', cart.id);
- //assuming you have a state variable to store the cart
- setCart(cart);
-});
+ localStorage.setItem("cart_id", cart.id)
+ // assuming you have a state variable to store the cart
+ setCart(cart)
+})
```
@@ -56,15 +60,15 @@ medusa.carts.create()
```jsx
fetch(`/store/carts`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
})
.then((response) => response.json())
.then(({ cart }) => {
- localStorage.setItem('cart_id', cart.id);
- //assuming you have a state variable to store the cart
+ localStorage.setItem("cart_id", cart.id)
+ // assuming you have a state variable to store the cart
setCart(cart)
-});
+})
```
@@ -81,13 +85,13 @@ Otherwise, you can assign it a specific region during creation:
```jsx
medusa.carts.create({
- region_id
+ region_id,
})
.then(({ cart }) => {
- localStorage.setItem('cart_id', cart.id);
- //assuming you have a state variable to store the cart
- setCart(cart);
-});
+ localStorage.setItem("cart_id", cart.id)
+ // assuming you have a state variable to store the cart
+ setCart(cart)
+})
```
@@ -95,21 +99,21 @@ medusa.carts.create({
```jsx
fetch(`/store/carts`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- region_id
- })
+ region_id,
+ }),
})
.then((response) => response.json())
.then(({ cart }) => {
- localStorage.setItem('cart_id', cart.id);
- //assuming you have a state variable to store the cart
+ localStorage.setItem("cart_id", cart.id)
+ // assuming you have a state variable to store the cart
setCart(cart)
-});
+})
```
@@ -123,6 +127,8 @@ The region a cart is associated with determines the currency the cart uses, the
:::
+---
+
## Retrieve a Cart
Notice that in the previous code snippets, you set the cart’s ID in the local storage. This is helpful to persist the customer’s cart even when they leave the website and come back later.
@@ -133,11 +139,11 @@ You can retrieve the cart at any given point using its ID with the following cod
```jsx
-const id = localStorage.getItem('cart_id');
+const id = localStorage.getItem("cart_id")
if (id) {
medusa.carts.retrieve(id)
- .then(({ cart }) => setCart(cart));
+ .then(({ cart }) => setCart(cart))
}
```
@@ -145,14 +151,14 @@ if (id) {
```jsx
-const id = localStorage.getItem('cart_id');
+const id = localStorage.getItem("cart_id")
if (id) {
fetch(`/store/carts/${id}`, {
- credentials: 'include',
+ credentials: "include",
})
.then((response) => response.json())
- .then(({ cart }) => setCart(cart));
+ .then(({ cart }) => setCart(cart))
}
```
@@ -169,6 +175,8 @@ Make sure to remove the ID from the local storage after the customer places an o
:::
+---
+
## Update a Cart
A cart has different data associated with it including the region, email, address, customer, and more.
@@ -180,9 +188,9 @@ You can use the following snippet to update any of the cart’s data:
```jsx
medusa.carts.update(cartId, {
- region_id
+ region_id,
})
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -190,17 +198,17 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- region_id
- })
+ region_id,
+ }),
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -223,9 +231,9 @@ You can do that using the same update operation:
```jsx
medusa.carts.update(cartId, {
- customer_id
+ customer_id,
})
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -233,17 +241,17 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- customer_id
- })
+ customer_id,
+ }),
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -262,9 +270,9 @@ You can do that using the same update operation:
```jsx
medusa.carts.update(cartId, {
- email: 'user@example.com'
+ email: "user@example.com",
})
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -272,22 +280,24 @@ medusa.carts.update(cartId, {
```jsx
fetch(`/store/carts/${cartId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- email: 'user@example.com'
- })
+ email: "user@example.com",
+ }),
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
+---
+
## Add Line Item to the Cart
To create a line item of a product and add it to a cart, you can use the following code snippet:
@@ -298,9 +308,9 @@ To create a line item of a product and add it to a cart, you can use the followi
```jsx
medusa.carts.lineItems.create(cartId, {
variant_id,
- quantity: 1
+ quantity: 1,
})
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -308,18 +318,18 @@ medusa.carts.lineItems.create(cartId, {
```jsx
fetch(`/store/carts/${cartId}/line-items`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
variant_id,
- quantity: 1
- })
+ quantity: 1,
+ }),
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -337,6 +347,8 @@ If you’re using Sales Channels, make sure that the cart and the product belong
:::
+---
+
## Update Line Item in the Cart
To update a line item's quantity in the cart, you can use the following code snippet:
@@ -346,7 +358,7 @@ To update a line item's quantity in the cart, you can use the following code sni
```jsx
medusa.carts.lineItems.update(cartId, lineItemId, {
- quantity: 3
+ quantity: 3,
})
.then(({ cart }) => setCart(cart))
```
@@ -356,17 +368,17 @@ medusa.carts.lineItems.update(cartId, lineItemId, {
```jsx
fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
- method: 'POST',
- credentials: 'include',
+ method: "POST",
+ credentials: "include",
headers: {
- 'Content-Type': 'application/json'
+ "Content-Type": "application/json",
},
body: JSON.stringify({
- quantity: 3
- })
+ quantity: 3,
+ }),
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -376,6 +388,8 @@ This request accepts the ID of the cart and the ID of the line item as path para
It returns the updated cart.
+---
+
## Delete a Line Item from the Cart
To delete a line item from the cart, you can use the following code snippet:
@@ -393,11 +407,11 @@ medusa.carts.lineItems.delete(cartId, lineItemId)
```jsx
fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
- method: 'DELETE',
- credentials: 'include',
+ method: "DELETE",
+ credentials: "include",
})
.then((response) => response.json())
-.then(({ cart }) => setCart(cart));
+.then(({ cart }) => setCart(cart))
```
@@ -407,7 +421,9 @@ This request accepts the ID of the cart and the ID of the line item as path para
It returns the updated cart.
-## What’s Next
+---
-- Learn [how to implement the checkout flow in your storefront](../advanced/storefront/how-to-implement-checkout-flow.mdx).
-- Learn more about the [JS Client and how to use it](../js-client/overview.md).
+## See Also
+
+- [Implement the checkout flow in your storefront](../advanced/storefront/how-to-implement-checkout-flow.mdx)
+- [Medusa JS Client Overview](../js-client/overview.md)
diff --git a/docs/content/js-client/overview.md b/docs/content/js-client/overview.md
index c2c96d617c..4b5e254cdc 100644
--- a/docs/content/js-client/overview.md
+++ b/docs/content/js-client/overview.md
@@ -12,6 +12,8 @@ To install the Medusa JS Client run the following command:
npm install @medusajs/medusa-js
```
+---
+
## Usage
Import Medusa as a default import and initiate it:
@@ -22,6 +24,8 @@ import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa()
```
+---
+
## How to Use this Reference
You'll find in the sidebar of this reference names of different resources. These resources are properties in the medusa instance you initialize and you can access them directly using the instance. Then, you'll be able to access the methods or nested resources within those resources.
@@ -33,9 +37,9 @@ import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa()
-//use method
+// use method
medusa.customers.create({
- //data
+ // data
})
```
@@ -43,10 +47,12 @@ The `customers` resource also has another resource `addresses` nested inside it
```js
medusa.customers.addresses.addAddress({
- //data
+ // data
})
```
+---
+
## Authentication
Authentication can be achieved in two ways using the `medusa-js` client: either by utilizing API keys or by using cookie based authentication. Each method has its own unique use case.
@@ -59,6 +65,8 @@ API keys can only be used for admin functionality in Medusa since only users of
Authentication using cookies is done automatically by Axios when authenticating using the [auth](/references/js-client/classes/AuthResource) endpoints. After authentication, all subsequent calls will be authenticated.
+---
+
## Configuration
### Initialize with config object
diff --git a/docs/content/nav.yml b/docs/content/nav.yml
deleted file mode 100644
index 9a16383e66..0000000000
--- a/docs/content/nav.yml
+++ /dev/null
@@ -1,41 +0,0 @@
-- title: Tutorials
- id: tutorials
- items:
- - id: overview
- title: Overview
- - id: getting-started
- title: Getting started
- - id: adding-plugins
- title: Adding plugins
- - id: creating-a-custom-endpoint
- title: Creating a custom endpoint
- - id: linking-medusa-cloud
- title: Linking Medusa Cloud
-- title: Guides
- id: guides
- items:
- - id: overview
- title: Overview
- - id: local-development
- title: Local development
- items:
- - id: overview
- title: Overview
- - id: create-project-from-starter
- title: Create project from starter
- items:
- - id: medusa-starter
- title: Medusa starter
- - id: gatsby-starter-medusa
- title: Gatsby starter
- - id: environment-variables
- title: Environment variables
-- title: Reference
- id: reference
- items:
- - id: admin
- title: admin
- - id: store
- title: store
-- title: Contributing
- id: contributing
diff --git a/docs/content/quickstart/quick-start-docker.md b/docs/content/quickstart/quick-start-docker.mdx
similarity index 82%
rename from docs/content/quickstart/quick-start-docker.md
rename to docs/content/quickstart/quick-start-docker.mdx
index 37c147a72f..c245445e51 100644
--- a/docs/content/quickstart/quick-start-docker.md
+++ b/docs/content/quickstart/quick-start-docker.mdx
@@ -1,3 +1,5 @@
+import Feedback from '@site/src/components/Feedback';
+
# Quickstart using Docker
In this document, you will learn how to make a container of Medusa's app on Docker. Docker is an open source platform for building, deploying, and managing containerized applications.
@@ -17,6 +19,8 @@ You can install Node from the [official website](https://nodejs.org/en/).
It is assumed that you have Docker installed on your system. You can install it from [Docker's website](https://docs.docker.com/get-docker/).
+---
+
## Create Medusa Server with Docker
### 1. Clone Medusa's starter project from GitHub
@@ -61,6 +65,14 @@ Running the above command does the following:
1. Build images for your Medusa project, a PostgreSQL database, and a Redis server
2. Run migrations for your newly created database
+` with the port number you want the storefront to run on. For example, `3000`.
+Make sure to replace `` with the port number you want the storefront to run on. For example, `3000`.
-Then, on your server, update the environment variable `STORE_CORS` to the URL with the new port:
+Then, on your server, update the environment variable `STORE_CORS` to the URL with the new port:
```bash
STORE_CORS=http://localhost:
@@ -206,6 +227,8 @@ STORE_CORS=http://localhost:
You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
+---
+
## Storefront Features
- View all products and manage your cart.
@@ -220,7 +243,10 @@ You can learn more about development with Next.js through [their documentation](
-## What’s Next
+---
-- Check the [Storefront API reference](https://docs.medusajs.com/api/store) for a full list of REST APIs to use on your storefront.
-- Learn [how to install Medusa Admin](../admin/quickstart.md).
+## See Also
+
+- [Storefront API reference](https://docs.medusajs.com/api/store)
+- [Install Medusa Admin](../admin/quickstart.mdx).
+- [Install Stripe as a payment provider](../add-plugins/stripe.md#add-to-nextjs-storefront)
diff --git a/docs/content/troubleshooting/cli-installation-errors.mdx b/docs/content/troubleshooting/cli-installation-errors.mdx
index 63a4d488e4..2c1c758d55 100644
--- a/docs/content/troubleshooting/cli-installation-errors.mdx
+++ b/docs/content/troubleshooting/cli-installation-errors.mdx
@@ -11,6 +11,24 @@ If you install the Medusa CLI tool with NPM and get a permission error, NPM prop
You can check out more information in [NPM’s documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
+---
+
+
+
+## Powershell Error: command not found: medusa
+
+
+
+If you're using Powershell and you installed the CLI tool, but when you try to use it you get the error:
+
+```bash noReport
+command not found: medusa
+```
+
+Try closing your Powershell window and opening a new one.
+
+---
+
## Yarn Error: command not found: medusa
@@ -44,4 +62,4 @@ setx path "%path%;c:\users\YOURUSERNAME\appdata\local\yarn\bin"
-You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).
+You can learn more in [Yarn’s documentation](https://classic.yarnpkg.com/en/docs/cli/global#adding-the-install-location-to-your-path).
\ No newline at end of file
diff --git a/docs/content/troubleshooting/common-installation-errors.mdx b/docs/content/troubleshooting/common-installation-errors.mdx
new file mode 100644
index 0000000000..fd57372694
--- /dev/null
+++ b/docs/content/troubleshooting/common-installation-errors.mdx
@@ -0,0 +1,27 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Resolve "Cannot find module X" Errors
+
+This error can occur while installing one of the storefronts or the Medusa admin. There is no specific cause to this error.
+
+One way to resolve it is by removing the `node_modules` directory in the project and re-installing the dependencies:
+
+
+
+
+```bash
+rm -rf node_modules
+yarn install
+```
+
+
+
+
+```bash
+rd /s /q node_modules
+yarn install
+```
+
+
+
\ No newline at end of file
diff --git a/docs/content/troubleshooting/cors-issues.md b/docs/content/troubleshooting/cors-issues.md
index 5119d8b18d..73372a435a 100644
--- a/docs/content/troubleshooting/cors-issues.md
+++ b/docs/content/troubleshooting/cors-issues.md
@@ -10,9 +10,10 @@ In your `medusa-config.js` , you should ensure that you've configured your CORS
The default configuration uses the following CORS settings:
-```jsx title=medusa-config.js
+```js title=medusa-config.js
// CORS when consuming Medusa from admin
-const ADMIN_CORS = process.env.ADMIN_CORS || "http://localhost:7000,http://localhost:7001"
+const ADMIN_CORS = process.env.ADMIN_CORS ||
+ "http://localhost:7000,http://localhost:7001"
// CORS to avoid issues when consuming Medusa from a client
const STORE_CORS = process.env.STORE_CORS || "http://localhost:8000"
@@ -20,6 +21,8 @@ const STORE_CORS = process.env.STORE_CORS || "http://localhost:8000"
If you wish to run your storefront or Medusa admin on other ports, you should update the above settings accordingly.
-## Additional Resources
+---
-To learn more about CORS configurations, check out the [Configure your Server](../usage/configurations.md) documentation.
+## See Also
+
+- [Configure your Medusa server](../usage/configurations.md)
diff --git a/docs/content/troubleshooting/database-error.md b/docs/content/troubleshooting/database-error.md
new file mode 100644
index 0000000000..e3da1ef9e8
--- /dev/null
+++ b/docs/content/troubleshooting/database-error.md
@@ -0,0 +1,20 @@
+# Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
+
+You can get the following error while running `medusa new` or while running integration tests during [local development](../usage/local-development.md):
+
+```bash
+Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string
+```
+
+If the error occurs while running `medusa new` and you've selected to enter your database credentials, either:
+
+1. Make sure your database credentials are correct;
+2. Or choose the Skip option to skip entering your database credentials.
+
+If the error occurs while running integration tests, make sure the following variable is set in your system's environment variable:
+
+```bash
+DB_HOST=
+DB_USERNAME=
+DB_PASSWORD=
+```
diff --git a/docs/content/troubleshooting/documentation-error.md b/docs/content/troubleshooting/documentation-error.md
index 94fbcd525f..cc31b8e5e3 100644
--- a/docs/content/troubleshooting/documentation-error.md
+++ b/docs/content/troubleshooting/documentation-error.md
@@ -8,6 +8,8 @@ This is because the content resides in `docs/content`. When that content is bein
For that reason, when the `start` and `build` scripts in `www/docs` are used, the `clean-node-modules` script is called. This script deleted the `node_modules` directory in the root of the Medusa repository.
+---
+
## Out of Memory Error
If you receive the following error when you run the `build` command in `www/docs`:
diff --git a/docs/content/troubleshooting/missing-payment-providers.md b/docs/content/troubleshooting/missing-payment-providers.md
index 9e7feaf6db..95d33da338 100644
--- a/docs/content/troubleshooting/missing-payment-providers.md
+++ b/docs/content/troubleshooting/missing-payment-providers.md
@@ -2,9 +2,9 @@
You add payment providers to your Medusa instance by adding them as plugins in `medusa-config.js`:
-```jsx title=medusa-config.js
+```js title=medusa-config.js
const plugins = [
- ...
+ // ...
// You can create a Stripe account via: https://stripe.com
{
resolve: `medusa-payment-stripe`,
@@ -13,8 +13,7 @@ const plugins = [
webhook_secret: STRIPE_WEBHOOK_SECRET,
},
},
- ...
-];
+]
```
And installing them with your favourite package manager:
@@ -27,7 +26,9 @@ However, to also show them as part of your checkout flow you need to add them to
In the Medusa Admin go to Settings > Regions and for each region scroll down to the Payment Provider input and choose the payment provider you want to use in that region.
-## Additional Resources
+---
-- Learn how to install [Stripe](../add-plugins/stripe.md) as a payment provider.
-- Learn more about the [Payment architecture](../advanced/backend/payment/overview.md).
+## See Also
+
+- [Install Stripe](../add-plugins/stripe.md)
+- [Payment Architecture Overview](../advanced/backend/payment/overview.md)
diff --git a/docs/content/troubleshooting/redis-events.md b/docs/content/troubleshooting/redis-events.md
index c8342b92bf..8ddf29c1c7 100644
--- a/docs/content/troubleshooting/redis-events.md
+++ b/docs/content/troubleshooting/redis-events.md
@@ -11,7 +11,7 @@ After installing it, make sure to configure your Medusa server to use Redis:
```jsx title=medusa-config.js
module.exports = {
projectConfig: {
- //...
+ // ...
redis_url: REDIS_URL,
},
}
@@ -23,7 +23,9 @@ By default, Medusa connects to Redis over the URL `redis://localhost:6379`. If y
REDIS_URL=
```
-## Additional Resources
+---
-- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx).
-- Learn how to [configure your server](../usage/configurations.md).
+## See Also
+
+- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx)
+- [Configure your server](../usage/configurations.md)
diff --git a/docs/content/troubleshooting/signing-in-to-admin.md b/docs/content/troubleshooting/signing-in-to-admin.md
index 0089558b3c..aa8a389f24 100644
--- a/docs/content/troubleshooting/signing-in-to-admin.md
+++ b/docs/content/troubleshooting/signing-in-to-admin.md
@@ -13,6 +13,8 @@ Alternatively, you can create your own users using the Medusa CLI tool:
medusa user -e some@email.com -p somepassword
```
-## Additional Resources
+---
-Learn more about Medusa's CLI tool in the [CLI reference](../cli/reference.md).
+## See Also
+
+- [Medusa CLI tool reference](../cli/reference.md)
diff --git a/docs/content/troubleshooting/transaction-error-in-checkout.md b/docs/content/troubleshooting/transaction-error-in-checkout.md
index 6830f67d24..d6537381ab 100644
--- a/docs/content/troubleshooting/transaction-error-in-checkout.md
+++ b/docs/content/troubleshooting/transaction-error-in-checkout.md
@@ -19,7 +19,7 @@ Then in your `medusa-config.js`, you should change the project configuration to
```jsx title=medusa-config.js
module.exports = {
projectConfig: {
- //...
+ // ...
database_url: DATABASE_URL,
database_type: "postgres",
},
@@ -31,6 +31,8 @@ Where `DATABASE_URL` is the connection string to your PostgreSQL database. You c
Make sure to also remove the following lines that are used to configure an SQLite database:
+
+
```jsx title=medusa-config.js
database_type: "sqlite",
database_database: "./medusa-db.sql",
@@ -52,8 +54,10 @@ npm run seed
:::
-## Additional Resources
+---
-- Learn how to [set up your development environment](../tutorial/0-set-up-your-development-environment.mdx).
-- Learn how to [configure your server](../usage/configurations.md).
-- Learn more about [the Medusa CLI tool](../cli/reference.md).
+## See Also
+
+- [Set up your development environment](../tutorial/0-set-up-your-development-environment.mdx)
+- [Configure your server](../usage/configurations.md)
+- [Medusa CLI tool reference](../cli/reference.md)
diff --git a/docs/content/tutorial/0-set-up-your-development-environment.mdx b/docs/content/tutorial/0-set-up-your-development-environment.mdx
index 82c98e5f3a..0ef044ca8f 100644
--- a/docs/content/tutorial/0-set-up-your-development-environment.mdx
+++ b/docs/content/tutorial/0-set-up-your-development-environment.mdx
@@ -139,6 +139,14 @@ If you run into any errors while installing the CLI tool, check out the [trouble
:::
+---
+
+## Install Medusa Server
+
+If you're not interested in installing the optional tools and want to get started quickly, check out the [quickstart guide](../quickstart/quick-start.mdx).
+
+---
+
## Optional Tools
These tools are not required to have to run a Medusa server, but it's highly recommended that you have them installed.
@@ -268,8 +276,11 @@ To install Redis without Homebrew you can check out [Redis’s guide on installi
-## What’s Next
+---
-- Learn how to [configure your Medusa server](../usage/configurations.md).
-- Learn how to install a storefront with [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](./../starters/gatsby-medusa-starter.md).
-- Learn how to install the [Medusa Admin](../admin/quickstart.md).
+## See Also
+
+- [Install Medusa server](../quickstart/quick-start.mdx)
+- [Configure your Medusa server](../usage/configurations.md).
+- Install a storefront with [Next.js](../starters/nextjs-medusa-starter.mdx) or [Gatsby](./../starters/gatsby-medusa-starter.mdx).
+- [Install the Medusa Admin](../admin/quickstart.mdx).
diff --git a/docs/content/usage.md b/docs/content/usage.md
index 0c61986283..f64b0f22d3 100644
--- a/docs/content/usage.md
+++ b/docs/content/usage.md
@@ -9,6 +9,8 @@ This document gives an overview of Medusa’s optional collected usage informati
At Medusa, we strive to provide the best experience for developers using our platform. For that reason, Medusa collects anonymous and non-sensitive data that provides a global understanding of how users are using Medusa.
+---
+
## Purpose
As an open source solution, we work closely and constantly interact with our community to ensure that we provide the best experience for everyone using Medusa.
@@ -25,6 +27,8 @@ Collecting this data allows us to understand certain details such as:
- How much data do users manage through our Medusa Admin? Is it being used for large number of products, orders, and other types of data?
- What Node version is globally used? Should we focus our efforts on providing support for versions that we don’t currently support?
+---
+
## Server Analytics
This section covers which data in the server are collected and how to opt out of it.
@@ -58,6 +62,8 @@ Or, you can run the following command in the root of your Medusa server project
medusa telemetry --disable
```
+---
+
## Admin Analytics
This section covers which data in the admin are collected and how to opt out of it.
diff --git a/docs/content/usage/configurations.md b/docs/content/usage/configurations.md
index d90f1b94bc..ad5a6f6661 100644
--- a/docs/content/usage/configurations.md
+++ b/docs/content/usage/configurations.md
@@ -4,7 +4,9 @@ In this document, you’ll learn what configurations you can add to your Medusa
## Prerequisites
-This document assumes you already followed along with the [“Set up your development environment” documentation](../tutorial/0-set-up-your-development-environment.mdx) and have [installed a Medusa server](../quickstart/quick-start.md#create-a-medusa-server).
+This document assumes you already followed along with the [“Set up your development environment” documentation](../tutorial/0-set-up-your-development-environment.mdx) and have [installed a Medusa server](../quickstart/quick-start.mdx#create-a-medusa-server).
+
+---
## Medusa Configurations File
@@ -12,6 +14,8 @@ The configurations for your Medusa server are in `medusa-config.js`. This includ
Some of the configurations mentioned in this document are already defined in `medusa-config.js` with default values. It’s important that you know what these configurations are used for and how to set them.
+---
+
## Environment Variables
In your configurations, you’ll often use environment variables. For example, when using API keys or setting your database URL.
@@ -24,6 +28,8 @@ This change in how environment variables are loaded was introduced in version 1.
:::
+---
+
## Database Configuration
Medusa supports two database types: SQLite and PostgreSQL.
@@ -41,11 +47,11 @@ For SQLite you mainly need two configurations:
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
database_type: "sqlite",
database_database: "./medusa-db.sql",
},
-};
+}
```
Where `database_type` is `sqlite` and `database_database` is the location you want the SQLite database to be created in.
@@ -54,7 +60,7 @@ Where `database_type` is `sqlite` and `database_database` is the location you wa
:::note
-Before getting started with configuring PostgreSQL, you should have created a PostgreSQL `database`. You can check how to create a database in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
+Before getting started with configuring PostgreSQL, you should have created a PostgreSQL database. You can check how to create a database in [PostgreSQL's documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
:::
@@ -63,16 +69,19 @@ For PostgreSQL you mainly need two configurations:
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
database_type: "postgres",
database_url: DATABASE_URL,
+ database_schema: process.env.DATABASE_SCHEMA, // optional
},
-};
+}
```
Where `database_type` is `postgres` and `DATABASE_URL` is the URL connection string to your PostgreSQL database. You can check out how to format it in [PostgreSQL’s documentation](https://www.postgresql.org/docs/current/libpq-connect.html).
-It is recommended to set the Database URL as an environment variable:
+You can optionally set the `database_schema` option. By default, its value is `public`.
+
+It's recommended to set the Database URL as an environment variable:
```bash
DATABASE_URL=
@@ -100,13 +109,15 @@ These configurations are not required and can be omitted.
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
database_logging: true,
- database_extra: {}
+ database_extra: {},
},
-};
+}
```
+---
+
## Redis
Medusa uses Redis to handle the event queue, among other usages. You need to set Redis URL in the configurations:
@@ -114,10 +125,10 @@ Medusa uses Redis to handle the event queue, among other usages. You need to set
```jsx
module.exports = {
projectConfig: {
- //...other configurations
- redis_url: REDIS_URL
+ // ...other configurations
+ redis_url: REDIS_URL,
},
-};
+}
```
Where `REDIS_URL` is the URL used to connect to Redis. The format of the connection string is `redis[s]://[[username][:password]@][host][:port][/db-number]`.
@@ -144,6 +155,8 @@ You can learn more about Subscribers and events in the [Subscriber documentation
:::
+---
+
## JWT Secret
Medusa uses JSON Web Token (JWT) to handle user authentication. To set the JWT secret:
@@ -151,10 +164,10 @@ Medusa uses JSON Web Token (JWT) to handle user authentication. To set the JWT s
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
jwt_secret: "very secure string",
},
-};
+}
```
Where `jwt_secret` is the secret used to create the tokens. The more secure it is the better.
@@ -173,6 +186,8 @@ In a development environment, if this option is not set the default secret is
:::
+---
+
## Cookie Secret
This configuration is used to sign the session ID cookie. To set the cookie secret:
@@ -180,10 +195,10 @@ This configuration is used to sign the session ID cookie. To set the cookie secr
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
cookie_secret: "very secure string",
},
-};
+}
```
Where `cookie_secret` is the secret used to create the tokens. The more secure it is the better.
@@ -202,6 +217,8 @@ In a development environment, if this option is not set the default secret is
:::
+---
+
## CORS Configurations
Medusa uses Cross-Origin Resource Sharing (CORS) to only allow specific origins to access the server.
@@ -222,10 +239,10 @@ To make sure your Admin dashboard can access the Medusa server’s admin endpoin
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
admin_cors: ADMIN_CORS,
},
-};
+}
```
Where `ADMIN_CORS` is the URL of your admin dashboard. By default, it’s `http://localhost:7000,http://localhost:7001`.
@@ -251,10 +268,10 @@ To make sure your Storefront dashboard can access the Medusa server, set this co
```jsx
module.exports = {
projectConfig: {
- //...other configurations
+ // ...other configurations
store_cors: STORE_CORS,
},
-};
+}
```
Where `STORE_CORS` is the URL of your storefront. By default, it’s `http://localhost:8000`.
@@ -273,6 +290,8 @@ Make sure that the URL is without a backslash at the end. For example, you shoul
:::
+---
+
## Plugins
On your Medusa server, you can use Plugins to add custom features or integrate third-party services. For example, installing a plugin to use Stripe as a payment provider.
@@ -288,10 +307,10 @@ Aside from installing the plugin with NPM, you need to pass the plugin you insta
```jsx
module.exports = {
projectConfig: {
- //previous configurations mentioned...
+ // previous configurations mentioned...
},
plugins,
-};
+}
```
### Add a Plugin Without Configuration
@@ -300,9 +319,9 @@ To add a plugin that doesn’t need any configurations, you can simply add its n
```jsx
const plugins = [
- //other plugins...
+ // other plugins...
`medusa-my-plugin`,
-];
+]
```
### Add a Plugin With Configuration
@@ -311,14 +330,14 @@ To add a plugin with configurations, you need to add an object to the `plugins`
```jsx
const plugins = [
- //other plugins...
+ // other plugins...
{
resolve: `medusa-my-plugin`,
options: {
- apiKey: `test`
- }
- }
-];
+ apiKey: `test`,
+ },
+ },
+]
```
:::tip
@@ -327,8 +346,10 @@ It is recommended to use environment variables to store values of options instea
:::
-## What’s Next
+---
-- Check out the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts.
-- Install the [Medusa admin](../admin/quickstart.md).
-- Learn about [deploying the Medusa server](../deployments/server/index.mdx).
+## See Also
+
+- Check out the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts
+- [Install the Medusa admin](../admin/quickstart.mdx)
+- [Deploy the Medusa server](../deployments/server/index.mdx)
diff --git a/docs/content/usage/create-medusa-app.mdx b/docs/content/usage/create-medusa-app.mdx
index 03699e637d..adff4da8cd 100644
--- a/docs/content/usage/create-medusa-app.mdx
+++ b/docs/content/usage/create-medusa-app.mdx
@@ -15,6 +15,8 @@ However, if you’re interested in using Medusa’s starters for the three compo
When you run the `create-medusa-app` command, you’ll install a Medusa server, a Medusa admin, and optionally a storefront at the same time.
+---
+
## How to Create a Medusa Project
In your terminal, run the following command:
@@ -77,7 +79,7 @@ If you choose an option other than `None`, a storefront will be installed under
:::tip
-Learn more about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts.
+Learn more about the [Next.js](../starters/nextjs-medusa-starter.mdx) and [Gatsby](../starters/gatsby-medusa-starter.mdx) starter storefronts.
:::
@@ -103,6 +105,8 @@ yarn start
The commands will differ based on your choices in previous prompts.
+---
+
## Project Directory Structure
Inside the root project directory which was specified at the beginning of the installation process you’ll find the following directory structure:
@@ -114,8 +118,10 @@ Inside the root project directory which was specified at the beginning of the in
/admin // Medusa admin panel
```
+---
+
## What’s Next
-- Learn how to [deploy the Medusa server](../deployments/server/index.mdx).
-- Learn how to [deploy the Medusa admin](../deployments/admin/index.mdx).
-- Learn how to [deploy the storefront](../deployments/storefront/index.mdx).
\ No newline at end of file
+- [Deploy the Medusa server](../deployments/server/index.mdx)
+- [Deploy the Medusa admin](../deployments/admin/index.mdx)
+- [Deploy the storefront](../deployments/storefront/index.mdx)
diff --git a/docs/content/usage/local-development.md b/docs/content/usage/local-development.md
index 9b52873033..7ef4fe5be5 100644
--- a/docs/content/usage/local-development.md
+++ b/docs/content/usage/local-development.md
@@ -14,6 +14,8 @@ Whether you want to implement something differently, introduce a new future as p
All the packages are part of a [Yarn workspace](https://classic.yarnpkg.com/lang/en/docs/workspaces/). So, when you run a command in the root of the project, such as `yarn build`, it goes through all registered packages in the workspace under the `packages` directory and runs the `build` command in each of those packages.
+---
+
## Prerequisites
### Yarn
@@ -51,10 +53,22 @@ In the directory of your forked GitHub repository, run the following command to
medusa-dev --set-path-to-repo `pwd`
```
+---
+
## Run Tests in the Repository
In this section, you’ll learn how to run tests in the Medusa repository. This is helpful after you customize any of Medusa’s packages and want to make sure everything is still working as expected.
+### Set System Environment Variables
+
+Before you can run the tests, make sure you set the following system environment variables:
+
+```bash
+DB_HOST=
+DB_USERNAME=
+DB_PASSWORD=
+```
+
### Run Unit Tests
To run unit tests in all packages in the Medusa repository, run the following command in the root directory of the repository:
@@ -94,6 +108,8 @@ To run the plugin integration tests, run the following command in the root direc
yarn test:integration:plugins
```
+---
+
## Test in a Local Server
Using Medusa’s dev CLI tool, you can test any changes you make to Medusa’s packages in a local server installation. This eliminates the need to publish these packages on NPM publicly to be able to use them.
@@ -122,7 +138,27 @@ cd medusa-server
medusa-dev
```
-By default, Medusa’s dev CLI runs in watch mode. So, it copies the files when you first run it, then, whenever you make changes in the packages in the Medusa repository, it copies the changed files again.
+By default, Medusa’s dev CLI runs in watch mode. So, it copies the files when you first run it. Then, whenever you make changes in the `dist` directory of the packages in the Medusa repository, it copies the changed files again.
+
+### Watch and Compile Changes
+
+While the above command is running, it's recommended to run the `watch` command inside the directory of every package you're making changes to.
+
+The combination of these two commands running at the same time will compile the package into the `dist` directory of the package, then copy the compiled changes into your local server.
+
+For example, if you're making changes in the `medusa` package, run the following command inside the directory of the `medusa` package:
+
+```bash title=packages/medusa
+yarn watch
+```
+
+Make sure the `medusa-dev` command is also running to copy the changes automatically.
+
+Alternatively, you can manually run the `build` command every time you want to compile the changes:
+
+```bash title=packages/medusa
+yarn build
+```
### CLI Options
@@ -146,7 +182,9 @@ medusa-dev -q
medusa-dev --packages @medusajs/medusa-cli medusa-file-minio
```
-## What’s Next
+---
-- Check out our [contribution guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md).
-- Learn how to [create a plugin](../advanced/backend/plugins/create.md).
+## See Also
+
+- [Create a Plugin](../advanced/backend/plugins/create.md)
+- [Contribution Guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md)
diff --git a/package.json b/package.json
index c19084b426..fcdf8d041f 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,7 @@
"@babel/plugin-transform-instanceof": "^7.10.4",
"@babel/plugin-transform-runtime": "^7.11.5",
"@babel/preset-env": "^7.11.5",
+ "@babel/preset-react": "^7.18.6",
"@babel/register": "^7.11.5",
"@babel/runtime": "^7.11.2",
"@redocly/cli": "latest",
@@ -29,7 +30,9 @@
"eslint": "^8.23.0",
"eslint-config-google": "^0.14.0",
"eslint-config-prettier": "^8.5.0",
+ "eslint-plugin-markdown": "^3.0.0",
"eslint-plugin-prettier": "^4.2.1",
+ "eslint-plugin-react": "^7.31.11",
"express": "^4.17.1",
"get-port": "^5.1.1",
"husky": "^7.0.2",
@@ -60,6 +63,7 @@
"hooks:uninstall": "husky uninstall",
"build": "turbo run build --no-daemon",
"lint": "eslint --ignore-path .eslintignore --ext .js,.ts,.tsx .",
+ "lint:docs": "eslint -c docs/.eslintrc.js --ignore-path docs/.eslintignore docs/content",
"prettier": "prettier",
"jest": "jest",
"test": "turbo run test --no-daemon --filter=!integration-tests-api --filter=!integration-tests-plugins",
diff --git a/packages/medusa/CHANGELOG.md b/packages/medusa/CHANGELOG.md
index e50a9c13a6..10db6e75be 100644
--- a/packages/medusa/CHANGELOG.md
+++ b/packages/medusa/CHANGELOG.md
@@ -1,5 +1,11 @@
# Change Log
+## 1.7.2
+
+### Patch Changes
+
+- [#2889](https://github.com/medusajs/medusa/pull/2889) [`d843bc102`](https://github.com/medusajs/medusa/commit/d843bc10235f33db9eecb72d74018966e43c26d6) Thanks [@olivermrbl](https://github.com/olivermrbl)! - Assign jobSchedulerService in EventBusService
+
## 1.7.1
### Patch Changes
diff --git a/packages/medusa/package.json b/packages/medusa/package.json
index 522da00bd4..d7e65281fd 100644
--- a/packages/medusa/package.json
+++ b/packages/medusa/package.json
@@ -1,6 +1,6 @@
{
"name": "@medusajs/medusa",
- "version": "1.7.1",
+ "version": "1.7.2",
"description": "E-commerce for JAMstack",
"main": "dist/index.js",
"bin": "./cli.js",
diff --git a/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts b/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts
index 6d17a87f5b..b500deadac 100644
--- a/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts
+++ b/packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts
@@ -12,7 +12,7 @@ import { FindParams } from "../../../../types/common"
/**
* @oas [post] /discounts/{discount_id}/conditions/{condition_id}/batch
* operationId: "PostDiscountsDiscountConditionsConditionBatch"
- * summary: "Add a batch of resources to a discount condition"
+ * summary: "Add Batch Resources"
* description: "Add a batch of resources to a discount condition."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts b/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts
index 9e3bf68d17..a2064606db 100644
--- a/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts
+++ b/packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts
@@ -11,7 +11,7 @@ import { FindParams } from "../../../../types/common"
/**
* @oas [delete] /discounts/{discount_id}/conditions/{condition_id}/batch
* operationId: "DeleteDiscountsDiscountConditionsConditionBatch"
- * summary: "Delete a batch of resources from a discount condition"
+ * summary: "Delete Batch Resources"
* description: "Delete a batch of resources from a discount condition."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
index 1aff36ecb6..e079bc4642 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
@@ -11,7 +11,7 @@ import {
/**
* @oas [post] /order-edits/{id}/items
* operationId: "PostOrderEditsEditLineItems"
- * summary: "Add an line item to an order (edit)"
+ * summary: "Add a Line Item"
* description: "Create an OrderEdit LineItem."
* parameters:
* - (path) id=* {string} The ID of the Order Edit.
diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts
index faad5d8096..3747ba758e 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts
@@ -9,7 +9,7 @@ import {
/**
* @oas [delete] /order-edits/{id}/items/{item_id}
* operationId: "DeleteOrderEditsOrderEditLineItemsLineItem"
- * summary: "Delete line items from an order edit and create change item"
+ * summary: "Delete a Line Item"
* description: "Delete line items from an order edit and create change item"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
index bc0278e757..0c05d37413 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
@@ -4,7 +4,7 @@ import { OrderEditService } from "../../../../services"
/**
* @oas [delete] /order-edits/{id}/changes/{change_id}
* operationId: "DeleteOrderEditsOrderEditItemChange"
- * summary: "Delete an Order Edit Item Change"
+ * summary: "Delete a Line Item Change"
* description: "Deletes an Order Edit Item Change"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
index f65b60f98f..16f1653b71 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
@@ -5,7 +5,7 @@ import { OrderEditService } from "../../../../services"
* @oas [delete] /order-edits/{id}
* operationId: "DeleteOrderEditsOrderEdit"
* summary: "Delete an Order Edit"
- * description: "Deletes an Order Edit"
+ * description: "Delete an Order Edit"
* x-authenticated: true
* parameters:
* - (path) id=* {string} The ID of the Order Edit to delete.
diff --git a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
index 458230490a..0ac1ec7451 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
@@ -5,7 +5,7 @@ import { FindParams } from "../../../../types/common"
/**
* @oas [get] /order-edits/{id}
* operationId: "GetOrderEditsOrderEdit"
- * summary: "Retrieve an OrderEdit"
+ * summary: "Get an OrderEdit"
* description: "Retrieves a OrderEdit."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
index 1715895a73..d6179150ee 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
@@ -14,7 +14,7 @@ import { PaymentCollectionType } from "../../../../models"
/**
* @oas [post] /order-edits/{id}/request
* operationId: "PostOrderEditsOrderEditRequest"
- * summary: "Request order edit confirmation"
+ * summary: "Request Confirmation"
* description: "Request customer confirmation of an Order Edit"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
index 92c7043ae4..bc9e4093d1 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
@@ -10,7 +10,7 @@ import {
/**
* @oas [post] /order-edits/{id}/items/{item_id}
* operationId: "PostOrderEditsEditLineItemsLineItem"
- * summary: "Create or update the order edit change holding the line item changes"
+ * summary: "Upsert Line Item Change"
* description: "Create or update the order edit change holding the line item changes"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
index 43f440be4b..4c39353ff0 100644
--- a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
+++ b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
@@ -11,7 +11,7 @@ import {
/**
* @oas [post] /order-edits/{id}
* operationId: "PostOrderEditsOrderEdit"
- * summary: "Updates an OrderEdit"
+ * summary: "Update an OrderEdit"
* description: "Updates a OrderEdit."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts
index cc3b6c63b1..b87970532a 100644
--- a/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts
+++ b/packages/medusa/src/api/routes/admin/payment-collections/delete-payment-collection.ts
@@ -3,7 +3,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [delete] /payment-collections/{id}
* operationId: "DeletePaymentCollectionsPaymentCollection"
- * summary: "Delete a Payment Collection"
+ * summary: "Del a PaymentCollection"
* description: "Deletes a Payment Collection"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts
index 6710b2c8f3..e76dc35793 100644
--- a/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts
+++ b/packages/medusa/src/api/routes/admin/payment-collections/get-payment-collection.ts
@@ -4,7 +4,7 @@ import { FindParams } from "../../../../types/common"
/**
* @oas [get] /payment-collections/{id}
* operationId: "GetPaymentCollectionsPaymentCollection"
- * summary: "Retrieve an PaymentCollection"
+ * summary: "Get a PaymentCollection"
* description: "Retrieves a PaymentCollection."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts
index 8e8a0fbfb3..42346356f6 100644
--- a/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts
+++ b/packages/medusa/src/api/routes/admin/payment-collections/mark-authorized-payment-collection.ts
@@ -4,7 +4,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/authorize
* operationId: "PostPaymentCollectionsPaymentCollectionAuthorize"
- * summary: "Set the status of PaymentCollection as Authorized"
+ * summary: "Mark Authorized"
* description: "Sets the status of PaymentCollection as Authorized."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts
index 40adb2aed9..83af43a19b 100644
--- a/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts
+++ b/packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts
@@ -6,7 +6,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}
* operationId: "PostPaymentCollectionsPaymentCollection"
- * summary: "Updates a PaymentCollection"
+ * summary: "Update PaymentCollection"
* description: "Updates a PaymentCollection."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts
index 0148df84ef..9de91351d9 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts
@@ -9,7 +9,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [post] /publishable-api-keys/{id}/sales-channels/batch
* operationId: "PostPublishableApiKeySalesChannelsChannelsBatch"
- * summary: "Add sales channel to a publishable api key scope"
+ * summary: "Add SalesChannels"
* description: "Assign a batch of sales channels to a publishable api key."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts
index a0c08a2cda..a480f588b6 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts
@@ -7,7 +7,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [post] /publishable-api-keys
* operationId: "PostPublishableApiKeys"
- * summary: "Create a PublishableApiKey"
+ * summary: "Create PublishableApiKey"
* description: "Creates a PublishableApiKey."
* requestBody:
* content:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts
index b29b6de0fa..4c1d40206e 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts
@@ -9,7 +9,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [delete] /publishable-api-keys/{id}/sales-channels/batch
* operationId: "DeletePublishableApiKeySalesChannelsChannelsBatch"
- * summary: "Remove sales channel from a publishable api key scope"
+ * summary: "Delete SalesChannels"
* description: "Remove a batch of sales channels from a publishable api key."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts
index c916929798..25d69f06a0 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts
@@ -5,7 +5,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [delete] /publishable-api-keys/{id}
* operationId: "DeletePublishableApiKeysPublishableApiKey"
- * summary: "Delete a PublishableApiKey"
+ * summary: "Delete PublishableApiKey"
* description: "Deletes a PublishableApiKeys"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts
index eda1667d77..4223587400 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts
@@ -5,7 +5,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [get] /publishable-api-keys/{id}
* operationId: "GetPublishableApiKeysPublishableApiKey"
- * summary: "Get a Publishable API Key"
+ * summary: "Get a PublishableApiKey"
* description: "Retrieve the Publishable Api Key."
* parameters:
* - (path) id=* {string} The ID of the PublishableApiKey.
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts
index b9ac340377..47d575c5d5 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts
@@ -7,7 +7,7 @@ import { extendedFindParamsMixin } from "../../../../types/common"
/**
* @oas [get] /publishable-api-keys/{id}/sales-channels
* operationId: "GetPublishableApiKeySalesChannels"
- * summary: "List PublishableApiKey's SalesChannels"
+ * summary: "List SalesChannels"
* description: "List PublishableApiKey's SalesChannels"
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts
index 6afe33e0b7..863934838a 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts
@@ -6,7 +6,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [post] /publishable-api-keys/{id}/revoke
* operationId: "PostPublishableApiKeysPublishableApiKeyRevoke"
- * summary: "Revoke a PublishableApiKey"
+ * summary: "Revoke PublishableApiKey"
* description: "Revokes a PublishableApiKey."
* parameters:
* - (path) id=* {string} The ID of the PublishableApiKey.
diff --git a/packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts b/packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts
index 1b271cfca7..6d5d33ee6b 100644
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts
+++ b/packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts
@@ -7,7 +7,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
/**
* @oas [post] /publishable-api-key/{id}
* operationId: "PostPublishableApiKysPublishableApiKey"
- * summary: "Updates a PublishableApiKey"
+ * summary: "Update PublishableApiKey"
* description: "Updates a PublishableApiKey."
* x-authenticated: true
* parameters:
diff --git a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
index fc523c3d10..b87cffd814 100644
--- a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
@@ -4,8 +4,8 @@ import { IFileService } from "../../../../interfaces"
/**
* @oas [post] /uploads/protected
* operationId: "PostUploadsProtected"
- * summary: "Upload files with acl or in a non-public bucket"
- * description: "Uploads at least one file to the specific fileservice that is installed in Medusa."
+ * summary: "Protected File Upload"
+ * description: "Uploads at least one file with ACL or a non-public bucket to the specific fileservice that is installed in Medusa."
* x-authenticated: true
* requestBody:
* content:
diff --git a/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts b/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts
index d41dab78c5..c941c84585 100644
--- a/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts
+++ b/packages/medusa/src/api/routes/store/orders/confirm-order-request.ts
@@ -9,7 +9,7 @@ import {
/**
* @oas [post] /orders/customer/confirm
* operationId: "PostOrdersCustomerOrderClaimsCustomerOrderClaimAccept"
- * summary: "Verify a claim to orders"
+ * summary: "Verify an Order Claim"
* description: "Verifies the claim order token provided to the customer upon request of order ownership"
* requestBody:
* content:
@@ -44,7 +44,7 @@ import {
* - api_token: []
* - cookie_auth: []
* tags:
- * - Invite
+ * - Order
* responses:
* 200:
* description: OK
diff --git a/packages/medusa/src/api/routes/store/orders/request-order.ts b/packages/medusa/src/api/routes/store/orders/request-order.ts
index 39439fa648..ab9f8f36da 100644
--- a/packages/medusa/src/api/routes/store/orders/request-order.ts
+++ b/packages/medusa/src/api/routes/store/orders/request-order.ts
@@ -11,7 +11,7 @@ import { TokenEvents } from "../../../../types/token"
/**
* @oas [post] /orders/batch/customer/token
* operationId: "PostOrdersCustomerOrderClaim"
- * summary: "Claim orders for signed in account"
+ * summary: "Claim an Order"
* description: "Sends an email to emails registered to orders provided with link to transfer order ownership"
* requestBody:
* content:
diff --git a/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts b/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts
index b5a6ff4c98..3f6e5aa86f 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts
@@ -4,7 +4,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/sessions/batch/authorize
* operationId: "PostPaymentCollectionsSessionsBatchAuthorize"
- * summary: "Authorize Payment Sessions of a Payment Collection"
+ * summary: "Authorize PaymentSessions"
* description: "Authorizes Payment Sessions of a Payment Collection."
* x-authenticated: false
* parameters:
@@ -33,7 +33,7 @@ import { PaymentCollectionService } from "../../../../services"
* - api_token: []
* - cookie_auth: []
* tags:
- * - Payment
+ * - PaymentCollection
* responses:
* 200:
* description: OK
diff --git a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts
index b2d580b3c0..83b6ca2324 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts
@@ -5,7 +5,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/sessions/{session_id}/authorize
* operationId: "PostPaymentCollectionsSessionsSessionAuthorize"
- * summary: "Authorize a Payment Session of a Payment Collection"
+ * summary: "Authorize Payment Session"
* description: "Authorizes a Payment Session of a Payment Collection."
* x-authenticated: false
* parameters:
@@ -30,7 +30,7 @@ import { PaymentCollectionService } from "../../../../services"
* - api_token: []
* - cookie_auth: []
* tags:
- * - Payment
+ * - PaymentCollection
* responses:
* 200:
* description: OK
diff --git a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts
index b6402497b3..d9530b1aad 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts
@@ -4,8 +4,8 @@ import { FindParams } from "../../../../types/common"
/**
* @oas [get] /payment-collections/{id}
* operationId: "GetPaymentCollectionsPaymentCollection"
- * summary: "Retrieve an PaymentCollection"
- * description: "Retrieves a PaymentCollection."
+ * summary: "Get a PaymentCollection"
+ * description: "Get a Payment Collection"
* x-authenticated: false
* parameters:
* - (path) id=* {string} The ID of the PaymentCollection.
diff --git a/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts b/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts
index 549ddd4751..f3566df96b 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts
@@ -7,7 +7,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/sessions/batch
* operationId: "PostPaymentCollectionsPaymentCollectionSessionsBatch"
- * summary: "Manage Multiple Payment Sessions from Payment Collections"
+ * summary: "Manage Payment Sessions"
* description: "Manages Multiple Payment Sessions from Payment Collections."
* x-authenticated: false
* parameters:
@@ -61,7 +61,7 @@ import { PaymentCollectionService } from "../../../../services"
* - api_token: []
* - cookie_auth: []
* tags:
- * - Payment
+ * - PaymentCollection
* responses:
* 200:
* description: OK
diff --git a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts
index cc99e80093..861c9f19ee 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts
@@ -6,7 +6,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/sessions
* operationId: "PostPaymentCollectionsSessions"
- * summary: "Manage Payment Sessions from Payment Collections"
+ * summary: "Manage a Payment Session"
* description: "Manages Payment Sessions from Payment Collections."
* x-authenticated: false
* parameters:
@@ -40,7 +40,7 @@ import { PaymentCollectionService } from "../../../../services"
* - api_token: []
* - cookie_auth: []
* tags:
- * - Payment
+ * - PaymentCollection
* responses:
* 200:
* description: OK
diff --git a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts
index f7294588f7..ac91104d15 100644
--- a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts
@@ -4,7 +4,7 @@ import { PaymentCollectionService } from "../../../../services"
/**
* @oas [post] /payment-collections/{id}/sessions/{session_id}
* operationId: PostPaymentCollectionsPaymentCollectionPaymentSessionsSession
- * summary: Refresh a Payment Session
+ * summary: "Refresh a Payment Session"
* description: "Refreshes a Payment Session to ensure that it is in sync with the Payment Collection."
* x-authenticated: false
* parameters:
diff --git a/packages/medusa/src/services/event-bus.ts b/packages/medusa/src/services/event-bus.ts
index e9ae4d896d..da5068cae3 100644
--- a/packages/medusa/src/services/event-bus.ts
+++ b/packages/medusa/src/services/event-bus.ts
@@ -52,6 +52,7 @@ export default class EventBusService {
stagedJobRepository,
redisClient,
redisSubscriber,
+ jobSchedulerService,
}: InjectedDependencies,
config: ConfigModule,
singleton = true
@@ -59,6 +60,7 @@ export default class EventBusService {
this.config_ = config
this.manager_ = manager
this.logger_ = logger
+ this.jobSchedulerService_ = jobSchedulerService
this.stagedJobRepository_ = stagedJobRepository
if (singleton) {
diff --git a/www/docs/docusaurus.config.js b/www/docs/docusaurus.config.js
index 18497638d1..8dcfda82ad 100644
--- a/www/docs/docusaurus.config.js
+++ b/www/docs/docusaurus.config.js
@@ -191,7 +191,10 @@ const config = {
href: 'https://github.com/medusajs/medusa'
},
],
- reportCodeLinkPrefix: 'https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml'
+ reportCodeLinkPrefix: 'https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml',
+ footerFeedback: {
+ event: 'survey'
+ }
},
presets: [
[
diff --git a/www/docs/netlify.toml b/www/docs/netlify.toml
new file mode 100644
index 0000000000..03b920b820
--- /dev/null
+++ b/www/docs/netlify.toml
@@ -0,0 +1,87 @@
+[[redirects]]
+ from = "/api"
+ to = "/api/store"
+
+[[redirects]]
+ from = "/api/store/auth/*"
+ to = "/api/store/#tag/Auth"
+
+[[redirects]]
+ from = "/api/store/cart/*"
+ to = "/api/store/#tag/Cart"
+
+[[redirects]]
+ from = "/api/store/collection/*"
+ to = "/api/store/#tag/Collection"
+
+[[redirects]]
+ from = "/api/store/product/*"
+ to = "/api/store/#tag/Product"
+
+[[redirects]]
+ from = "/api/admin/auth/*"
+ to = "/api/admin/#tag/Auth"
+
+[[redirects]]
+ from = "/api/admin/users/*"
+ to = "/api/admin/#tag/User"
+
+[[redirects]]
+ from = "/how-to/headless-ecommerce-store-with-gatsby-contentful-medusa"
+ to = "/add-plugins/contentful"
+
+[[redirects]]
+ from = "/how-to/deploying-on-heroku"
+ to = "/deployments/server/deploying-on-heroku"
+
+[[redirects]]
+ from = "/admin/introduction"
+ to = "/admin/quickstart"
+
+[[redirects]]
+ from = "/admin/quickstart/quick-start"
+ to = "/admin/quickstart"
+
+[[redirects]]
+ from = "/admin/quickstart"
+ to = "/admin/quickstart"
+
+[[redirects]]
+ from = "/quickstart/starters/nextjs-medusa-starter"
+ to = "/starters/nextjs-medusa-starter"
+
+[[redirects]]
+ from = "/quickstart/starters/gatsby-medusa-starter"
+ to = "/starters/gatsby-medusa-starter"
+
+[[redirects]]
+ from = "/how-to/create-medusa-app"
+ to = "/usage/create-medusa-app"
+
+[[redirects]]
+ from = "/guides/plugins"
+ to = "/advanced/backend/plugins/overview"
+
+[[redirects]]
+ from = "/how-to/deploying-admin-on-netlify"
+ to = "/deployments/admin/deploying-on-netlify"
+
+[[redirects]]
+ from = "/how-to/deploying-on-digital-ocean/"
+ to = "/deployments/server/deploying-on-digital-ocean"
+
+[[redirects]]
+ from = "/how-to/deploying-on-qovery/"
+ to = "/deployments/server/deploying-on-qovery"
+
+[[redirects]]
+ from = "/guides/fulfillment-api"
+ to = "/advanced/backend/shipping/add-fulfillment-provider"
+
+[[redirects]]
+ from = "/guides/checkouts"
+ to = "/advanced/storefront/how-to-implement-checkout-flow"
+
+[[redirects]]
+ from = "/guides/checkouts"
+ to = "/advanced/storefront/how-to-implement-checkout-flow"
\ No newline at end of file
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
index 290528d71f..5616fd8b12 100644
--- a/www/docs/sidebars.js
+++ b/www/docs/sidebars.js
@@ -176,18 +176,13 @@ module.exports = {
items: [
{
type: "doc",
- id: "advanced/backend/upgrade-guides/1-3-0",
- label: "v1.3.0"
+ id: "advanced/backend/upgrade-guides/1-7-1",
+ label: "v1.7.1"
},
{
type: "doc",
- id: "advanced/backend/upgrade-guides/1-3-6",
- label: "v1.3.6"
- },
- {
- type: "doc",
- id: "advanced/backend/upgrade-guides/1-3-8",
- label: "v1.3.8"
+ id: "advanced/backend/upgrade-guides/1-7-0",
+ label: "v1.7.0"
},
{
type: "doc",
@@ -196,8 +191,18 @@ module.exports = {
},
{
type: "doc",
- id: "advanced/backend/upgrade-guides/1-7-0",
- label: "v1.7.0"
+ id: "advanced/backend/upgrade-guides/1-3-8",
+ label: "v1.3.8"
+ },
+ {
+ type: "doc",
+ id: "advanced/backend/upgrade-guides/1-3-6",
+ label: "v1.3.6"
+ },
+ {
+ type: "doc",
+ id: "advanced/backend/upgrade-guides/1-3-0",
+ label: "v1.3.0"
},
{
type: "doc",
@@ -237,6 +242,11 @@ module.exports = {
id: "advanced/storefront/use-regions",
label: "Use Regions"
},
+ {
+ type: "doc",
+ id: "advanced/storefront/customer-profiles",
+ label: "Add Customer Profiles"
+ },
{
type: "doc",
id: "guides/carts-in-medusa",
@@ -262,6 +272,11 @@ module.exports = {
id: "advanced/storefront/implement-claim-order",
label: "Implement Claim Order"
},
+ {
+ type: "doc",
+ id: "advanced/storefront/handle-order-edits",
+ label: "Handle Order Edits"
+ },
{
type: "doc",
id: "advanced/storefront/use-sales-channels",
@@ -275,8 +290,18 @@ module.exports = {
items: [
{
type: "doc",
- id: "advanced/admin/manage-regions",
- label: "Manage Regions"
+ id: "advanced/admin/order-edit",
+ label: "Edit an Order"
+ },
+ {
+ type: "doc",
+ id: "advanced/admin/manage-customers",
+ label: "Manage Customers"
+ },
+ {
+ type: "doc",
+ id: "advanced/admin/use-customergroups-api",
+ label: "Manage Customer Groups"
},
{
type: "doc",
@@ -291,22 +316,22 @@ module.exports = {
{
type: "doc",
id: "advanced/backend/price-lists/use-api",
- label: "Use PriceList APIs"
- },
- {
- type: "doc",
- id: "advanced/backend/sales-channels/manage-admin",
- label: "Use SalesChannel APIs"
- },
- {
- type: "doc",
- id: "advanced/admin/use-customergroups-api",
- label: "Use CustomerGroup APIs"
+ label: "Manage PriceLists"
},
{
type: "doc",
id: "advanced/admin/manage-discounts",
- label: "Use Discount APIs"
+ label: "Manage Discounts"
+ },
+ {
+ type: "doc",
+ id: "advanced/admin/manage-regions",
+ label: "Manage Regions"
+ },
+ {
+ type: "doc",
+ id: "advanced/backend/sales-channels/manage-admin",
+ label: "Manage Sales Channels"
},
]
},
@@ -444,6 +469,10 @@ module.exports = {
id: "advanced/backend/regions/overview",
label: "Regions"
},
+ {
+ type: "doc",
+ id: "advanced/backend/customers/index"
+ },
{
type: "doc",
id: "advanced/backend/taxes/inclusive-pricing",
@@ -607,6 +636,16 @@ module.exports = {
id: "troubleshooting/cli-installation-errors",
label: "Errors Installing CLI",
},
+ {
+ type: "doc",
+ id: "troubleshooting/common-installation-errors",
+ label: "Installation Errors",
+ },
+ {
+ type: "doc",
+ id: "troubleshooting/database-error",
+ label: "Database SASL Error",
+ },
{
type: "doc",
id: "troubleshooting/cors-issues",
diff --git a/www/docs/src/components/Feedback/index.css b/www/docs/src/components/Feedback/index.css
index cfbf36696d..d67e1f66af 100644
--- a/www/docs/src/components/Feedback/index.css
+++ b/www/docs/src/components/Feedback/index.css
@@ -1,6 +1,7 @@
.feedback-container {
padding-top: var(--ifm-base-margin-vertical);
+ padding-bottom: var(--ifm-base-margin-vertical);
border-top: 1px solid var(--ifm-doc-footer-border-color);
}
diff --git a/www/docs/src/components/Feedback/index.js b/www/docs/src/components/Feedback/index.js
index ffc4a6ce54..47ff900210 100644
--- a/www/docs/src/components/Feedback/index.js
+++ b/www/docs/src/components/Feedback/index.js
@@ -5,7 +5,16 @@ import './index.css';
import useIsBrowser from '@docusaurus/useIsBrowser';
import {useLocation} from '@docusaurus/router';
-export default function Feedback () {
+export default function Feedback ({
+ event,
+ question = 'Was this page helpful?',
+ positiveBtn = 'Yes',
+ negativeBtn = 'No',
+ positiveQuestion = 'What was most helpful?',
+ negativeQuestion = 'What can we improve?',
+ submitBtn = 'Submit',
+ submitMessage = 'Thank you for helping improve our documentation!'
+}) {
const [showForm, setShowForm] = useState(false);
const [submittedFeedback, setSubmittedFeedback] = useState(false);
const [loading, setLoading] = useState(false);
@@ -28,7 +37,7 @@ export default function Feedback () {
if (isBrowser) {
if (window.analytics) {
setLoading(true);
- window.analytics.track('survey', {
+ window.analytics.track(event, {
url: location.pathname,
label: document.title,
feedback: positiveFeedback ? 'yes' : 'no',
@@ -63,21 +72,21 @@ export default function Feedback () {
<>
{(!showForm && !submittedFeedback) && (
{cart !== undefined && (
,
+ "client-id": "",
"currency": "EUR",
- "intent": "authorize"
+ "intent": "authorize",
}}>
{errorMessage && (
{errorMessage}
@@ -362,10 +382,10 @@ function Paypal() {
)}
- );
+ )
}
-export default Paypal;
+export default Paypal
```
Here’s briefly what this code snippet does:
@@ -384,6 +404,8 @@ If you run the Medusa server and the storefront server, you should see the PayPa
+---
+
## Capture Payments
After the customer places an order, you can see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button.
@@ -394,6 +416,8 @@ Clicking this button lets you capture the payment for an order. You can also ref
Refunding or Capturing payments is reflected in your PayPal dashboard as well.
-## What's Next
+---
+
+## See Also
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.
diff --git a/docs/content/add-plugins/s3.md b/docs/content/add-plugins/s3.md
index 92bc00aba2..943d92f606 100644
--- a/docs/content/add-plugins/s3.md
+++ b/docs/content/add-plugins/s3.md
@@ -8,16 +8,20 @@ To manage images in Medusa, you need a file service plugin responsible for hosti
Medusa provides three different options to handle your file storage. This document focuses on using [S3](https://aws.amazon.com/s3/) to store your Medusa server’s images.
+---
+
## Prerequisites
### Medusa Server
-A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.md) to get started in minutes.
+A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.mdx) to get started in minutes.
### Required Accounts
You need to [create an AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin) to follow along with this documentation.
+---
+
## Create S3 Bucket
On your AWS Console, search for S3 in the search box at the top. Then, choose the first result you see which should be S3 under the Services category.
@@ -42,6 +46,8 @@ Then, in the “Block Public Access settings for this bucket” section, uncheck
You can leave the rest of the fields in the form as is and scroll down to the end of the page. Then, click on the Create Bucket button.
+---
+
## Manage Bucket Policies
On the page of the bucket you just created, click on the Permissions tab. Then, scroll down until you find the Bucket policy section. Click on Edit in that section.
@@ -80,6 +86,8 @@ Your user must have the `AmazonS3FullAccess` policy attached to it. You can refe
You must obtain access keys for your user as you’ll use them to integrate the S3 plugin in Medusa with your bucket. To obtain the Access Key ID and the Secret Access Key, check out [this guide](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
+---
+
## Install the S3 Plugin
In the directory of your Medusa server, run the following command to install the S3 Plugin:
@@ -110,7 +118,7 @@ Finally, in `medusa-config.js`, add to the `plugins` array the following new ite
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-file-s3`,
options: {
@@ -121,7 +129,7 @@ const plugins = [
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
},
},
-];
+]
```
### Add AWS Configurations
@@ -132,7 +140,7 @@ For example, you can pass the `region`, `access_key_id` and `secret_access_key`
```jsx title=medusa-config.js
const plugins = [
- //...
+ // ...
{
resolve: `medusa-file-s3`,
options: {
@@ -142,10 +150,10 @@ const plugins = [
region: process.env.S3_REGION,
access_key_id: process.env.S3_ACCESS_KEY_ID,
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
- }
+ },
},
},
-];
+]
```
Make sure to define `S3_REGION`, `S3_ACCESS_KEY_ID`, and `S3_SECRET_ACCESS_KEY` in your environment variables first.
@@ -157,6 +165,8 @@ If you have multiple storage plugins configured, the last plugin declared in the
:::
+---
+
## Test the S3 Plugin
Run your Medusa server with the following command:
@@ -165,7 +175,7 @@ Run your Medusa server with the following command:
npm run start
```
-Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.md).
+Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.mdx).
On the Medusa Admin, create a new product and, in the Images section, upload an image then click Save. If the integration was successful, the product image will be uploaded successfully.
@@ -175,9 +185,11 @@ You can also check that the image was uploaded on the S3 bucket’s page.
+---
+
## Next.js Storefront Configuration
-If you’re using a [Next.js](../starters/nextjs-medusa-starter.md) storefront, you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket.
+If you’re using a [Next.js](../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket.
If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
@@ -186,14 +198,14 @@ In `next.config.js` add the following option in the exported object:
```jsx title=next.config.js
const { withStoreConfig } = require("./store-config")
-//...
+// ...
module.exports = withStoreConfig({
- //...
+ // ...
images: {
domains: [
- //...
- "
{clientSecret && (
)}
- );
+ )
};
```
@@ -229,15 +237,19 @@ Once the clientSecret is set, the `Elements` Stripe component will wrap a `Form`
Create a new file for the `Form` component with the following content:
```jsx
-import {CardElement, useElements, useStripe} from '@stripe/react-stripe-js';
+import {
+ CardElement,
+ useElements,
+ useStripe,
+} from "@stripe/react-stripe-js"
-export default function Form({clientSecret, cartId}) {
- const stripe = useStripe();
- const elements = useElements();
+export default function Form({ clientSecret, cartId }) {
+ const stripe = useStripe()
+ const elements = useElements()
async function handlePayment(e) {
e.preventDefault()
- //TODO handle payment
+ // TODO handle payment
}
return (
@@ -245,7 +257,7 @@ export default function Form({clientSecret, cartId}) {
+---
+
## Install the Admin
:::tip
@@ -53,6 +59,21 @@ Then, install the dependencies:
npm install
```
+-
+ {orderEdit.changes.map((itemChange) => (
+
- + + { + itemChange.line_item ? + itemChange.line_item.title : + itemChange.original_line_item.title + } + + {itemChange.type === "added" && New Item} + {itemChange.type === "removed" && Removed Item} + {itemChange.type === "edited" && + + Edited Item + Old Quantity: {itemChange.original_line_item.quantity} + New Quantity: {itemChange.line_item.quantity} + } + + ))} +
+---
+
## Prerequisites
### Medusa Components
-Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally. If not, please go through the [quickstart guide](../../starters/gatsby-medusa-starter.md) first.
+Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally. If not, please go through the [quickstart guide](../../starters/gatsby-medusa-starter.mdx) first.
Additionally, this documentation does not cover how to deploy the Medusa server. If you want to deploy the Medusa server, [check out one of the deployment documentation related to the Medusa server](../server/index.mdx).
@@ -35,6 +37,8 @@ If you want to use another Git Provider, it’s possible to follow along with th
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
+---
+
## Create GitHub Repository
Before you can deploy your Gatsby storefront you need to create a GitHub repository and push the code base to it.
@@ -74,6 +78,8 @@ git push origin master
After pushing the changes, you can find the files in your GitHub repository.
+---
+
## Deploy to Netlify
This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool.
@@ -291,6 +297,8 @@ The Gatsby storefront will then open in your browser.
Before you can use the Gatsby storefront, you must add the URL as an environment variable on your deployed Medusa server.
+---
+
## Configure CORS Variable on the Medusa Server
To send requests to the Medusa server from the Gatsby storefront, you must set the `STORE_CORS` environment variable on your server to the Gatsby storefront’s URL.
@@ -311,7 +319,9 @@ Where `
+---
+
## Prerequisites
-This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.md) to learn how to do it.
+This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.mdx) to learn how to do it.
You should also have the Gatsby CLI installed:
@@ -22,6 +26,8 @@ You should also have the Gatsby CLI installed:
npm install gatsby-cli -g
```
+---
+
## Installation
:::tip
@@ -51,6 +57,21 @@ npm run start
Your Gatsby storefront is now running at `localhost:8000`!
+
+---
+
## Prerequisites
-This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.md) to learn how to do it.
+This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.mdx) to learn how to do it.
+
+---
## Installation
@@ -24,13 +30,13 @@ It is recommended to use [Yarn](https://yarnpkg.com/getting-started/install) for
:::
-1\. Create a new Next.js project using the [Medusa starter template](https://github.com/medusajs/nextjs-starter-medusa):
+1\. Create a new Next.js project using the [Medusa starter template](https://github.com/medusajs/nextjs-starter-medusa):
```bash
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
```
-2\. Change to the newly created directory `my-medusa-storefront` and rename the template environment variable file to use environment variables in development:
+2\. Change to the newly created directory `my-medusa-storefront` and rename the template environment variable file to use environment variables in development:
```bash
cd my-medusa-storefront
@@ -43,7 +49,22 @@ mv .env.template .env.local
npm run dev
```
-Your Next.js storefront is now running at `localhost:8000`!
+Your Next.js storefront is now running at `localhost:8000`!
+
+
- Was this page helpful?
-
-
+ {question}
+
+
)}
{(showForm && !submittedFeedback) && (
- {positiveFeedback ? 'What was most helpful?' : 'What can we improve?'}
+ {positiveFeedback ? positiveQuestion : negativeQuestion}
-
+
)}
{submittedFeedback && (
- Thank you for helping improve our documentation!
+ {submitMessage}
)}
diff --git a/www/docs/src/css/_docspage.css b/www/docs/src/css/_docspage.css
index 7d93f33ea8..deb48dfd4c 100644
--- a/www/docs/src/css/_docspage.css
+++ b/www/docs/src/css/_docspage.css
@@ -83,7 +83,7 @@ kbd {
}
.theme-doc-footer {
- margin-top: var(--ifm-base-margin-vertical) !important;
+ margin-top: 0 !important;
border-top: 1px solid var(--ifm-doc-footer-border-color) !important;
padding-top: var(--ifm-base-margin-vertical);
}
diff --git a/www/docs/src/theme/DocItem/Footer/index.js b/www/docs/src/theme/DocItem/Footer/index.js
index ee7380f112..3776679a9e 100644
--- a/www/docs/src/theme/DocItem/Footer/index.js
+++ b/www/docs/src/theme/DocItem/Footer/index.js
@@ -2,15 +2,17 @@ import React from 'react';
import Footer from '@theme-original/DocItem/Footer';
import Feedback from '../../../components/Feedback';
import { useDoc } from '@docusaurus/theme-common/internal';
+import {useThemeConfig} from '@docusaurus/theme-common';
export default function FooterWrapper(props) {
const { metadata } = useDoc()
+ const { footerFeedback = { event: '' } } = useThemeConfig();
return (
<>
{!metadata.frontMatter?.hide_footer && (
-
)}
diff --git a/yarn.lock b/yarn.lock
index c8773f73be..e7c74d45f0 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1826,7 +1826,7 @@ __metadata:
languageName: node
linkType: hard
-"@babel/preset-react@npm:^7.12.10, @babel/preset-react@npm:^7.14.0":
+"@babel/preset-react@npm:^7.12.10, @babel/preset-react@npm:^7.14.0, @babel/preset-react@npm:^7.18.6":
version: 7.18.6
resolution: "@babel/preset-react@npm:7.18.6"
dependencies:
@@ -9888,6 +9888,19 @@ __metadata:
languageName: node
linkType: hard
+"array-includes@npm:^3.1.6":
+ version: 3.1.6
+ resolution: "array-includes@npm:3.1.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ get-intrinsic: ^1.1.3
+ is-string: ^1.0.7
+ checksum: d0caeaa57bea7d14b8480daee30cf8611899321006b15a6cd872b831bd7aaed7649f8764e060d01c5d33b8d9e998e5de5c87f4901874e1c1f467f429b7db2929
+ languageName: node
+ linkType: hard
+
"array-union@npm:^1.0.2":
version: 1.0.2
resolution: "array-union@npm:1.0.2"
@@ -9942,6 +9955,18 @@ __metadata:
languageName: node
linkType: hard
+"array.prototype.flatmap@npm:^1.3.1":
+ version: 1.3.1
+ resolution: "array.prototype.flatmap@npm:1.3.1"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ es-shim-unscopables: ^1.0.0
+ checksum: 2bd58a0e79d5d90cb4f5ef0e287edf8b28e87c65428f54025ac6b7b4c204224b92811c266f296c53a2dbc93872117c0fcea2e51d3c9e8cecfd5024d4a4a57db4
+ languageName: node
+ linkType: hard
+
"array.prototype.map@npm:^1.0.4":
version: 1.0.4
resolution: "array.prototype.map@npm:1.0.4"
@@ -9968,6 +9993,19 @@ __metadata:
languageName: node
linkType: hard
+"array.prototype.tosorted@npm:^1.1.1":
+ version: 1.1.1
+ resolution: "array.prototype.tosorted@npm:1.1.1"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ es-shim-unscopables: ^1.0.0
+ get-intrinsic: ^1.1.3
+ checksum: fd5f57aca3c7ddcd1bb83965457b625f3a67d8f334f5cbdb8ac8ef33d5b0d38281524114db2936f8c08048115d5158af216c94e6ae1eb966241b9b6f4ab8a7e8
+ languageName: node
+ linkType: hard
+
"arrify@npm:^1.0.1":
version: 1.0.1
resolution: "arrify@npm:1.0.1"
@@ -13756,7 +13794,7 @@ __metadata:
languageName: node
linkType: hard
-"debug@npm:4, debug@npm:^4.0.1, debug@npm:^4.1.0, debug@npm:^4.1.1, debug@npm:^4.3.1, debug@npm:^4.3.2, debug@npm:^4.3.3, debug@npm:^4.3.4, debug@npm:~4.3.1":
+"debug@npm:4, debug@npm:^4.0.0, debug@npm:^4.0.1, debug@npm:^4.1.0, debug@npm:^4.1.1, debug@npm:^4.3.1, debug@npm:^4.3.2, debug@npm:^4.3.3, debug@npm:^4.3.4, debug@npm:~4.3.1":
version: 4.3.4
resolution: "debug@npm:4.3.4"
dependencies:
@@ -14894,6 +14932,39 @@ __metadata:
languageName: node
linkType: hard
+"es-abstract@npm:^1.20.4":
+ version: 1.20.5
+ resolution: "es-abstract@npm:1.20.5"
+ dependencies:
+ call-bind: ^1.0.2
+ es-to-primitive: ^1.2.1
+ function-bind: ^1.1.1
+ function.prototype.name: ^1.1.5
+ get-intrinsic: ^1.1.3
+ get-symbol-description: ^1.0.0
+ gopd: ^1.0.1
+ has: ^1.0.3
+ has-property-descriptors: ^1.0.0
+ has-symbols: ^1.0.3
+ internal-slot: ^1.0.3
+ is-callable: ^1.2.7
+ is-negative-zero: ^2.0.2
+ is-regex: ^1.1.4
+ is-shared-array-buffer: ^1.0.2
+ is-string: ^1.0.7
+ is-weakref: ^1.0.2
+ object-inspect: ^1.12.2
+ object-keys: ^1.1.1
+ object.assign: ^4.1.4
+ regexp.prototype.flags: ^1.4.3
+ safe-regex-test: ^1.0.0
+ string.prototype.trimend: ^1.0.6
+ string.prototype.trimstart: ^1.0.6
+ unbox-primitive: ^1.0.2
+ checksum: c99f8a3e9ac15890cde5bf78d1910d72758d3e79c710bd1ad2ab6b595d39ad07209626befaa7c18591bd935a02f6a3bdba3a7e9c8dd6a01146e655df09dc4353
+ languageName: node
+ linkType: hard
+
"es-array-method-boxes-properly@npm:^1.0.0":
version: 1.0.0
resolution: "es-array-method-boxes-properly@npm:1.0.0"
@@ -15265,6 +15336,17 @@ __metadata:
languageName: node
linkType: hard
+"eslint-plugin-markdown@npm:^3.0.0":
+ version: 3.0.0
+ resolution: "eslint-plugin-markdown@npm:3.0.0"
+ dependencies:
+ mdast-util-from-markdown: ^0.8.5
+ peerDependencies:
+ eslint: ^6.0.0 || ^7.0.0 || ^8.0.0
+ checksum: 3424fd97b6990cbed7be3764ae8bec7eae9bd1cc03cd76d8d1cf38e088a9777ed4491921e7e1a8d3a146361bcd935e5ed1b2bfd4fd623bcdafdb824bccfdd2b2
+ languageName: node
+ linkType: hard
+
"eslint-plugin-prettier@npm:^4.2.1":
version: 4.2.1
resolution: "eslint-plugin-prettier@npm:4.2.1"
@@ -15313,6 +15395,31 @@ __metadata:
languageName: node
linkType: hard
+"eslint-plugin-react@npm:^7.31.11":
+ version: 7.31.11
+ resolution: "eslint-plugin-react@npm:7.31.11"
+ dependencies:
+ array-includes: ^3.1.6
+ array.prototype.flatmap: ^1.3.1
+ array.prototype.tosorted: ^1.1.1
+ doctrine: ^2.1.0
+ estraverse: ^5.3.0
+ jsx-ast-utils: ^2.4.1 || ^3.0.0
+ minimatch: ^3.1.2
+ object.entries: ^1.1.6
+ object.fromentries: ^2.0.6
+ object.hasown: ^1.1.2
+ object.values: ^1.1.6
+ prop-types: ^15.8.1
+ resolve: ^2.0.0-next.3
+ semver: ^6.3.0
+ string.prototype.matchall: ^4.0.8
+ peerDependencies:
+ eslint: ^3 || ^4 || ^5 || ^6 || ^7 || ^8
+ checksum: 2f8d27adbfe1b551a170cc1340dd8bbecf6c9fdbfcde04dd1097bbf198e99f0c981af84bc3c69f851af5736cc4d6520687a03dfb3271717079f88983d79cb9cd
+ languageName: node
+ linkType: hard
+
"eslint-plugin-testing-library@npm:^5.5.1":
version: 5.5.1
resolution: "eslint-plugin-testing-library@npm:5.5.1"
@@ -17753,6 +17860,17 @@ __metadata:
languageName: node
linkType: hard
+"get-intrinsic@npm:^1.1.3":
+ version: 1.1.3
+ resolution: "get-intrinsic@npm:1.1.3"
+ dependencies:
+ function-bind: ^1.1.1
+ has: ^1.0.3
+ has-symbols: ^1.0.3
+ checksum: 6f201d5f95ea0dd6c8d0dc2c265603aff0b9e15614cb70f8f4674bb3d2b2369d521efaa84d0b70451d2c00762ebd28402758bf46279c6f2a00d242ebac0d8442
+ languageName: node
+ linkType: hard
+
"get-own-enumerable-property-symbols@npm:^3.0.0":
version: 3.0.2
resolution: "get-own-enumerable-property-symbols@npm:3.0.2"
@@ -18152,6 +18270,15 @@ __metadata:
languageName: node
linkType: hard
+"gopd@npm:^1.0.1":
+ version: 1.0.1
+ resolution: "gopd@npm:1.0.1"
+ dependencies:
+ get-intrinsic: ^1.1.3
+ checksum: 505c05487f7944c552cee72087bf1567debb470d4355b1335f2c262d218ebbff805cd3715448fe29b4b380bae6912561d0467233e4165830efd28da241418c63
+ languageName: node
+ linkType: hard
+
"got@npm:^11.8.2, got@npm:^11.8.5":
version: 11.8.5
resolution: "got@npm:11.8.5"
@@ -19613,6 +19740,13 @@ __metadata:
languageName: node
linkType: hard
+"is-callable@npm:^1.2.7":
+ version: 1.2.7
+ resolution: "is-callable@npm:1.2.7"
+ checksum: ceebaeb9d92e8adee604076971dd6000d38d6afc40bb843ea8e45c5579b57671c3f3b50d7f04869618242c6cee08d1b67806a8cb8edaaaf7c0748b3720d6066f
+ languageName: node
+ linkType: hard
+
"is-ci@npm:^2.0.0":
version: 2.0.0
resolution: "is-ci@npm:2.0.0"
@@ -23624,6 +23758,19 @@ __metadata:
languageName: node
linkType: hard
+"mdast-util-from-markdown@npm:^0.8.5":
+ version: 0.8.5
+ resolution: "mdast-util-from-markdown@npm:0.8.5"
+ dependencies:
+ "@types/mdast": ^3.0.0
+ mdast-util-to-string: ^2.0.0
+ micromark: ~2.11.0
+ parse-entities: ^2.0.0
+ unist-util-stringify-position: ^2.0.0
+ checksum: 86e7589e574378817c180f10ab602db844b6b71b7b1769314947a02ef42ac5c1435f5163d02a975ae8cdab8b6e6176acbd9188da1848ddd5f0d5e09d0291c870
+ languageName: node
+ linkType: hard
+
"mdast-util-to-hast@npm:10.0.1":
version: 10.0.1
resolution: "mdast-util-to-hast@npm:10.0.1"
@@ -23647,6 +23794,13 @@ __metadata:
languageName: node
linkType: hard
+"mdast-util-to-string@npm:^2.0.0":
+ version: 2.0.0
+ resolution: "mdast-util-to-string@npm:2.0.0"
+ checksum: a4231085133cdfec24644b694c13661e5a01d26716be0105b6792889faa04b8030e4abbf72d4be3363098b2b38b2b98f1f1f1f0858eb6580dc04e2aca1436a37
+ languageName: node
+ linkType: hard
+
"mdn-data@npm:2.0.14":
version: 2.0.14
resolution: "mdn-data@npm:2.0.14"
@@ -24723,6 +24877,16 @@ __metadata:
languageName: node
linkType: hard
+"micromark@npm:~2.11.0":
+ version: 2.11.4
+ resolution: "micromark@npm:2.11.4"
+ dependencies:
+ debug: ^4.0.0
+ parse-entities: ^2.0.0
+ checksum: 67307cbacae621ab1eb23e333a5addc7600cf97d3b40cad22fc1c2d03d734d6d9cbc3f5a7e5d655a8c0862a949abe590ab7cfa96be366bfe09e239a94e6eea55
+ languageName: node
+ linkType: hard
+
"micromatch@npm:4.x, micromatch@npm:^4.0.2, micromatch@npm:^4.0.4, micromatch@npm:^4.0.5":
version: 4.0.5
resolution: "micromatch@npm:4.0.5"
@@ -26102,7 +26266,7 @@ __metadata:
languageName: node
linkType: hard
-"object-inspect@npm:^1.12.0, object-inspect@npm:^1.9.0":
+"object-inspect@npm:^1.12.0, object-inspect@npm:^1.12.2, object-inspect@npm:^1.9.0":
version: 1.12.2
resolution: "object-inspect@npm:1.12.2"
checksum: e1bd625f4c44a2f733bd69cfccce6469f71333fb09c6de151f4f346c16d658ef7555727b12652c108e20c2afb908ae7cd165f52ca53745a1d6cbf228cdb46ebe
@@ -26154,6 +26318,18 @@ __metadata:
languageName: node
linkType: hard
+"object.assign@npm:^4.1.4":
+ version: 4.1.4
+ resolution: "object.assign@npm:4.1.4"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ has-symbols: ^1.0.3
+ object-keys: ^1.1.1
+ checksum: 2f286118c023e557757620e647b02e7c88d3d417e0c568fca0820de8ec9cca68928304854d5b03e99763eddad6e78a6716e2930f7e6372e4b9b843f3fd3056f3
+ languageName: node
+ linkType: hard
+
"object.entries@npm:^1.1.0, object.entries@npm:^1.1.5":
version: 1.1.5
resolution: "object.entries@npm:1.1.5"
@@ -26165,6 +26341,17 @@ __metadata:
languageName: node
linkType: hard
+"object.entries@npm:^1.1.6":
+ version: 1.1.6
+ resolution: "object.entries@npm:1.1.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: 8782c71db3a068ccbae9e0541e6b4ac2c25dc67c63f97b7e6ad3c88271d7820197e7398e37747f96542ed47c27f0b81148cdf14c42df15dc22f64818ae7bb5bf
+ languageName: node
+ linkType: hard
+
"object.fromentries@npm:^2.0.0 || ^1.0.0, object.fromentries@npm:^2.0.5":
version: 2.0.5
resolution: "object.fromentries@npm:2.0.5"
@@ -26176,6 +26363,17 @@ __metadata:
languageName: node
linkType: hard
+"object.fromentries@npm:^2.0.6":
+ version: 2.0.6
+ resolution: "object.fromentries@npm:2.0.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: db6759ea68131cbdb70b1152f9984b49db03e81de4f6de079b39929bebd8b45501e5333ca2351991e07ee56f4651606c023396644e8f25c0806fa39a26c4c6e6
+ languageName: node
+ linkType: hard
+
"object.getownpropertydescriptors@npm:^2.0.3, object.getownpropertydescriptors@npm:^2.1.1, object.getownpropertydescriptors@npm:^2.1.2":
version: 2.1.4
resolution: "object.getownpropertydescriptors@npm:2.1.4"
@@ -26198,6 +26396,16 @@ __metadata:
languageName: node
linkType: hard
+"object.hasown@npm:^1.1.2":
+ version: 1.1.2
+ resolution: "object.hasown@npm:1.1.2"
+ dependencies:
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: 419fc1c74a2aea7ebb4d49b79d5b1599a010b26c18eae35bd061ccdd013ccb749c499d8dd6ee21a91e6d7264ccc592573d0f13562970f76e25fc844d8c1b02ce
+ languageName: node
+ linkType: hard
+
"object.pick@npm:^1.3.0":
version: 1.3.0
resolution: "object.pick@npm:1.3.0"
@@ -26218,6 +26426,17 @@ __metadata:
languageName: node
linkType: hard
+"object.values@npm:^1.1.6":
+ version: 1.1.6
+ resolution: "object.values@npm:1.1.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: 3381204390f10c9f653a4875a50d221c67b5c16cb80a6ac06c706fc82a7cad8400857d4c7a0731193b0abb56b84fe803eabcf7addcf32de76397bbf207e68c66
+ languageName: node
+ linkType: hard
+
"objectFitPolyfill@npm:^2.3.5":
version: 2.3.5
resolution: "objectFitPolyfill@npm:2.3.5"
@@ -30150,6 +30369,7 @@ __metadata:
"@babel/plugin-transform-instanceof": ^7.10.4
"@babel/plugin-transform-runtime": ^7.11.5
"@babel/preset-env": ^7.11.5
+ "@babel/preset-react": ^7.18.6
"@babel/register": ^7.11.5
"@babel/runtime": ^7.11.2
"@changesets/changelog-github": ^0.4.5
@@ -30167,7 +30387,9 @@ __metadata:
eslint: ^8.23.0
eslint-config-google: ^0.14.0
eslint-config-prettier: ^8.5.0
+ eslint-plugin-markdown: ^3.0.0
eslint-plugin-prettier: ^4.2.1
+ eslint-plugin-react: ^7.31.11
express: ^4.17.1
get-port: ^5.1.1
global: ^4.4.0
@@ -30295,6 +30517,17 @@ __metadata:
languageName: node
linkType: hard
+"safe-regex-test@npm:^1.0.0":
+ version: 1.0.0
+ resolution: "safe-regex-test@npm:1.0.0"
+ dependencies:
+ call-bind: ^1.0.2
+ get-intrinsic: ^1.1.3
+ is-regex: ^1.1.4
+ checksum: 14a81a7e683f97b2d6e9c8be61fddcf8ed7a02f4e64a825515f96bb1738eb007145359313741d2704d28b55b703a0f6300c749dde7c1dbc13952a2b85048ede2
+ languageName: node
+ linkType: hard
+
"safe-regex@npm:^1.1.0":
version: 1.1.0
resolution: "safe-regex@npm:1.1.0"
@@ -31814,6 +32047,22 @@ __metadata:
languageName: node
linkType: hard
+"string.prototype.matchall@npm:^4.0.8":
+ version: 4.0.8
+ resolution: "string.prototype.matchall@npm:4.0.8"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ get-intrinsic: ^1.1.3
+ has-symbols: ^1.0.3
+ internal-slot: ^1.0.3
+ regexp.prototype.flags: ^1.4.3
+ side-channel: ^1.0.4
+ checksum: 644523d05c1ee93bab7474e999a5734ee5f6ad2d7ad24ed6ea8706c270dc92b352bde0f2a5420bfbeed54e28cb6a770c3800e1988a5267a70fd5e677c7750abc
+ languageName: node
+ linkType: hard
+
"string.prototype.padend@npm:^3.0.0":
version: 3.1.3
resolution: "string.prototype.padend@npm:3.1.3"
@@ -31847,6 +32096,17 @@ __metadata:
languageName: node
linkType: hard
+"string.prototype.trimend@npm:^1.0.6":
+ version: 1.0.6
+ resolution: "string.prototype.trimend@npm:1.0.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: 51b663e3195a74b58620a250b3fc4efb58951000f6e7d572a9f671c038f2f37f24a2b8c6994500a882aeab2f1c383fac1e8c023c01eb0c8b4e52d2f13b6c4513
+ languageName: node
+ linkType: hard
+
"string.prototype.trimstart@npm:^1.0.5":
version: 1.0.5
resolution: "string.prototype.trimstart@npm:1.0.5"
@@ -31858,6 +32118,17 @@ __metadata:
languageName: node
linkType: hard
+"string.prototype.trimstart@npm:^1.0.6":
+ version: 1.0.6
+ resolution: "string.prototype.trimstart@npm:1.0.6"
+ dependencies:
+ call-bind: ^1.0.2
+ define-properties: ^1.1.4
+ es-abstract: ^1.20.4
+ checksum: 13b9970d4e234002dfc8069c655c1fe19e83e10ced208b54858c41bb0f7544e581ac0ce746e92b279563664ad63910039f7253f36942113fec413b2b4e7c1fcd
+ languageName: node
+ linkType: hard
+
"string_decoder@npm:^1.0.0, string_decoder@npm:^1.1.1":
version: 1.3.0
resolution: "string_decoder@npm:1.3.0"