Generating Migrations for Entities
@@ -104,6 +104,6 @@ If you check your database now you should see that the change defined by the mig
---
-## What’s Next
+## See Also
-- [Set up your development server](../../../tutorial/0-set-up-your-development-environment.mdx).
+- [Create a Plugin](../../plugins/create.md)
diff --git a/docs/content/advanced/backend/migrations/overview.md b/docs/content/development/entities/migrations/overview.mdx
similarity index 55%
rename from docs/content/advanced/backend/migrations/overview.md
rename to docs/content/development/entities/migrations/overview.mdx
index 1d60316be4dbe..c868fcbb4fb97 100644
--- a/docs/content/advanced/backend/migrations/overview.md
+++ b/docs/content/development/entities/migrations/overview.mdx
@@ -1,22 +1,25 @@
---
-description: 'Learn what Migrations are in the Medusa server and how to run them. Migrations are used to make changes to the database schema the Medusa server is linked to.'
+description: 'Learn what Migrations are in Medusa and how to run them. Migrations are used to make changes to the database schema that Medusa is linked to.'
---
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
# Migrations
In this document, you'll learn what Migrations are in Medusa.
:::note
-Medusa’s Migrations do not work with SQLite databases. They are intended to be used with PostgreSQL databases, which is the recommended Database for your Medusa production server.
+Medusa’s Migrations do not work with SQLite databases. They are intended to be used with PostgreSQL databases, which is the recommended database for using Medusa in production.
:::
## What are Migrations
-Migrations are scripts that are used to make additions or changes to your database schema. In Medusa, they are essential for both when you first install your server and for subsequent server upgrades later on.
+Migrations are scripts that are used to make additions or changes to your database schema. In Medusa, they are essential for both when you first install your backend and for subsequent backend upgrades later on.
-When you first create your Medusa server, the database schema used must have all the tables necessary for the server to run.
+When you first create your Medusa backend, the database schema used must have all the tables necessary for the backend to run.
When a new Medusa version introduces changes to the database schema, you'll have to run migrations to apply them to your own database.
@@ -40,7 +43,7 @@ Using the Medusa CLI tool, you can run migrations with the following command:
medusa migrations run
```
-This will check for any migrations that contain changes to your database schema that aren't applied yet and run them on your server.
+This will check for any migrations that contain changes to your database schema that aren't applied yet and run them on your backend.
### Seed Command
@@ -52,11 +55,31 @@ You can use the following command to seed your database:
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.
+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 backend.
---
-## See Also
-
-- [Create a migration](index.md)
-- [Set up your development environment](../../../tutorial/set-up-your-development-environment)
+## Custom Development
+
+Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/entities/overview.md b/docs/content/development/entities/overview.mdx
similarity index 67%
rename from docs/content/advanced/backend/entities/overview.md
rename to docs/content/development/entities/overview.mdx
index 48c7f9f746773..1d3b095ae6ea9 100644
--- a/docs/content/advanced/backend/entities/overview.md
+++ b/docs/content/development/entities/overview.mdx
@@ -1,7 +1,10 @@
---
-description: 'Learn what entities are in the Medusa server. There are entities in the Medusa server, and developers can create custom entities.'
+description: 'Learn what entities are in Medusa. There are entities defined in the Medusa backend, and developers can create custom entities.'
---
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
# Entities
In this document, you'll learn what Entities are in Medusa.
@@ -10,7 +13,7 @@ In this document, you'll learn what Entities are in Medusa.
Entities in medusa represent tables in the database as classes. An example of this would be the `Order` entity which represents the `order` table in the database. Entities provide a uniform way of defining and interacting with data retrieved from the database.
-Aside from Medusa’s core entities, you can also create your own entities to use in your Medusa server. Custom entities are TypeScript or JavaScript files located in the `src/models` directory of your Medusa server.
+Aside from the entities in the Medusa core package, you can also create your own entities to use in your Medusa backend. Custom entities are TypeScript or JavaScript files located in the `src/models` directory of your Medusa backend. These entities are then transpiled to the `dist/models` directory to be used during the backend's runtime.
Entities are TypeScript files and they are based on [Typeorm’s Entities](https://typeorm.io/entities) and use Typeorm decorators.
@@ -65,7 +68,27 @@ If you want to remove a property from the `metadata` object, you can pass the `m
---
-## See Also
-
-- [Create an entity](./index.md)
-- [Entities' reference](../../../references/entities/classes/Address.md)
\ No newline at end of file
+## Custom Development
+
+Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/subscribers/create-subscriber.md b/docs/content/development/events/create-subscriber.md
similarity index 79%
rename from docs/content/advanced/backend/subscribers/create-subscriber.md
rename to docs/content/development/events/create-subscriber.md
index 0dc3e6d8b95d8..5d6f29487205a 100644
--- a/docs/content/advanced/backend/subscribers/create-subscriber.md
+++ b/docs/content/development/events/create-subscriber.md
@@ -1,17 +1,17 @@
---
-description: 'Learn how to create a subscriber in the Medusa server. You can use subscribers to implement functionalities like sending an order confirmation email.'
+description: 'Learn how to create a subscriber in Medusa. You can use subscribers to implement functionalities like sending an order confirmation email.'
addHowToData: true
---
# How to Create a Subscriber
-In this document, you’ll learn how to create a [Subscriber](overview.md) in your Medusa server that listens to events to perform an action.
+In this document, you’ll learn how to create a [Subscriber](./subscribers.mdx) in Medusa that listens to events to perform an action.
## Prerequisites
Medusa's event system works by pushing data to a Queue that each handler then gets notified of. The queuing system is based on Redis, so it's required for subscribers to work.
-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.
+You can learn how to [install Redis](../backend/prepare-environment.mdx#redis) and [configure it with Medusa](../backend/configurations.md#redis) before you get started.
---
@@ -60,7 +60,10 @@ class OrderNotifierSubscriber {
constructor({ productService, eventBusService }) {
this.productService = productService
- eventBusService.subscribe("order.placed", this.handleOrder)
+ eventBusService.subscribe(
+ "order.placed",
+ this.handleOrder
+ )
}
// ...
}
@@ -88,5 +91,4 @@ When using attributes defined in the subscriber, such as the `productService` in
## See Also
-- [Events reference](events-list.md)
-- [Create a Service](../services/create-service)
+- [Create a Plugin](../plugins/create.md)
\ No newline at end of file
diff --git a/docs/content/advanced/backend/subscribers/events-list.md b/docs/content/development/events/events-list.md
similarity index 94%
rename from docs/content/advanced/backend/subscribers/events-list.md
rename to docs/content/development/events/events-list.md
index 165b7184ffac8..5556e0c966cf9 100644
--- a/docs/content/advanced/backend/subscribers/events-list.md
+++ b/docs/content/development/events/events-list.md
@@ -8,7 +8,7 @@ This document details all events in Medusa, when they are triggered, and what da
## Prerequisites
-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.
+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.
---
@@ -1761,7 +1761,7 @@ Triggered when a payment is created.
-The entire payment passed as an object. You can refer to the [Payment entity](../../../references/entities/classes/Payment.md) for an idea of what fields to expect.
+The entire payment passed as an object. You can refer to the [Payment entity](../../references/entities/classes/Payment.md) for an idea of what fields to expect.
|
@@ -1779,7 +1779,7 @@ Triggered when a payment is updated.
-The entire payment passed as an object. You can refer to the [Payment entity](../../../references/entities/classes/Payment.md) for an idea of what fields to expect.
+The entire payment passed as an object. You can refer to the [Payment entity](../../references/entities/classes/Payment.md) for an idea of what fields to expect.
|
@@ -1797,7 +1797,7 @@ Triggered when a payment is captured.
-The entire payment passed as an object. You can refer to the [Payment entity](../../../references/entities/classes/Payment.md) for an idea of what fields to expect.
+The entire payment passed as an object. You can refer to the [Payment entity](../../references/entities/classes/Payment.md) for an idea of what fields to expect.
|
@@ -1815,7 +1815,7 @@ Triggered when the capturing of a payment fails.
-The entire payment passed as an object. You can refer to the [Payment entity](../../../references/entities/classes/Payment.md) for an idea of what fields to expect.
+The entire payment passed as an object. You can refer to the [Payment entity](../../references/entities/classes/Payment.md) for an idea of what fields to expect.
In addition, an error object is passed within the same object as the Payment provider:
@@ -1847,7 +1847,7 @@ Triggered when a refund of a payment is created.
|
-The entire refund passed as an object. You can refer to the [Refund entity](../../../references/entities/classes/Refund.md) for an idea of what fields to expect.
+The entire refund passed as an object. You can refer to the [Refund entity](../../references/entities/classes/Refund.md) for an idea of what fields to expect.
|
@@ -1865,7 +1865,7 @@ Triggered when a payment's refund fails.
-The entire payment passed as an object. You can refer to the [Payment entity](../../../references/entities/classes/Payment.md) for an idea of what fields to expect.
+The entire payment passed as an object. You can refer to the [Payment entity](../../references/entities/classes/Payment.md) for an idea of what fields to expect.
|
@@ -1908,7 +1908,7 @@ Triggered when a payment collection is created.
-The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
+The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
|
@@ -1926,7 +1926,7 @@ Triggered when a payment collection is update.
-The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
+The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
|
@@ -1944,7 +1944,7 @@ Triggered when a payment collection is deleted.
-The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
+The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
|
@@ -1962,7 +1962,7 @@ Triggered when a payment collection is either marked authorized or its payment s
-The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
+The entire payment collection passed as an object. You can refer to the [Payment Collection entity](../../references/entities/classes/PaymentCollection.md) for an idea of what fields to expect.
|
@@ -2029,7 +2029,7 @@ Triggered when a product and data associated with it (options, variant orders, e
-The entire product passed as an object. You can refer to the [Product entity](../../../references/entities/classes/Product.md) for an idea of what fields to expect.
+The entire product passed as an object. You can refer to the [Product entity](../../references/entities/classes/Product.md) for an idea of what fields to expect.
In one case, when the `/admin/products/{id}` endpoint is used to update the product, the payload is an object of the following format:
@@ -2442,17 +2442,6 @@ Object of the following format:
This section holds all events related to sales channels.
-:::note
-
-As of Medusa v1.3.5, Sales Channels are available but guarded by a feature flag. To use Sales Channels either:
-
-1. Enable the `MEDUSA_FF_SALES_CHANNELS` environment variable;
-2. Or enable the `sales_channels` key in the Medusa server's settings.
-
-You can learn more about enabling it in the [feature flags](../feature-flags/toggle.md) documentation.
-
-:::
-
@@ -2969,6 +2958,6 @@ Object of the following format:
## See Also
-- [Events architecture overview](../events/architecture.md)
-- [Use services in subscribers](create-subscriber.md#using-services-in-subscribers)
-- [Create a notification provider](../notification/overview.md)
+- [Events architecture overview](./index.md)
+- [Use services in subscribers](./create-subscriber.md#using-services-in-subscribers)
+- [Create a notification provider](../notification/overview.mdx)
diff --git a/docs/content/advanced/backend/events/architecture.md b/docs/content/development/events/index.md
similarity index 88%
rename from docs/content/advanced/backend/events/architecture.md
rename to docs/content/development/events/index.md
index 8714d1a0f5163..428112c402958 100644
--- a/docs/content/advanced/backend/events/architecture.md
+++ b/docs/content/development/events/index.md
@@ -14,7 +14,7 @@ Those events can be subscribed to using subscribers. When you subscribe to an ev
:::info
-You can learn more about subscribers and their use cases in the [Subscribers](../subscribers/overview.md) documentation.
+You can learn more about subscribers and their use cases in the [Subscribers](./subscribers.mdx) documentation.
:::
@@ -48,7 +48,8 @@ export default class EventBusService {
async emit(
eventName: string,
data: T,
- options: Record & EmitOptions = { attempts: 1 }
+ options: Record &
+ EmitOptions = { attempts: 1 }
): Promise
}
```
@@ -111,7 +112,7 @@ In the constructor of a subscriber, you use the `EventBusService` to subscribe t
:::note
-You can learn more about how to create a subscriber in [this documentation](../subscribers/create-subscriber.md)
+You can learn more about how to create a subscriber in [this documentation](./create-subscriber.md)
:::
@@ -154,7 +155,7 @@ Here's what each of these options mean:
### Note on Subscriber IDs
-If you have more than one handler methods attached to a single event, or if you have multiple server instances running, you must pass a subscriber ID as a third parameter to the `subscribe` method. This allows the `EventBusService` to differentiate between handler methods when retrying a failed one.
+If you have more than one handler methods attached to a single event, or if you have multiple backend instances running, you must pass a subscriber ID as a third parameter to the `subscribe` method. This allows the `EventBusService` to differentiate between handler methods when retrying a failed one.
If a subscriber ID is not passed on subscription, all handler methods are run again. This can lead to data inconsistencies or general unwanted behavior in your system.
@@ -196,7 +197,7 @@ Transactions in Medusa ensure atomicity, consistency, isolation, and durability,
-In many cases, [services](../services/overview.md) typically update resources in the database and emit an event within a transactional operation. To ensure that these events don't cause data inconsistencies (for example, a plugin subscribes to an event to contact a third-party service, but the transaction fails) the concept of a staged job is introduced.
+In many cases, [services](../services/overview.mdx) typically update resources in the database and emit an event within a transactional operation. To ensure that these events don't cause data inconsistencies (for example, a plugin subscribes to an event to contact a third-party service, but the transaction fails) the concept of a staged job is introduced.
Instead of events being processed immediately, they're stored in the database as a staged job until they're ready. In other words, until the transaction has succeeded.
@@ -222,6 +223,5 @@ This pattern is heavily inspired by the [Transactionally-staged Job Drain descri
## See Also
-- [Events reference](../subscribers/events-list.md)
-- [Subscribers overview](../subscribers/overview.md)
-- [How to create a subscriber](../subscribers/create-subscriber.md)
\ No newline at end of file
+- [Events reference](./events-list.md)
+- [Create a subscriber](./create-subscriber.md)
\ No newline at end of file
diff --git a/docs/content/advanced/backend/subscribers/overview.md b/docs/content/development/events/subscribers.mdx
similarity index 75%
rename from docs/content/advanced/backend/subscribers/overview.md
rename to docs/content/development/events/subscribers.mdx
index 97b4355981cf3..5d8dec00f48e7 100644
--- a/docs/content/advanced/backend/subscribers/overview.md
+++ b/docs/content/development/events/subscribers.mdx
@@ -1,7 +1,10 @@
---
-description: 'Learn what subscribers are in the Medusa server. Subscribers are used to listen to triggered events to perform an action.'
+description: 'Learn what subscribers are in Medusa. Subscribers are used to listen to triggered events to perform an action.'
---
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
# Subscribers
In this document, you'll learn what Subscribers are in Medusa.
@@ -12,7 +15,7 @@ In Medusa, there are events that are emitted when a certain action occurs. For e
The purpose of these events is to allow other parts of the platform, or third-party integrations, to listen to those events and perform a certain action. That is done by creating subscribers.
-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.
+Medusa's queuing and events system is handled by Redis. So, you must have [Redis configured](../backend/prepare-environment.mdx#redis) on your backend to use subscribers.
---
@@ -36,8 +39,17 @@ Subscribers are useful in many use cases, including:
---
-## See Also
+## Custom Development
+
+Developers can create custom subscribers in the Medusa backend, a plugin, or in a Commerce Module.
-- [Create a Subscriber](create-subscriber.md).
-- [Events architecture overview](../events/architecture.md)
-- [Events reference](events-list.md).
+
diff --git a/docs/content/development/feature-flags/overview.mdx b/docs/content/development/feature-flags/overview.mdx
new file mode 100644
index 0000000000000..f44e290eb3a6f
--- /dev/null
+++ b/docs/content/development/feature-flags/overview.mdx
@@ -0,0 +1,28 @@
+---
+description: "Learn what feature flags in Medusa. Feature flags are used in Medusa to guard beta features that aren’t ready for live and production applications."
+---
+
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
+# Feature Flags
+
+In this document, you’ll learn what feature flags in Medusa.
+
+## Introduction
+
+Feature flags are used in Medusa to guard beta features that aren’t ready for live and production applications. This allows the Medusa team to keep publishing releases more frequently, while also working on necessary future features behind the scenes. To use these beta features, you must enable their feature flags.
+
+If a feature is guarded by a flag, entities, migrations, endpoints, and other resources associated with that feature are guarded by that flag as well. So, these resources will only be available to use in Medusa if you have enabled the associated feature flag.
+
+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.
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/feature-flags/toggle.md b/docs/content/development/feature-flags/toggle.md
similarity index 55%
rename from docs/content/advanced/backend/feature-flags/toggle.md
rename to docs/content/development/feature-flags/toggle.md
index ea371b9a78fa8..92133e001a3e7 100644
--- a/docs/content/advanced/backend/feature-flags/toggle.md
+++ b/docs/content/development/feature-flags/toggle.md
@@ -1,23 +1,11 @@
---
-description: 'Learn how to toggle feature flags in the Medusa server. This guide explains the steps required to toggle a feature flag.'
+description: 'Learn how to toggle feature flags in Medusa. This guide explains the steps required to toggle a feature flag.'
addHowToData: true
---
# How to Toggle Feature Flags
-In this document, you’ll learn about what feature flags are and how to toggle them.
-
-## Overview
-
-Feature flags are used in Medusa to guard beta features that aren’t ready for live and production servers. This allows the Medusa team to keep publishing releases more frequently, while also working on necessary future features behind the scenes.
-
-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.
+In this document, you’ll learn about how to toggle feature flags.
:::info
@@ -25,8 +13,6 @@ If a feature flag is enabled/disabled by default, you don’t need to manually e
:::
----
-
## Enable Feature Flags
:::caution
@@ -47,9 +33,9 @@ For example, to enable the Tax-Inclusive Pricing beta feature, add the following
MEDUSA_FF_TAX_INCLUSIVE_PRICING=true
```
-### Method Two: Using Server Settings
+### Method Two: Using Backend Configurations
-You can enable a feature by using the server settings in `medusa-config.js`. You can find [a feature flag’s key in the loader file](https://github.com/medusajs/medusa/tree/master/packages/medusa/src/loaders/feature-flags) it’s defined in. It is defined under the property `key` in the exported object.
+You can enable a feature by using the backend configurations in `medusa-config.js`. You can find [a feature flag’s key in the loader file](https://github.com/medusajs/medusa/tree/master/packages/medusa/src/loaders/feature-flags) it’s defined in. It is defined under the property `key` in the exported object.
For example, to enable the Tax-Inclusive Pricing beta feature, add the following to the exported object in `medusa-config.js`:
@@ -64,9 +50,9 @@ module.exports = {
### Note About Precedence
-The environment variable’s value has higher precedence over the server settings. So, if you use both these methods on your server, the value of the environment variable will be used.
+The environment variable’s value has higher precedence over the backend configurations. So, if you use both these methods on your backend, the value of the environment variable will be used.
-For example, if the value of the environment variable is set to `false`, but the value of the feature flag in the server settings is set to `true`, the feature flag will take the value of the environment variable and will be disabled.
+For example, if the value of the environment variable is set to `false`, but the value of the feature flag in the backend configurations is set to `true`, the feature flag will take the value of the environment variable and will be disabled.
### Running Migrations
@@ -86,7 +72,7 @@ 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`.
+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 backend configurations to `false`.
Once you disable a feature flag, all endpoints, entities, services, or other related classes and functionalities are disabled.
@@ -94,11 +80,4 @@ Once you disable a feature flag, all endpoints, entities, services, or other rel
If you had the feature flag previously enabled, and you want to disable this feature flag completely, you might need to revert the migrations you ran when you enabled it.
-You can follow [this documentation to learn how to revert the last migration you ran](https://docs.medusajs.com/cli/reference#migrations).
-
----
-
-## See Also
-
-- [Migrations Overview](../migrations/overview.md).
-- [Configure your Medusa server](../../../usage/configurations.md).
+You can follow [this documentation to learn how to revert the last migration you ran](../../cli/reference.md#migrations).
\ No newline at end of file
diff --git a/docs/content/development/file-service/overview.mdx b/docs/content/development/file-service/overview.mdx
new file mode 100644
index 0000000000000..4ea5b6b05bd2d
--- /dev/null
+++ b/docs/content/development/file-service/overview.mdx
@@ -0,0 +1,35 @@
+---
+description: "Learn what a file service is in Medusa. A file service defines how files are stored in the Medusa Backend."
+---
+
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
+# File Service
+
+In this document, you’ll learn what a file service is in Medusa.
+
+## Introduction
+
+A file service defines how files are stored in the Medusa Backend. Those files include products’ images and files used to import or export data.
+
+Medusa Backend includes a default file service that acts as a placeholder, but does not actually perform any storage functionalities. So, you must either install one of the [existing file-service plugins](../../plugins/file-service/index.mdx), such as [MinIO](../../plugins/file-service/minio.md) or [S3](../../plugins/file-service/s3.md), or create your own file service if you want to utilize storage functionalities.
+
+A file service is a TypeScript or JavaScript class that extends the `AbstractFileService` class from the core `@medusajs/medusa` package. By extending this class, the file service must implement the necessary methods that take care of general upload and download functionalities. The Medusa Backend then uses these methods when necessary, for example, when a product image is uploaded.
+
+---
+
+## Custom Development
+
+Developers can create a custom file service with the desired functionality directly within the Medusa Core, in a plugin, or in a Commerce Module.
+
+
\ No newline at end of file
diff --git a/docs/content/development/fundamentals/architecture-overview.md b/docs/content/development/fundamentals/architecture-overview.md
new file mode 100644
index 0000000000000..a710d5a4004f7
--- /dev/null
+++ b/docs/content/development/fundamentals/architecture-overview.md
@@ -0,0 +1,27 @@
+---
+description: "Learn about Medusa's architecture and get a general overview of how all different tools work together."
+---
+
+# Medusa Architecture Overview
+
+In this document, you'll get an overview of Medusa's architecture to better understand how all resources and tools work together.
+
+## Architecture Overview
+
+Medusa's core package `@medusajs/medusa` is a Node.js backend built on top of [Express](https://expressjs.com/). It combines all the [**Commerce Modules**](../../modules/overview.mdx) that Medusa provides. Commerce Modules are ecommerce features that can be used as building blocks in an ecommerce ecosystem. Product is an example of a Commerce Module.
+
+
+
+The backend connects to a **database**, such as [PostgreSQL](https://www.postgresql.org/), to store the ecommerce store’s data. The tables in that database are represented by [**Entities**](../entities/overview.mdx), built on top of [Typeorm](https://typeorm.io/). Entities can also be reflected in the database using [**Migrations**](../entities/migrations/overview.mdx).
+
+The retrieval, manipulation, and other utility methods related to that entity are created inside a [**Service**](../services/overview.mdx). Services are TypeScript or JavaScript classes that, similar along with other resources, can be accessed throughout the Medusa backend through [**dependency injection**](./dependency-injection.md).
+
+The backend does not have any tightly-coupled frontend. Instead, it exposes [**Endpoints**](../endpoints/overview.mdx) which are REST APIs that frontends such as an admin or a storefront can use to communicate with the backend. Endpoints are [Express routes](https://expressjs.com/en/guide/routing.html).
+
+Medusa also uses an [**Events Architecture**](../events/index.md) to trigger and handle events. Events are triggered when a specific action occurs, such as when an order is placed. To manage this events system, Medusa connects to a service that implements a pub/sub model, such as [Redis](https://redis.io/).
+
+Events can be handled using [**Subscribers**](../events/subscribers.mdx). Subscribers are TypeScript or JavaScript classes that add their methods as handlers for specific events. These handler methods are only executed when an event is triggered.
+
+You can create any of the resources in the backend’s architecture, such as entities, endpoints, services, and more, as part of your custom development without directly modifying the backend itself. The Medusa backend uses **loaders** to load the backend’s resources, as well as your custom resources and resources in [**Plugins**](../plugins/overview.mdx).
+
+You can package your customizations into Plugins to reuse them in different Medusa backends or publish them for others to use. You can also install existing plugins into your Medusa backend.
\ No newline at end of file
diff --git a/docs/content/advanced/backend/dependency-container/index.md b/docs/content/development/fundamentals/dependency-injection.md
similarity index 89%
rename from docs/content/advanced/backend/dependency-container/index.md
rename to docs/content/development/fundamentals/dependency-injection.md
index 379821d342ac7..b33267448f098 100644
--- a/docs/content/advanced/backend/dependency-container/index.md
+++ b/docs/content/development/fundamentals/dependency-injection.md
@@ -2,9 +2,9 @@
description: 'Learn what the dependency container is and how to use it in Medusa. Learn also what dependency injection is, and what the resources regsitered and their names are.'
---
-# Dependency Container
+# Dependency Injection
-In this document, you’ll learn what the dependency container is and how you can use it in Medusa.
+In this document, you’ll learn what the dependency injection is and how you can use it in Medusa.
## Introduction
@@ -16,25 +16,25 @@ Generally, all resources are registered in a container. Then, whenever a class d
### Medusa’s Dependency Container
-Medusa uses a dependency container to register essential resources of your server. You can then access these resources in classes and endpoints using the dependency container.
+Medusa uses a dependency container to register essential resources of the backend. You can then access these resources in classes and endpoints using the dependency container.
-For example, if you create a custom service, you can access any other service registered in Medusa in your service’s constructor. That includes Medusa’s core services, services defined in plugins, or other services that you create on your server.
+For example, if you create a custom service, you can access any other service registered in Medusa in your service’s constructor. That includes Medusa’s core services, services defined in plugins, or other services that you create on your backend.
-You can load more than services in your Medusa server. You can load the Entity Manager, logger instance, and much more.
+You can load more than services in your Medusa backend. You can load the Entity Manager, logger instance, and much more.
### MedusaContainer
To manage dependency injections, Medusa uses [Awilix](https://github.com/jeffijoe/awilix). Awilix is an NPM package that implements dependency injection in Node.js projects.
-When you run the Medusa server, a container of the type `MedusaContainer` is created. This type extends the [AwilixContainer](https://github.com/jeffijoe/awilix#the-awilixcontainer-object) object.
+When you run the Medusa backend, a container of the type `MedusaContainer` is created. This type extends the [AwilixContainer](https://github.com/jeffijoe/awilix#the-awilixcontainer-object) object.
-The server then registers all important resources in the container, which makes them accessible in classes and endpoints.
+The backend 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:
+The Medusa backend scans the core Medusa package, plugins, and your files in the `dist` directory and registers the following resources:
:::note
@@ -72,7 +72,7 @@ Configurations
|
-The configurations that are exported from medusa-config.js.
+The configurations that are exported from `medusa-config.js`.
|
@@ -560,7 +560,7 @@ Its camel-case name.
## Loading Resources
-This section covers how to load resources that the Medusa server registers when it starts running.
+This section covers how to load resources that the Medusa backend registers when it starts running.
### In Endpoints
@@ -596,5 +596,5 @@ class OrderSubscriber {
## See Also
-- [Create services](../services/create-service.md).
-- [Create subscribers](../subscribers/create-subscriber.md).
+- [Create services](../services/create-service.md)
+- [Create subscribers](../events/create-subscriber.md)
diff --git a/docs/content/usage/local-development.md b/docs/content/development/fundamentals/local-development.md
similarity index 86%
rename from docs/content/usage/local-development.md
rename to docs/content/development/fundamentals/local-development.md
index f47a2b2551e1a..f379d3a290656 100644
--- a/docs/content/usage/local-development.md
+++ b/docs/content/development/fundamentals/local-development.md
@@ -2,7 +2,7 @@
description: 'Learn how to perform local development in the Medusa monorepo. This includes how to use the dev CLI tool and perform unit, integration, and plugin tests.'
---
-# Local Development of Medusa Server and Monorepo
+# Local Development of Medusa Backend and Monorepo
In this document, you’ll learn how to customize Medusa’s core and run tests.
@@ -10,11 +10,11 @@ In this document, you’ll learn how to customize Medusa’s core and run tests.
As an open-source platform, Medusa’s core can be completely customized.
-Whether you want to implement something differently, introduce a new future as part of Medusa’s core or any of the other packages, or contribute to Medusa, this guide helps you learn how to run Medusa’s integration tests, as well as test your own Medusa core in a local server.
+Whether you want to implement something differently, introduce a new future as part of Medusa’s core or any of the other packages, or contribute to Medusa, this guide helps you learn how to run Medusa’s integration tests, as well as test your own Medusa core in a local backend.
### Medusa Repository Overview
-[Medusa’s repository on GitHub](https://github.com/medusajs/medusa) includes all packages related to Medusa under the [`packages` directory](https://github.com/medusajs/medusa/tree/master/packages). This includes the [core Medusa server](https://github.com/medusajs/medusa/tree/master/packages/medusa), the [JS Client](https://github.com/medusajs/medusa/tree/master/packages/medusa-js), the CLI tools, and much more.
+[Medusa’s repository on GitHub](https://github.com/medusajs/medusa) includes all packages related to Medusa under the [`packages` directory](https://github.com/medusajs/medusa/tree/master/packages). This includes the [core Medusa package](https://github.com/medusajs/medusa/tree/master/packages/medusa), the [JS Client](https://github.com/medusajs/medusa/tree/master/packages/medusa-js), the CLI tools, and much more.
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.
@@ -114,11 +114,11 @@ yarn test:integration:plugins
---
-## Test in a Local Server
+## Test in a Local Backend
-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.
+Using Medusa’s dev CLI tool, you can test any changes you make to Medusa’s packages in a local backend installation. This eliminates the need to publish these packages on NPM publicly to be able to use them.
-Medusa’s dev CLI tool scans and finds the Medusa packages used in your Medusa server. Then, it copies the files of these packages from the `packages` directory in the Medusa repository into the `node_modules` directory of your Medusa server.
+Medusa’s dev CLI tool scans and finds the Medusa packages used in your Medusa backend. Then, it copies the files of these packages from the `packages` directory in the Medusa repository into the `node_modules` directory of your Medusa backend.
:::info
@@ -126,14 +126,14 @@ Medusa’s Dev CLI tool uses the [path you specified earlier](#set-the-location-
:::
-### Copy Files to Local Server
+### Copy Files to Local Backend
-To test in a local server:
+To test in a local backend:
-1. Change to the directory of the server you want to test your changes in:
+1. Change to the directory of the backend you want to test your changes in:
```bash
-cd medusa-server
+cd medusa-backend
```
2\. Run the following command to copy the files from the `packages` directory of your Medusa repository into `node_modules`:
@@ -148,7 +148,7 @@ By default, Medusa’s dev CLI runs in watch mode. So, it copies the files when
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.
+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 backend.
For example, if you're making changes in the `medusa` package, run the following command inside the directory of the `medusa` package:
@@ -190,5 +190,5 @@ medusa-dev --packages @medusajs/medusa-cli medusa-file-minio
## See Also
-- [Create a Plugin](../advanced/backend/plugins/create.md)
+- [Create a Plugin](../plugins/create.md)
- [Contribution Guidelines](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md)
diff --git a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md b/docs/content/development/notification/create-notification-provider.md
similarity index 73%
rename from docs/content/advanced/backend/notification/how-to-create-notification-provider.md
rename to docs/content/development/notification/create-notification-provider.md
index fc0c51d30326c..c072f30c475d2 100644
--- a/docs/content/advanced/backend/notification/how-to-create-notification-provider.md
+++ b/docs/content/development/notification/create-notification-provider.md
@@ -1,23 +1,23 @@
---
-description: 'Learn how to create a notification provider in the Medusa server. This guide explains the different methods available in a Notification provider.'
+description: 'Learn how to create a notification provider in Medusa. This guide explains the different methods available in a Notification provider.'
addHowToData: true
---
# How to Create a Notification Provider
-In this document, you’ll learn how to add a Notification Provider to your Medusa server.
+In this document, you’ll learn how to create a Notification Provider in Medusa.
:::note
-If you’re unfamiliar with the Notification architecture in Medusa, it is recommended to check out the [architecture overview](overview.md) first.
+If you’re unfamiliar with the Notification architecture in Medusa, it is recommended to check out the [architecture overview](./overview.mdx) first.
:::
## Prerequisites
-Before you start creating a Notification Provider, you need to install a [Medusa server](../../../quickstart/quick-start.mdx).
+Before you start creating a Notification Provider, you need to either install a [Medusa backend](../backend/install.mdx), or create it in a [plugin](../plugins/overview.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).
+You also need to [setup Redis](../backend/prepare-environment.mdx#redis) and [configure it with the Medusa backend](../backend/configurations.md#redis) to test out the Notification provider.
---
@@ -96,15 +96,15 @@ You can use the `constructor` of your Notification Provider to have access to
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the Service.
-Additionally, if you’re creating your Notification 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.
+Additionally, if you’re creating your Notification Provider as an external plugin to be installed on any Medusa backend 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.
:::info
-You can learn more about plugins and how to create them in the [Plugins](../plugins/overview.md) documentation.
+You can learn more about plugins and how to create them in the [Plugins](../plugins/overview.mdx) documentation.
:::
-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:
+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 {
@@ -132,7 +132,7 @@ class EmailSenderService extends AbstractNotificationService {
### sendNotification
-When an event is triggered that your Notification Provider is registered as a handler for, the [`NotificationService`](../../../references/services/classes/NotificationService.md) in Medusa’s core will execute the `sendNotification` method of your Notification Provider.
+When an event is triggered that your Notification Provider is registered as a handler for, the [`NotificationService`](../../references/services/classes/NotificationService.md) in Medusa’s core will execute the `sendNotification` method of your Notification Provider.
In this method, you can perform the necessary operation to send the Notification. Following the example above, you can send an email to the customer when they place an order.
@@ -140,11 +140,11 @@ This method receives three parameters:
1. `eventName`: This is the name of the event that was triggered. For example, `order.placed`.
2. `eventData`: This is the data payload of the event that was triggered. For example, if the `order.placed` event is triggered, the `eventData` object contains the property `id` which is the ID of the order that was placed.
-3. `attachmentGenerator`: If you’ve previously attached a generator to the `NotificationService` using the [`registerAttachmentGenerator`](../../../references/services/classes/NotificationService.md#registerattachmentgenerator) method, you have access to it here. You can use the `attachmentGenerator` to generate on-demand invoices or other documents. The default value of this parameter is null.
+3. `attachmentGenerator`: If you’ve previously attached a generator to the `NotificationService` using the [`registerAttachmentGenerator`](../../references/services/classes/NotificationService.md#registerattachmentgenerator) method, you have access to it here. You can use the `attachmentGenerator` to generate on-demand invoices or other documents. The default value of this parameter is null.
:::info
-You can learn more about what events are triggered in Medusa and their data payload in the [Events List](../subscribers/events-list.md) documentation.
+You can learn more about what events are triggered in Medusa and their data payload in the [Events List](../events/events-list.md) documentation.
:::
@@ -196,19 +196,19 @@ Finally, you return an object with the `to` property set to the customer email a
:::note
-The `to` and `data` properties are used in the `NotificationService` in Medusa’s core to create a new `Notification` record in the database. You can learn more about the `Notification` entity in the [Architecture Overview](overview.md#notification-entity-overview) documentation.
+The `to` and `data` properties are used in the `NotificationService` in Medusa’s core to create a new `Notification` record in the database. You can learn more about the `Notification` entity in the [Architecture Overview](./overview.mdx#notification-entity-overview) documentation.
:::
### resendNotification
-Using the [Resend Notification endpoint](https://docs.medusajs.com/api/admin/#tag/Notification/operation/PostNotificationsNotificationResend), an admin user can resend a Notification to the customer. The [`NotificationService`](../../../references/services/classes/NotificationService.md) in Medusa’s core then executes the `resendNotification` method in your Notification Provider.
+Using the [Resend Notification endpoint](/api/admin/#tag/Notification/operation/PostNotificationsNotificationResend), an admin user can resend a Notification to the customer. The [`NotificationService`](../../references/services/classes/NotificationService.md) in Medusa’s core then executes the `resendNotification` method in your Notification Provider.
This method receives three parameters:
-1. `notification`: This is the original Notification record that was created after you sent the notification with `sendNotification`. You can get an overview of the entity and its attributes in the [architecture overview](overview.md#notification-entity-overview), but most notably it includes the `to` and `data` attributes which are populated originally using the `to` and `data` properties of the object you return in `sendNotification`.
+1. `notification`: This is the original Notification record that was created after you sent the notification with `sendNotification`. You can get an overview of the entity and its attributes in the [architecture overview](./overview.mdx#notification-entity-overview), but most notably it includes the `to` and `data` attributes which are populated originally using the `to` and `data` properties of the object you return in `sendNotification`.
2. `config`: In the Resend Notification endpoint you may specify an alternative receiver of the notification using the `to` request body parameter. For example, you may want to resend the order confirmation email to a different email. If that’s the case, you have access to it in the `config` parameter object. Otherwise, `config` will be an empty object.
-3. `attachmentGenerator`: If you’ve previously attached a generator to the Notification Service using the [`registerAttachmentGenerator`](../../../references/services/classes/NotificationService.md#registerattachmentgenerator) method, you have access to it here. You can use the `attachmentGenerator` to generate on-demand invoices or other documents. The default value of this parameter is null.
+3. `attachmentGenerator`: If you’ve previously attached a generator to the Notification Service using the [`registerAttachmentGenerator`](../../references/services/classes/NotificationService.md#registerattachmentgenerator) method, you have access to it here. You can use the `attachmentGenerator` to generate on-demand invoices or other documents. The default value of this parameter is null.
Similarly to the `sendNotification` method, this method must return an object containing two properties:
@@ -229,7 +229,7 @@ class EmailSenderService extends AbstractNotificationService {
status: string;
data: Record;
}> {
- // check if the receiver of the notification should be changed
+ // check if the receiver should be changed
const to: string = config.to ? config.to : notification.to
// TODO resend the notification using the same data
@@ -239,7 +239,7 @@ class EmailSenderService extends AbstractNotificationService {
return {
to,
status: "done",
- data: notification.data, // you can also make changes to the data
+ data: notification.data, // make changes to the data
}
}
}
@@ -253,7 +253,7 @@ Finally, you return an object with the `to` property set to the email (either ne
:::note
-The `to` and `data` properties are used in the `NotificationService` in Medusa’s core to create a new `Notification` record in the database. No changes are made to the original `Notification` record created after the `sendNotification` method. This new record is associated with the original `Notification` record using the `parent_id` attribute in the entity. You can learn more about the `Notification` entity in the [Architecture Overview](overview.md#notification-entity-overview) documentation.
+The `to` and `data` properties are used in the `NotificationService` in Medusa’s core to create a new `Notification` record in the database. No changes are made to the original `Notification` record created after the `sendNotification` method. This new record is associated with the original `Notification` record using the `parent_id` attribute in the entity. You can learn more about the `Notification` entity in the [Architecture Overview](./overview.mdx#notification-entity-overview) documentation.
:::
@@ -265,7 +265,7 @@ After creating your Notification Provider Service, you must create a Subscriber
:::note
-This section will not cover the basics of Subscribers. You can read the [Subscribers](../subscribers/create-subscriber.md) documentation to learn more about them and how to create them.
+This section will not cover the basics of Subscribers. You can read the [Subscribers](../events/create-subscriber.md) documentation to learn more about them and how to create them.
:::
@@ -274,7 +274,10 @@ 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"
+ )
}
// ...
}
@@ -294,19 +297,19 @@ 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.
+Make sure you've configured Redis with your Medusa backend as explained in the [Prerequisites](#prerequisites) section and that the Redis service is running.
-Then, start by running your Medusa server:
+Then, start by running your Medusa backend:
```bash npm2yarn
npm run start
```
-Then, place an order either using the [REST APIs](https://docs.medusajs.com/api/store) or using the storefront.
+Then, place an order either using the [REST APIs](/api/store) or using the storefront.
:::tip
-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.
+If you don’t have a storefront installed you can get started with the [Next.js](../../starters/nextjs-medusa-starter.mdx) starter storefront in minutes.
:::
@@ -316,17 +319,17 @@ After placing an order, you can see in your console the message “Notification
## 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.
+To test resending a notification, first, retrieve the ID of the notification you just sent using the [List Notifications admin endpoint](/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.
:::tip
-You must be authenticated as an admin user before sending this request. You can use the [Authenticate a User](https://docs.medusajs.com/api/admin) endpoint to get authenticated.
+You must be authenticated as an admin user before sending this request. You can use the [Authenticate a User](/api/admin) endpoint to get authenticated.
:::
-Then, send a request to the [Resend Notification](https://docs.medusajs.com/api/admin/#tag/Notification/operation/PostNotificationsNotificationResend) endpoint using the ID retrieved from the previous request. You can pass the `to` parameter in the body to change the receiver of the notification. You should see the message “Notification Resent” in your console and if you implemented your own logic for resending the notification it will be resent.
+Then, send a request to the [Resend Notification](/api/admin/#tag/Notification/operation/PostNotificationsNotificationResend) endpoint using the ID retrieved from the previous request. You can pass the `to` parameter in the body to change the receiver of the notification. You should see the message “Notification Resent” in your console and if you implemented your own logic for resending the notification it will be resent.
@@ -336,8 +339,4 @@ This request returns the same notification object as the List Notifications endp
## 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/development/notification/overview.mdx
similarity index 74%
rename from docs/content/advanced/backend/notification/overview.md
rename to docs/content/development/notification/overview.mdx
index 3481c19ed843c..486551bf401b1 100644
--- a/docs/content/advanced/backend/notification/overview.md
+++ b/docs/content/development/notification/overview.mdx
@@ -2,6 +2,9 @@
description: 'Learn about the Notificaiton architecture in Medusa and the automation flow. The Notification Architecture is made up of the Notification Provider and Notification.'
---
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
# Notification Architecture Overview
This document gives an overview of the notification architecture and how it works.
@@ -22,11 +25,11 @@ An example of a notification provider is SendGrid. When an order is placed, the
### How Notification Provider is Created
-A Notification Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the [`NotificationService`](../../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.md), or it can be created just as a Service file in your Medusa server.
+A Notification Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the [`NotificationService`](../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend.
As a developer, you mainly work with the Notification Provider when integrating a third-party service that handles notifications in Medusa.
-When you run your Medusa server, the Notification Provider is registered on your server if it isn’t already. This means that it will be inserted into the `notification_provider` table in your database.
+When you run your Medusa backend, the Notification Provider is registered in your backend. If it's a new Notification Provider, it will be inserted into the `notification_provider` table in your database.
### NotificationProvider Entity Overview
@@ -55,7 +58,7 @@ A Notification also represents a resent notification. So, when a notification is
### Notification Entity Overview
-The two most important properties in the [`Notification`](../../../references/entities/classes/Notification.md) entity are the `to` and `data` properties.
+The two most important properties in the [`Notification`](../../references/entities/classes/Notification.md) entity are the `to` and `data` properties.
The `to` property is a string that represents the receiver of the Notification. For example, if the Notification was sent to an email address, the `to` property holds the email address the Notification was sent to.
@@ -83,17 +86,24 @@ With Medusa you can create notifications as a reaction to a wide spectrum of eve
An example of a flow that can be implemented using Medusa's Notification API is automated return flows:
-- A customer requests a return by sending a `POST` request to the `/store/returns` endpoint.
-- The Notification Provider listens to the `order.return_requested` event and sends an email to the customer with a return invoice and return label generated by the Fulfillment Provider.
-- 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.
+- A customer requests a return by sending a `POST` request to the `/store/returns` endpoint.
+- The Notification Provider listens to the `order.return_requested` event and sends an email to the customer with a return invoice and return label generated by the Fulfillment Provider.
+- 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.
---
-## See Also
+## Custom Development
+
+Developers can create custom notification providers in the Medusa backend, a plugin, or in a Commerce Module.
-- [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)
+
\ No newline at end of file
diff --git a/docs/content/development/overview.mdx b/docs/content/development/overview.mdx
new file mode 100644
index 0000000000000..843d3019bacef
--- /dev/null
+++ b/docs/content/development/overview.mdx
@@ -0,0 +1,203 @@
+---
+description: "Learn about development with Medusa, fundamental concepts, and more."
+hide_table_of_contents: true
+---
+
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
+# Medusa Development
+
+This part of the documentation provides you with the fundamental concepts and guides that can help you build and customize commerce applications with Medusa.
+
+## Introduction
+
+Medusa is a set of tools that developers can use to build digital commerce applications. Whether you want to offer unique customer experiences, create powerful automations, or build rich commerce applications like marketplaces, Medusa provides all the necessary tools.
+
+Other ecommerce platforms offer a finite set of features accessible through an API. Medusa is different because it provides building blocks for businesses and developers to build commerce features. This means that you can extend your commerce API for your exact needs.
+
+Medusa's building blocks ship as NPM packages of the following types:
+
+- [Commerce Modules](../modules/overview.mdx), which are isolated commerce logic for different domains. For example, an Inventory Module.
+- A core package responsible for orchestrating the different commerce modules and exposing REST APIs.
+
+---
+
+## How Does Medusa Work
+
+The core package is the NPM package `@medusajs/medusa`. It's a Node.js server built with Express and other tools that offer functionalities for managing events, caching, job queues, and more.
+
+The core package has two main objectives.
+
+### Orchestrate Commerce Modules
+
+When you build a commerce application with Medusa, you’ll typically interact with more than one commerce module. The core package manages relationships between modules, and forwarding calls to modules at the right time during business logic execution.
+
+For example, imagine an Inventory module that contains lightweight logic to increment and decrement stock levels for a Stock-Keeping Unit (SKU). In a commerce application, you typically want to associate the stock levels with a specific product. Medusa offers both an Inventory module and a Product module, and the core package creates associations between these modules and executing the related business logic. So, the core package contains code similar to this:
+
+```ts
+function handler(req, res) {
+ // ...
+
+ // associate a product with an inventory item
+ const product = await productService.create(data)
+ const inventoryItem = await inventoryService.create(
+ inventoryData
+ )
+ await productVariantInventoryService.associate(
+ product.id,
+ inventoryItem.id
+ )
+
+ // ...
+}
+```
+
+### Expose REST APIs
+
+The goal of orchestrating the modules is to expose an API that client applications, like websites or apps, can consume. By default, Medusa’s core package exposes a REST API that offers commerce functionalities similar to what other platforms give you.
+
+The core package also holds the logic that allows developers to extend and add custom endpoints, among other available customizations.
+
+---
+
+## Backend First Steps
+
+
+
+---
+
+## Understanding Fundamental Concepts
+
+These concepts will guide you through your development and building customization with Medusa.
+
+
+
+---
+
+## Medusa Use Cases
+
+To better understand how you can use Medusa, here are some common use cases that Medusa is the ideal solution for.
+
+### Ecommerce Building Blocks
+
+Developers can set up the core package and handpick the Commerce Modules they want to use. This gives them great flexibility in choosing the features they want to provide in their ecommerce store, while utilizing the powerful architecture in the core package.
+
+
+
+Developers can modify and tailor the modules that Medusa offers to their use case. They can also create custom Modules to implement new features. All these modules become building blocks that shape their ecommerce system.
+
+### Medusa in Microservices Architectures
+
+Medusa’s Commerce Modules can be used in isolation from the core package and within a larger ecosystem. For example, you can use Medusa’s Cart module within a blog to allow readers to buy merch.
+
+
+
+Developers can benefit from Medusa’s Modules that provide essential ecommerce features while maintaining the ecommerce ecosystem of their choice. Commerce Modules can be installed in your setup as NPM packages.
+
+### Vertical Ecommerce Platforms
+
+A Vertical Ecommerce Platform is a platform that provides features and functionalities specialized for a type of business sector. For example, a platform for pharmaceuticals.
+
+Developers can use Medusa to build a vertical ecommerce platform as it provides the stepping stones that eliminate the need to reinvent the wheel for basic ecommerce features, but are customizable enough to be changed for their use case.
+
+### Out-of-Box APIs
+
+Since Medusa’s Commerce Modules are NPM packages, they can be installed and used in any JavaScript project.
+
+By installing a Module in your project and expose its APIs based on the framework you’re using, you can get ecommerce REST APIs right from your frontend framework without having to create a separate project.
+
+### Full-Fledged Ecommerce System
+
+Developers can use Medusa’s toolkit to create their ecommerce system. With the use of the [create-medusa-app](../create-medusa-app.mdx) command, developers can set up a Medusa Backend, Medusa admin, and a storefront.
+
+
+
+Developers can still benefit from customization opportunities here that Medusa provides. This includes creating resources such as endpoints and services, creating plugins, integrating third-party services, create a custom storefront, and more.
+
+### Your Own Use Case
+
+Medusa’s vision is to allow developers to build anything they want using it. There are no limitations to what you can build and the ideas you can come up with. If you have an idea, you can use Medusa’s tools to start building it.
\ No newline at end of file
diff --git a/docs/content/advanced/backend/plugins/create.md b/docs/content/development/plugins/create.md
similarity index 76%
rename from docs/content/advanced/backend/plugins/create.md
rename to docs/content/development/plugins/create.md
index f70ff779a6ec7..50f58d6ce4f49 100644
--- a/docs/content/advanced/backend/plugins/create.md
+++ b/docs/content/development/plugins/create.md
@@ -5,7 +5,7 @@ addHowToData: true
# How to Create a Plugin
-In this document, you’ll learn how to create a plugin and some tips for develoment. If you’re interested to learn more about what plugins are and where to find available official and community plugins, check out the [overview document](overview.md).
+In this document, you’ll learn how to create a plugin and some tips for develoment. If you’re interested to learn more about what plugins are and where to find available official and community plugins, check out the [overview document](./overview.mdx).
## Prerequisites
@@ -17,7 +17,7 @@ npm install @medusajs/medusa-cli -g
:::note
-If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../../troubleshooting/cli-installation-errors.mdx).
+If you run into any errors while installing the CLI tool, check out the [troubleshooting guide](../../troubleshooting/cli-installation-errors.mdx).
:::
@@ -41,7 +41,7 @@ By convention, all plugin names start with `medusa` followed by a descriptive na
### Change Dependencies
-A basic Medusa server installed with the `medusa new` command has dependencies similar to this:
+A basic Medusa backend installed with the `medusa new` command has dependencies similar to this:
```json title=package.json
"dependencies": {
@@ -61,7 +61,7 @@ A basic Medusa server installed with the `medusa new` command has dependencies s
}
```
-For a plugin, some dependencies are not necessary. You can remove the packages `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa server, but not for a plugin.
+For a plugin, some dependencies are not necessary. You can remove the packages `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa backend, but not for a plugin.
Additionally, you can remove `@medusajs/medusa-cli` as you don’t need to use the Medusa CLI while developing a plugin.
@@ -102,11 +102,11 @@ Now, You can start developing your plugin. This can include adding services, end
While developing your plugin, you can create your TypeScript or JavaScript files under the `src` directory. This includes creating services, endpoints, migrations, etc...
-However, before you test the changes on a Medusa server or publish your plugin, you must transpile your files, which moves them into the root of your plugin directory.
+However, before you test the changes on a Medusa backend or publish your plugin, you must transpile your files, which moves them into the root of your plugin directory.
For example, if you have an endpoint in `src/api/index.js`, after running the `build` or `watch` commands [as defined earlier](#change-scripts), the file should be transpiled into `api/index.js` in your plugin's root.
-If files and directories aren't placed in the root of your plugin, the Medusa server won't detect or load them.
+If files and directories aren't placed in the root of your plugin, the Medusa backend won't detect or load them.
An example of a plugin's directory before testing or publishing:
@@ -139,11 +139,11 @@ medusa-plugin-custom
This guide doesn't cover how to create different files and components. If you’re interested in learning how to do that, you can check out these guides:
-- How to [create endpoints](../endpoints/add.md)
+- How to [create endpoints](../endpoints/create.md)
- How to [create a service](../services/create-service.md)
-- How to [create a subscriber](../subscribers/create-subscriber.md)
-- How to [create an entity](./../entities/index.md)
-- How to [create a migration](../migrations/index.md)
+- How to [create a subscriber](../events/create-subscriber.md)
+- How to [create an entity](../entities/create.md)
+- How to [create a migration](../entities/migrations/create.md)
---
@@ -151,7 +151,7 @@ This guide doesn't cover how to create different files and components. If you’
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.
-To pass a plugin its configurations on a Medusa server, you have to add it to the `plugins` array in `medusa-config.js`:
+To pass a plugin its configurations on a Medusa backend, you have to add it to the `plugins` array in `medusa-config.js`:
```jsx title=medusa-config.js
const plugins = [
@@ -189,7 +189,8 @@ export default (rootDirectory, options) => {
router.get("/hello-world", (req, res) => {
res.json({
- message: `Welcome to ${options.name ? options.name : "Medusa"}!`,
+ message:
+ `Welcome to ${options.name ? options.name : "Medusa"}!`,
})
})
@@ -207,7 +208,7 @@ 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.
+While you develop your plugin, you’ll need to test it on an actual Medusa backend. This can be done by using the [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) command.
In the root of your plugin directory, run the following command:
@@ -215,7 +216,7 @@ In the root of your plugin directory, run the following command:
npm link
```
-Then, change to the directory of the Medusa server you want to test the plugin on and run the following command:
+Then, change to the directory of the Medusa backend you want to test the plugin on and run the following command:
```bash npm2yarn
npm link medusa-plugin-custom
@@ -223,7 +224,7 @@ npm link medusa-plugin-custom
Where `medusa-plugin-custom` is the package name of your plugin.
-After linking to your plugin in a local Medusa server, either run the `build` or `watch` commands in your plugin directory:
+After linking to your plugin in a local Medusa backend, either run the `build` or `watch` commands in your plugin directory:
```bash npm2yarn
# in the directory of the plugin
@@ -253,11 +254,11 @@ const plugins = [
:::note
-If your plugin has migrations, you must run them before you start the server. Check out the [Migrations guide](../migrations/overview.md#migrate-command) for more details.
+If your plugin has migrations, you must run them before you start the backend. Check out the [Migrations guide](../entities/migrations/overview.mdx#migrate-command) for more details.
:::
-Finally, start your server and test your plugin’s functionalities:
+Finally, start your backend and test your plugin’s functionalities:
```bash npm2yarn
npm run start
@@ -270,9 +271,9 @@ npm run start
Please make sure that your plugin is following the correct structure. If the error persists then please try the following fix:
```bash npm2yarn
-cd /node_modules/medusa-interfaces
+cd /node_modules/medusa-interfaces
npm link
-cd /node_modules/@medusajs/medusa
+cd /node_modules/@medusajs/medusa
npm link
cd
rm -rf node_modules/medusa-interfaces
@@ -280,30 +281,30 @@ rm -rf node_modules/@medusajs/medusa
npm link medusa-interfaces
npm link @medusajs/medusa
npm link
-cd
+cd
npm link your-plugin
```
-Where `` is the path to your Medusa server and `` is the path to your plugin.
+Where `` is the path to your Medusa backend and `` is the path to your plugin.
This links the `medusa-interfaces` and `@medusajs/medusa` packages from your `medusa-backend` to your plugin directory and then links your plugin to your `medusa-backend`.
#### APIs not loading
-If the APIs you added to your Medussa server are not loading then please try the following steps:
+If the APIs you added to your Medussa backend are not loading then please try the following steps:
```bash npm2yarn
cd
rm -rf node_modules
-cd /node_modules/
+cd /node_modules/
npm install
cd
npm run build
-cd
+cd
npm run start
```
-Where `` is the path to your Medusa server, `` is the path to your plugin and `` is the name of your plugin as it is in your plugin `package.json` file.
+Where `` is the path to your Medusa backend, `` is the path to your plugin and `` is the name of your plugin as it is in your plugin `package.json` file.
:::note
@@ -318,11 +319,3 @@ It is safe to ignore any `cross-env: command not found` error you may receive.
Once you're done with the development of the plugin, you can publish it to NPM so that other Medusa developers and users can use it.
Please refer to [this guide on required steps to publish a plugin](./publish.md).
-
----
-
-## 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/development/plugins/overview.mdx
similarity index 67%
rename from docs/content/advanced/backend/plugins/overview.md
rename to docs/content/development/plugins/overview.mdx
index 74b430230a5a5..04661efaabf81 100644
--- a/docs/content/advanced/backend/plugins/overview.md
+++ b/docs/content/development/plugins/overview.mdx
@@ -1,7 +1,10 @@
---
-description: 'Learn what Plugins are and how they are used in Medusa. Plugins are re-usable customizations that can be added to a Medusa server.'
+description: 'Learn what Plugins are and how they are used in Medusa. Plugins are re-usable customizations that can be added to a Medusa backend.'
---
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
# Plugins
In this document, you’ll get an overview of plugins in Medusa, where to find them, and how to install them. If you want to learn how to create a plugin, check out [this guide](create.md) instead.
@@ -12,11 +15,11 @@ Medusa was built with flexibility and extendibility in mind. All different compo
Developers can use plugins to take advantage of this abstraction, flexibility, and extendibility. Plugins allow developers to implement custom features or integrate third-party services into Medusa.
-For example, if you want to use Stripe as a payment provider in your store, then you can install the Stripe plugin on your server and use it.
+For example, if you want to use Stripe as a payment provider in your store, then you can install the Stripe plugin on your backend and use it.
An alternative approach is developing a custom way of handling payment on your ecommerce store. Both approaches are achievable by either creating a plugin or using an existing plugin.
-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.
+Plugins run within the same process as the core Medusa backend eliminating the need for extra backend capacity, infrastructure, and maintenance. As a result, plugins can use all other services as dependencies and access the database.
---
@@ -24,7 +27,7 @@ Plugins run within the same process as the core Medusa server eliminating the ne
### Official Plugins
-Medusa has official plugins that cover different aspects and functionalities such as payment, Content Management System (CMS), fulfillment, and notifications. You can check out the available plugins under the [packages directory in the Medusa repository on GitHub](https://github.com/medusajs/medusa/tree/master/packages).
+Medusa has official plugins that cover different aspects and functionalities such as payment, Content Management System (CMS), fulfillment, and notifications. You can check out the available plugins under the [Plugins section of this documentation](../../plugins/overview.mdx).
:::tip
@@ -40,7 +43,7 @@ You can also check the [Awesome Medusa repository](https://github.com/adrien2p/a
## How to Install a Plugin
-To install an existing plugin, in your Medusa server run the following command:
+To install an existing plugin, in your Medusa backend run the following command:
```bash npm2yarn
npm install
@@ -56,8 +59,27 @@ For community plugins, please refer to the installation instructions of that plu
---
-## See Also
-
-- [Create a plugin](create.md)
-- [Publish a plugin](publish.md)
-- [Create a fulfillment provider](../shipping/add-fulfillment-provider.md) or a [payment provider](../payment/how-to-create-payment-provider.md)
+## Custom Development
+
+Developers can create plugins and reuse them across different Medusa backends. They can also share them with the community to help out other developers.
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/plugins/publish.md b/docs/content/development/plugins/publish.md
similarity index 96%
rename from docs/content/advanced/backend/plugins/publish.md
rename to docs/content/development/plugins/publish.md
index c8af392320572..27bc03c340369 100644
--- a/docs/content/advanced/backend/plugins/publish.md
+++ b/docs/content/development/plugins/publish.md
@@ -34,7 +34,7 @@ Before publishing your plugin, make sure you've set the following fields in your
- `medusa-plugin-shipping`: For plugins that add shipping functionalities or integrations.
- `medusa-plugin-storage`: For plugins that add a file service or storage integration.
- `medusa-plugin-source`: For plugins that help migrate or import data into Medusa from another platform.
- - `medusa-plugin-storefront`: For storefronts that can be integrated with a Medusa server.
+ - `medusa-plugin-storefront`: For storefronts that can be integrated with a Medusa backend.
- `medusa-plugin-other`: For any other type of plugin.
### Scripts in package.json
@@ -131,7 +131,7 @@ Your package is then published on NPM and everyone can use it and install it.
### Install Plugin
-To install your published plugin, you can run the following command on any Medusa server project:
+To install your published plugin, you can run the following command on any Medusa backend project:
```bash npm2yarn
npm install medusa-plugin-custom
@@ -151,10 +151,4 @@ Then, publish the new update:
```bash
npm publish
-```
-
----
-
-## See Also
-
-- [Available official plugins](https://github.com/medusajs/medusa/tree/master/packages)
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/docs/content/advanced/admin/manage-publishable-api-keys.mdx b/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx
similarity index 85%
rename from docs/content/advanced/admin/manage-publishable-api-keys.mdx
rename to docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx
index bbfb3e006b4b7..a3b519579bff8 100644
--- a/docs/content/advanced/admin/manage-publishable-api-keys.mdx
+++ b/docs/content/development/publishable-api-keys/admin/manage-publishable-api-keys.mdx
@@ -37,19 +37,19 @@ You want to use or implement the following admin functionalities:
### 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.
+It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../backend/install.mdx) to get started.
### JS Client
-This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, among other methods.
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
-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).
+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).
### Medusa React
-This guide also includes code snippets to send requests to your Medusa server using Medusa React, among other methods.
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
-If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../medusa-react/overview.md#usage).
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
### Authenticated Admin User
@@ -81,7 +81,8 @@ import { PublishableApiKey } from "@medusajs/medusa"
import { useAdminPublishableApiKeys } from "medusa-react"
const PublishabelApiKeys = () => {
- const { publishable_api_keys, isLoading } = useAdminPublishableApiKeys()
+ const { publishable_api_keys, isLoading } =
+ useAdminPublishableApiKeys()
return (
@@ -89,11 +90,14 @@ const PublishabelApiKeys = () => {
{publishable_api_keys && !publishable_api_keys.length && (
No Publishable API Keys
)}
- {publishable_api_keys && publishable_api_keys.length > 0 && (
+ {publishable_api_keys &&
+ publishable_api_keys.length > 0 && (
{publishable_api_keys.map(
(publishableApiKey: PublishableApiKey) => (
- - {publishableApiKey.title}
+ -
+ {publishableApiKey.title}
+
)
)}
@@ -109,7 +113,7 @@ export default PublishabelApiKeys
```ts
-fetch(`/admin/publishable-api-keys`, {
+fetch(`/admin/publishable-api-keys`, {
credentials: "include",
})
.then((response) => response.json())
@@ -122,7 +126,7 @@ fetch(`/admin/publishable-api-keys`, {
```bash
-curl -L -X GET '/admin/publishable-api-keys' \
+curl -L -X GET '/admin/publishable-api-keys' \
-H 'Authorization: Bearer '
```
@@ -188,7 +192,7 @@ export default CreatePublishableApiKey
```ts
-fetch(`/admin/publishable-api-keys`, {
+fetch(`/admin/publishable-api-keys`, {
method: "POST",
credentials: "include",
headers: {
@@ -208,7 +212,7 @@ fetch(`/admin/publishable-api-keys`, {
```bash
-curl -L -X POST '/admin/publishable-api-keys' \
+curl -L -X POST '/admin/publishable-api-keys' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
--data-raw '{
@@ -248,7 +252,9 @@ medusa.admin.publishableApiKeys.update(publishableApiKeyId, {
import { useAdminUpdatePublishableApiKey } from "medusa-react"
const UpdatePublishableApiKey = () => {
- const updateKey = useAdminUpdatePublishableApiKey(publishableApiKeyId)
+ const updateKey = useAdminUpdatePublishableApiKey(
+ publishableApiKeyId
+ )
// ...
const handleUpdate = (title: string) => {
@@ -266,8 +272,10 @@ export default UpdatePublishableApiKey
+
+
```ts
-fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
+fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
method: "POST",
credentials: "include",
headers: {
@@ -287,7 +295,7 @@ fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
```bash
-curl -L -X POST '/admin/publishable-api-keys/' \
+curl -L -X POST '/admin/publishable-api-keys/' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
--data-raw '{
@@ -327,7 +335,9 @@ medusa.admin.publishableApiKeys.revoke(publishableApiKeyId)
import { useAdminRevokePublishableApiKey } from "medusa-react"
const PublishableApiKey = () => {
- const revokeKey = useAdminRevokePublishableApiKey(publishableApiKeyId)
+ const revokeKey = useAdminRevokePublishableApiKey(
+ publishableApiKeyId
+ )
// ...
const handleRevoke = () => {
@@ -343,9 +353,11 @@ export default PublishableApiKey
+
+
```ts
fetch(
- `/admin/publishable-api-keys/${publishableApiKeyId}/revoke`,
+ `/admin/publishable-api-keys/${publishableApiKeyId}/revoke`,
{
method: "POST",
credentials: "include",
@@ -361,7 +373,7 @@ fetch(
```bash
-curl -L -X POST '/admin/publishable-api-keys//revoke' \
+curl -L -X POST '/admin/publishable-api-keys//revoke' \
-H 'Authorization: Bearer '
```
@@ -393,7 +405,9 @@ medusa.admin.publishableApiKeys.delete(publishableApiKeyId)
import { useAdminDeletePublishableApiKey } from "medusa-react"
const PublishableApiKey = () => {
- const deleteKey = useAdminDeletePublishableApiKey(publishableApiKeyId)
+ const deleteKey = useAdminDeletePublishableApiKey(
+ publishableApiKeyId
+ )
// ...
const handleDelete = () => {
@@ -409,8 +423,10 @@ export default PublishableApiKey
+
+
```ts
-fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
+fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
method: "DELETE",
credentials: "include",
})
@@ -424,7 +440,7 @@ fetch(`/admin/publishable-api-keys/${publishableApiKeyId}`, {
```bash
-curl -L -X DELETE '/admin/publishable-api-keys/' \
+curl -L -X DELETE '/admin/publishable-api-keys/' \
-H 'Authorization: Bearer '
```
@@ -453,7 +469,8 @@ You can retrieve the list of sales channels associated with a publishable API ke
```ts
-medusa.admin.publishableApiKeys.listSalesChannels(publishableApiKeyId)
+medusa.admin.publishableApiKeys
+ .listSalesChannels(publishableApiKeyId)
.then(({ sales_channels }) => {
console.log(sales_channels)
})
@@ -464,7 +481,9 @@ medusa.admin.publishableApiKeys.listSalesChannels(publishableApiKeyId)
```tsx
import { SalesChannel } from "@medusajs/medusa"
-import { useAdminPublishableApiKeySalesChannels } from "medusa-react"
+import {
+ useAdminPublishableApiKeySalesChannels,
+} from "medusa-react"
const SalesChannels = () => {
const { sales_channels, isLoading } =
@@ -499,7 +518,7 @@ export default SalesChannels
```ts
fetch(
- `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels`,
+ `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels`,
{
credentials: "include",
}
@@ -514,7 +533,7 @@ fetch(
```bash
-curl -L -X GET '/admin/publishable-api-keys//sales-channels' \
+curl -L -X GET '/admin/publishable-api-keys//sales-channels' \
-H 'Authorization: Bearer '
```
@@ -552,12 +571,15 @@ medusa.admin.publishableApiKeys.addSalesChannelsBatch(
```tsx
-import { useAdminAddPublishableKeySalesChannelsBatch } from "medusa-react"
+import {
+ useAdminAddPublishableKeySalesChannelsBatch,
+} from "medusa-react"
const PublishableApiKey = () => {
- const addSalesChannels = useAdminAddPublishableKeySalesChannelsBatch(
- publishableApiKeyId
- )
+ const addSalesChannels =
+ useAdminAddPublishableKeySalesChannelsBatch(
+ publishableApiKeyId
+ )
// ...
const handleAdd = (salesChannelId: string) => {
@@ -583,7 +605,7 @@ export default PublishableApiKey
```ts
fetch(
- `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
+ `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
{
method: "POST",
credentials: "include",
@@ -609,7 +631,7 @@ fetch(
```bash
-curl -L -X POST '/admin/publishable-api-keys//sales-channels/batch' \
+curl -L -X POST '/admin/publishable-api-keys//sales-channels/batch' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
--data-raw '{
@@ -693,7 +715,7 @@ export default PublishableApiKey
```ts
fetch(
- `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
+ `/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
{
method: "DELETE",
credentials: "include",
@@ -719,7 +741,7 @@ fetch(
```bash
-curl -L -X DELETE '/admin/publishable-api-keys//sales-channels/batch' \
+curl -L -X DELETE '/admin/publishable-api-keys//sales-channels/batch' \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
--data-raw '{
@@ -746,5 +768,4 @@ This request returns the updated publishable API key in the response.
## See Also
-- [Publishable API key overview](../backend/publishable-api-keys/index.md)
-- [Publishable API key admin API reference](/api/admin/#tag/PublishableApiKey)
+- [Use publishable API keys in client requests](../storefront/use-in-requests.md)
diff --git a/docs/content/development/publishable-api-keys/index.mdx b/docs/content/development/publishable-api-keys/index.mdx
new file mode 100644
index 0000000000000..d123f3bcfd8a9
--- /dev/null
+++ b/docs/content/development/publishable-api-keys/index.mdx
@@ -0,0 +1,69 @@
+---
+description: 'Learn what publishable API keys are and how they can be used in the Medusa backend. Publishable API keys can be used to scope API calls with an API key.'
+---
+
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
+# Publishable API Keys
+
+In this document, you’ll learn about Publishable API Keys and their architecture.
+
+## Introduction
+
+While using Medusa’s APIs, you might have to pass some query parameters for certain resources with every or most requests.
+
+Taking Sales Channels as an example, you have to pass the Sales Channel’s ID as a query parameter to all the necessary endpoints, such as the List Products endpoint.
+
+This is a tedious and error-prone process. This is where Publishable API Keys are useful.
+
+Publishable API Keys can be used to scope API calls with an API key, determining what resources are retrieved when querying the API. Currently, they can be associated only with Sales Channels.
+
+For example, you can associate an API key with a B2B channel, then, on the storefront, retrieve only products available in that channel using the API key.
+
+---
+
+## PublishableApiKey Entity Overview
+
+The `PublishableApiKey` entity represents a publishable API key that is stored in the database. Some of its important attributes include:
+
+- `id`: The ID of the publishable API key. This is the API key you’ll use in your API requests.
+- `created_by`: The ID of the user that created this API key.
+- `revoked_by`: The ID of the user that revoked this API key. A revoked publishable API key cannot be used in requests.
+
+---
+
+## Relation to Other Entities
+
+### Sales Channels
+
+A publishable API key can be associated with more than one sales channel, and a sales channel can be associated with more than one publishable API key.
+
+The relation is represented by the entity `PublishableApiKeySalesChannel`.
+
+---
+
+## Custom Development
+
+Developers can manage Publishable API Keys and use them when making requests to the Store APIs.
+
+
\ No newline at end of file
diff --git a/docs/content/development/publishable-api-keys/storefront/use-in-requests.md b/docs/content/development/publishable-api-keys/storefront/use-in-requests.md
new file mode 100644
index 0000000000000..dbf3031f50176
--- /dev/null
+++ b/docs/content/development/publishable-api-keys/storefront/use-in-requests.md
@@ -0,0 +1,78 @@
+---
+description: 'Learn how to use Publishable API Keys in Client Requests using Medusa JS Client, Medusa React, or other methods.'
+---
+
+# Use Publishable API Keys in Client Requests
+
+In this document, you'll learn how to use Publishable API Keys in client requests.
+
+:::note
+
+[Publishable API keys](../index.mdx) are only for client-side use. They can be publicly accessible in your code, as they are not authorized for the Admin API.
+
+:::
+
+## Using Medusa JS Client
+
+When using [Medusa’s JS Client](../../../js-client/overview.md), you can pass it to the client only once when you create the instance of the client:
+
+```ts
+const medusa = new Medusa({
+ maxRetries: 3,
+ baseUrl: "https://api.example.com",
+ publishableApiKey,
+})
+```
+
+This will add the API key as in the header parameter `x-publishable-api-key` on all requests.
+
+You can also use the `setPublishableKey` method to set it at a later point:
+
+```ts
+const medusa = new Medusa({
+ // ...
+})
+
+// at a later point
+medusa.setPublishableKey(publishableApiKey)
+```
+
+## Using Medusa React
+
+You can pass the publishable API key to the `MedusaProvider` component:
+
+```tsx
+const App = () => {
+ return (
+
+
+
+ )
+}
+```
+
+Then, the API key will be passed in the header parameter `x-publishable-api-key` of every request.
+
+## Using Other Methods
+
+For other ways of sending requests to your Medusa backend, such as using the Fetch API, you must pass `x-publishable-api-key` in the header of every request. Its value is the publishable API key’s `id`.
+
+```ts
+fetch(`/store/products`, {
+ credentials: "include",
+ headers: {
+ "x-publishable-api-key": publishableApiKey,
+ },
+})
+```
+
+---
+
+## See Also
+
+- [Manage publishable keys as an admin](../admin/manage-publishable-api-keys.mdx)
\ No newline at end of file
diff --git a/docs/content/advanced/backend/scheduled-jobs/create.md b/docs/content/development/scheduled-jobs/create.md
similarity index 74%
rename from docs/content/advanced/backend/scheduled-jobs/create.md
rename to docs/content/development/scheduled-jobs/create.md
index f7c0438a6fc8f..7a70e73839e54 100644
--- a/docs/content/advanced/backend/scheduled-jobs/create.md
+++ b/docs/content/development/scheduled-jobs/create.md
@@ -1,5 +1,5 @@
---
-description: 'Learn how to create a scheduled job in the Medusa server. The scheduled job in this example will simply change the status of draft products to published.'
+description: 'Learn how to create a scheduled job in Medusa. The scheduled job in this example will simply change the status of draft products to published.'
addHowToData: true
---
@@ -9,9 +9,9 @@ In this document, you’ll learn how to create a scheduled job in Medusa.
## Overview
-Medusa allows you to create scheduled jobs that run at specific times during your server’s lifetime. For example, you can synchronize your inventory with an Enterprise Resource Planning (ERP) system once a day.
+Medusa allows you to create scheduled jobs that run at specific times during your backend's lifetime. For example, you can synchronize your inventory with an Enterprise Resource Planning (ERP) system once a day.
-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`.
+This guide explains how to create a scheduled job on your Medusa backend. The scheduled job in this example will simply change the status of draft products to `published`.
---
@@ -19,11 +19,11 @@ This guide explains how to create a scheduled job on your Medusa server. The sch
### 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.
+It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../backend/install.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).
+Redis is required for scheduled jobs to work. Make sure you [install Redis](../../development/backend/prepare-environment.mdx#redis) and [configure it with your Medusa backend](../../development/backend/configurations.md#redis).
---
@@ -43,8 +43,12 @@ To create a scheduled job, add the following code in the file you created, which
```ts title=src/loaders/publish.ts
const publishJob = async (container, options) => {
- const jobSchedulerService = container.resolve("jobSchedulerService")
- jobSchedulerService.create("publish-products", {}, "0 0 * * *",
+ const jobSchedulerService =
+ container.resolve("jobSchedulerService")
+ jobSchedulerService.create(
+ "publish-products",
+ {},
+ "0 0 * * *",
async () => {
// job to execute
const productService = container.resolve("productService")
@@ -77,7 +81,7 @@ You then resolve the `JobSchedulerService` and use the `jobSchedulerService.crea
- The first parameter is a unique name to give to the scheduled job. In the example above, you use the name `publish-products`;
- The second parameter is an object which can be used to [pass data to the job](#pass-data-to-the-scheduled-job);
- The third parameter is the scheduled job expression pattern. In this example, it will execute the scheduled job once a day at 12 AM.
-- The fourth parameter is the function to execute. This is where you add the code to execute once the scheduled job runs. In this example, you retrieve the draft products using the [ProductService](../../../references/services/classes/ProductService.md) and update the status of each of these products to `published`.
+- The fourth parameter is the function to execute. This is where you add the code to execute once the scheduled job runs. In this example, you retrieve the draft products using the [ProductService](../../references/services/classes/ProductService.md) and update the status of each of these products to `published`.
:::tip
@@ -104,23 +108,23 @@ jobSchedulerService.create("publish-products", {
---
-## 3. Run Medusa Server
+## 3. Run Medusa Backend
:::info
-Cron Jobs only run while the Medusa server is running.
+Cron Jobs only run while the Medusa backend is running.
:::
-In your terminal run the following command to run your Medusa server:
+In your terminal run the following command to run your Medusa backend:
```bash npm2yarn
npm run start
```
-This builds your code under the `src` directory into the `dist` directory, then runs the Medusa server.
+This builds your code under the `src` directory into the `dist` directory, then runs the Medusa backend.
-If the scheduled job was registered successfully, you should see a message similar to this logged on your Medusa server:
+If the scheduled job was registered successfully, you should see a message similar to this logged on your Medusa backend:
```bash
Registering publish-products
@@ -128,15 +132,15 @@ Registering publish-products
Where `publish-products` is the unique name you provided to the scheduled job.
-Once it is time to run your scheduled job based on the scheduled job expression pattern, the scheduled job will run and you can see it logged on your Medusa server.
+Once it is time to run your scheduled job based on the scheduled job expression pattern, the scheduled job will run and you can see it logged on your Medusa backend.
-For example, the above scheduled job will run at 12 AM and, when it runs, you can see the following logged on your Medusa server:
+For example, the above scheduled job will run at 12 AM and, when it runs, you can see the following logged on your Medusa backend:
```bash noReport
info: Processing scheduled job: publish-products
```
-If you log anything in the scheduled job, for example using `console.log`, or if any errors are thrown, it’ll also be logged on your Medusa server.
+If you log anything in the scheduled job, for example using `console.log`, or if any errors are thrown, it’ll also be logged on your Medusa backend.
:::tip
@@ -148,4 +152,4 @@ To test the previous example out instantly, you can change the scheduled job exp
## See Also
-- [Services Overview](../services/overview.md).
+- [Create a Plugin](../plugins/create.md)
\ No newline at end of file
diff --git a/docs/content/development/scheduled-jobs/overview.mdx b/docs/content/development/scheduled-jobs/overview.mdx
new file mode 100644
index 0000000000000..d9ee10fb40ce8
--- /dev/null
+++ b/docs/content/development/scheduled-jobs/overview.mdx
@@ -0,0 +1,40 @@
+---
+description: "Learn what scheduled jobs are in Medusa. Scheduled jobs (also known as cron jobs) are tasks performed at a specific time in the Medusa Backend."
+---
+
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
+# Scheduled Jobs
+
+In this document, you’ll learn what scheduled jobs are in Medusa.
+
+## Introduction
+
+Scheduled jobs (also known as cron jobs) are tasks performed at a specific time while the Medusa Backend is running. They’re used to perform asynchronous tasks in the background.
+
+For example, you can synchronize your inventory with an Enterprise Resource Planning (ERP) system once a day using a scheduled job.
+
+In the Medusa Backend, the scheduled jobs queue is implemented using [Redis](https://redis.io/) and [Bull](https://www.npmjs.com/package/bull). So, for scheduled jobs to work, you must have [Redis enabled](../../development/backend/configurations.md#redis).
+
+:::tip
+
+Future versions of Medusa will allow switching out Redis and using a different pub/sub service.
+
+:::
+
+---
+
+## Custom Development
+
+Developers can create an unlimited number of scheduled jobs within the Medusa Backend, a plugin, or a custom Commerce Module.
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/services/create-service.md b/docs/content/development/services/create-service.md
similarity index 91%
rename from docs/content/advanced/backend/services/create-service.md
rename to docs/content/development/services/create-service.md
index 7dfeabfd6de9a..3c5450e5d3a5a 100644
--- a/docs/content/advanced/backend/services/create-service.md
+++ b/docs/content/development/services/create-service.md
@@ -5,7 +5,7 @@ addHowToData: true
# Create a Service
-In this document, you’ll learn how you can create a [Service](./overview.md) and use it across your Medusa server just like any of the core services.
+In this document, you’ll learn how you can create a [Service](./overview.mdx) and use it across your Medusa backend just like any of the core services.
## Implementation
@@ -63,7 +63,7 @@ class HelloService extends TransactionBaseService {
## 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.
+In this section, you'll learn how to use services throughout your Medusa backend. This includes both Medusa's services and your custom services.
:::note
@@ -118,5 +118,4 @@ class MySubscriber {
## See Also
-- [Services Reference](/references/services/classes/AuthService)
-- [Create an Endpoint](../endpoints/add.md)
+- [Create a Plugin](../plugins/create.md)
diff --git a/docs/content/development/services/overview.mdx b/docs/content/development/services/overview.mdx
new file mode 100644
index 0000000000000..a066fccdd32a1
--- /dev/null
+++ b/docs/content/development/services/overview.mdx
@@ -0,0 +1,49 @@
+---
+description: 'Learn what Services are in Medusa. Services represent bundled helper methods that you want to use across your commerce application.'
+---
+
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
+# Services
+
+In this document, you'll learn about what Services are in Medusa.
+
+## What are Services
+
+Services in Medusa represent bundled helper methods that you want to use across your commerce application. By convention, they represent a certain entity or functionality in Medusa.
+
+For example, you can use Medusa’s `productService` to get the list of products, as well as perform other functionalities related to products. There’s also an `authService` that provides functionalities like authenticating customers and users.
+
+In the Medusa backend, custom services are TypeScript or JavaScript files located in the `src/services` directory. Each service should be a class that extends the `TransactionBaseService` class from the core Medusa package `@medusajs/medusa`. Each file you create in `src/services` should hold one service and export it.
+
+The file name is important as it determines the name of the service when you need to use it elsewhere. The name of the service will be registered as the camel-case version of the file name + `Service` at the end of the name.
+
+For example, if the file name is `hello.ts`, the service will be registered as `helloService`. If the file name is `hello-world.ts`, the service name will be registered as `helloWorldService`.
+
+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.
+
+The service must then be transpiled using the `build` command, which moves them to the `dist` directory, to be used across your commerce application.
+
+:::tip
+
+If you're creating a service in a plugin, learn more about the required structure [here](../plugins/create.md#plugin-structure).
+
+:::
+
+---
+
+## Custom Development
+
+Developers can create custom services in the Medusa backend, a plugin, or in a Commerce Module.
+
+
\ No newline at end of file
diff --git a/docs/content/development/strategies/overview.mdx b/docs/content/development/strategies/overview.mdx
new file mode 100644
index 0000000000000..10656385982da
--- /dev/null
+++ b/docs/content/development/strategies/overview.mdx
@@ -0,0 +1,68 @@
+---
+description: "Learn what a Strategy is in Medusa. A strategy is an isolated piece of business logic that can be overridden and customized."
+---
+
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
+# Strategy
+
+In this document, you’ll learn what a Strategy is in Medusa.
+
+## Introduction
+
+A strategy is an isolated piece of business logic that can be overridden and customized. It’s a TypeScript or JavaScript class that doesn’t have to follow a specific definition, but performs only a single functionality.
+
+For example, in the core `@medusajs/medusa` package, strategies are used to implement functionalities like cart completion and product import.
+
+These strategy classes are then resolved in endpoints, services, or wherever needed using dependency injection and used to perform their designated functionality.
+
+For example, the `CartCompletionStrategy` is resolved in the Complete Cart endpoint that is defined in the core `@medusajs/medusa` package. It’s then used to complete the cart and place the order:
+
+```ts
+export default async (req, res) => {
+ // ...
+ const completionStrat: AbstractCartCompletionStrategy =
+ req.scope.resolve(
+ "cartCompletionStrategy"
+ )
+
+ const {
+ response_code,
+ response_body,
+ } = await completionStrat.complete(
+ id,
+ idempotencyKey,
+ req.request_context
+ )
+
+ res.status(response_code).json(response_body)
+}
+```
+
+Developers can override these strategies defined in the core to customize their functionality. Dependency injection then resolves the strategy (in the code example above, `CartCompletionStrategy`) to the custom strategy that the developer created. Then, the method (in the code example above, `complete`) of the custom strategy will be executed instead of the one defined in the core package.
+
+## Custom Development
+
+
\ No newline at end of file
diff --git a/docs/content/homepage.mdx b/docs/content/homepage.mdx
index af9d5428c5b93..a77b8a6d9fc15 100644
--- a/docs/content/homepage.mdx
+++ b/docs/content/homepage.mdx
@@ -8,163 +8,191 @@ hide_footer: true
---
import DocCardList from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
# Medusa Documentation
-Get an overview of Medusa's features, integrations, and how to use them.
+Medusa is a set of commerce tools and modules that can be used to build unique commerce experiences.
-## Medusa basics
+Medusa provides the essential building blocks that developers can put together to create a powerful commerce store. Developers have full control over their tech stack and the logic behind the commerce features.
-Learn about Medusa basic features and kickstart your ecommerce project.
+
+
+## Explore Medusa
+
+## Medusa Toolkit
+
+
+
+
-## Most popular
-
-Best of the greatest.
-
-
+
+
+
+## What's New
+
+Learn about all the new features and enhancements in Medusa.
+
+
\ No newline at end of file
+ },
+]} />
+
+
+
+## Need Help?
+
+
+
+If you’re still not sure that Medusa is the right solution for you, you can get in-touch with the core Medusa team over at [Discord](https://discord.gg/medusajs) and get help from the community.
\ No newline at end of file
diff --git a/docs/content/introduction.md b/docs/content/introduction.md
deleted file mode 100644
index b203ed7381b1a..0000000000000
--- a/docs/content/introduction.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-description: 'Medusa is composed of three architectures: Medusa server, admin dashboard, and storefront. It also provides advanced ecommerce features such as order management and automated RMA flows.'
----
-
-# Overview
-
-## Architecture
-
-Medusa is composed of three components: The Medusa server, the admin dashboard, and the storefront.
-
-
-
-### Medusa Server
-
-The Medusa server is a headless backend built on Node.js. This is the main component that holds all the logic and data of the store. Your admin dashboard and storefront interact with the backend to retrieve, create, and modify data through REST APIs.
-
-Your Medusa server will include all functionalities related to your store’s checkout workflow. That includes cart management, shipping and payment providers, user management, and more. It also allows you to configure your store including your store’s region, tax rules, discounts, gift cards, and more.
-
-### Admin Dashboard
-
-The admin dashboard is accessible by store operators. Store operators can use the admin dashboard to view, create, and modify data such as orders and products.
-
-Medusa provides a beautiful [admin dashboard](https://demo.medusajs.com) that you can use right off the bat. Medusa's admin dashboard provides a lot of functionalities to manage your store including Order management, Product management, User management, and more.
-
-You can also create your own admin dashboard by utilizing the [Admin REST APIs](https://docs.medusajs.com/api/admin).
-
-### Storefront
-
-Your customers use the Storefront to view products and make orders. Medusa provides two storefronts, one built with [Next.js](https://docs.medusajs.com/starters/nextjs-medusa-starter) and one with [Gatsby](https://docs.medusajs.com/starters/gatsby-medusa-starter). You are also free to create your own storefront using the [Storefront REST APIs](https://docs.medusajs.com/api/store/).
-
----
-
-## Features
-
-- [Orders, Exchanges, and Returns](./user-guide/orders/index.md): Aside from the standard order management that comes with ecommerce platforms, Medusa also provides an easy and automated way to manage swaps, returns, and claims.
-- [Customers and Customer Groups](./user-guide/customers/index.md): Manage Customers and assign them to customer groups.
-- [Products and Collections](./user-guide/products/index.mdx): Add products with extensive customization settings and sort them into collections.
-- [Region](./user-guide/regions/index.md): Configure and manage multiple regions and currencies all from one platform.
-- [Plugins](./advanced/backend/plugins/overview.md): Easily integrate fulfillment providers, payment providers, notification services, and many other custom tools and third-party services.
-- [PriceList](./user-guide/price-lists/index.md) and [Discounts](./user-guide/discounts/): Advanced pricing for products with conditions based on the amount in the cart or promotions and discounts.
-- [Taxes](./user-guide/taxes/index.md): Advanced tax configurations specific to multiple regions, with the capability of specifying taxes for specific products.
-- [Sales Channels](./user-guide/sales-channels/index.md): Create multiple sales channels and control which sales channels products are available in.
-- [Bulk Import](./user-guide/products/import.mdx): Bulk import strategies for different entities including [products](./advanced/admin/import-products.mdx) and [price lists](./advanced/admin/import-prices.mdx).
-- [Bulk Export](./user-guide/products/export.mdx): Bulk export strategies for different entities including [products](./user-guide/products/export.mdx) and [orders](./user-guide/orders/export.mdx).
-- Complete Customization Capabilities: Aside from all the features that Medusa provides, it is completely customizable providing capabilities to create custom [endpoints](./advanced/backend/endpoints/add.md), [services](./advanced/backend/services/create-service.md), [subscribers](./advanced/backend/subscribers/create-subscriber.md), [batch job strategies](./advanced/backend/batch-jobs/create.mdx), and much more!
-
----
-
-## See Also
-
-- [Quickstart guide](./quickstart/quick-start.mdx)
-- [Install the Next.js Storefront](./starters/nextjs-medusa-starter.mdx)
-- [Install Medusa Admin](./admin/quickstart.mdx)
\ No newline at end of file
diff --git a/docs/content/medusa-react/overview.md b/docs/content/medusa-react/overview.md
index 254895487eec2..44a7229013f05 100644
--- a/docs/content/medusa-react/overview.md
+++ b/docs/content/medusa-react/overview.md
@@ -1,10 +1,10 @@
---
-description: 'Learn how to install Medusa React in a React storefront. Medusa React is a React library that provides a set of utilities and hooks for interactive with the Medusa server.'
+description: 'Learn how to install Medusa React in a React storefront. Medusa React is a React library that provides a set of utilities and hooks for interactive with the Medusa backend.'
---
# Medusa React
-[Medusa React](https://www.npmjs.com/package/medusa-react) is a React library that provides a set of utilities and hooks for interacting seamlessly with the Medusa server. It can be used to build custom React-based storefronts or admin dashboards.
+[Medusa React](https://www.npmjs.com/package/medusa-react) is a React library that provides a set of utilities and hooks for interacting seamlessly with the Medusa backend. It can be used to build custom React-based storefronts or admin dashboards.
:::tip
@@ -46,7 +46,7 @@ To use the hooks exposed by Medusa React, you need to include the `MedusaProvi
The `MedusaProvider` requires two props:
-1. `baseUrl`: The URL to your Medusa server
+1. `baseUrl`: The URL to your Medusa backend
2. `queryClientProviderProps`: An object used to set the Tanstack Query client. The object requires a `client` property, which should be an instance of [QueryClient](https://tanstack.com/query/v4/docs/react/reference/QueryClient).
For example:
@@ -88,9 +88,9 @@ You can also pass the following props to Medusa Provider:
### Queries
-To fetch data from the Medusa server (in other words, perform `GET` requests), you can use [Queries](https://tanstack.com/query/v4/docs/react/guides/queries). Query hooks simply wrap around Tanstack Query's `useQuery` hook to fetch data from your medusa server.
+To fetch data from the Medusa backend (in other words, perform `GET` requests), you can use [Queries](https://tanstack.com/query/v4/docs/react/guides/queries). Query hooks simply wrap around Tanstack Query's `useQuery` hook to fetch data from your medusa backend.
-For example, to fetch products from your Medusa server:
+For example, to fetch products from your Medusa backend:
```tsx title=src/Products.ts
import { Product } from "@medusajs/medusa"
@@ -133,7 +133,7 @@ You can learn more about using queries in [Tanstack Query’s documentation](htt
### Mutations
-To create, update, or delete data on the Medusa server (in other words, perform `POST`, `PUT`, and `DELETE` requests), you can use [Mutations](https://tanstack.com/query/v4/docs/react/guides/mutations). Mutation hooks wrap around Tanstack Query's `useMutation` to mutate data on your medusa server.
+To create, update, or delete data on the Medusa backend (in other words, perform `POST`, `PUT`, and `DELETE` requests), you can use [Mutations](https://tanstack.com/query/v4/docs/react/guides/mutations). Mutation hooks wrap around Tanstack Query's `useMutation` to mutate data on your medusa backend.
For example, to create a cart:
@@ -166,7 +166,7 @@ export default Cart
In the example above, you import the `useCreateCart` hook from `medusa-react`. This hook, and every other mutation hook exposed by `medusa-react`, returns everything that [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation) returns. You can also pass the same options you would pass to `useMutation` to mutation hooks exposed by `medusa-react`.
-To create a cart, you call the `createCart.mutate` method. In the underlying logic, this method sends a `POST` request to the Medusa server to create a cart.
+To create a cart, you call the `createCart.mutate` method. In the underlying logic, this method sends a `POST` request to the Medusa backend to create a cart.
If the request accepts any parameters, they can be passed as parameters to the `mutate` request. For example:
@@ -200,8 +200,8 @@ This utility function can be used to compute the price of a variant for a region
It accepts an object with the following properties:
-- `variant`: A variant object retrieved from the Medusa server. It should mainly include the `prices` array in the object.
-- `region`: A region object retrieved from the Medusa server.
+- `variant`: A variant object retrieved from the Medusa backend. It should mainly include the `prices` array in the object.
+- `region`: A region object retrieved from the Medusa backend.
- `includeTaxes`: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is `true`.
- `minimumFractionDigits`: (optional) The minimum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` in the underlying layer. You can learn more about this method’s options in [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
- `maximumFractionDigits`: (optional) The maximum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` which is used within the utility method. You can learn more about this method’s options in [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
@@ -243,8 +243,8 @@ This utility function can be used to compute the price of a variant for a region
It accepts an object with the following properties:
-- `variant`: A variant object retrieved from the Medusa server. It should mainly include the `prices` array in the variant.
-- `region`: A region object retrieved from the Medusa server.
+- `variant`: A variant object retrieved from the Medusa backend. It should mainly include the `prices` array in the variant.
+- `region`: A region object retrieved from the Medusa backend.
- `includeTaxes`: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is `true`.
For example:
@@ -286,7 +286,7 @@ The main difference between this utility function and `formatVariantPrice` is th
It accepts an object with the following properties:
- `amount`: A number that should be used for computation.
-- `region`: A region object retrieved from the Medusa server.
+- `region`: A region object retrieved from the Medusa backend.
- `includeTaxes`: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is `true`.
- `minimumFractionDigits`: (optional) The minimum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` in the underlying layer. You can learn more about this method’s options in [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
- `maximumFractionDigits`: (optional) The maximum number of fraction digits to use when formatting the price. This is passed as an option to `Intl.NumberFormat` which is used within the utility method. You can learn more about this method’s options in [MDN’s documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters).
@@ -319,7 +319,7 @@ The main difference between this utility function and `computeVariantPrice` is t
It accepts an object with the following properties:
- `amount`: A number that should be used for computation.
-- `region`: A region object retrieved from the Medusa server.
+- `region`: A region object retrieved from the Medusa backend.
- `includeTaxes`: (optional) A boolean value that indicates whether the computed price should include taxes or not. The default value is `true`.
For example:
@@ -354,7 +354,7 @@ To facilitate building custom storefronts, `medusa-react` also exposes a `CartP
### CartProvider
-`CartProvider` makes use of some of the hooks already exposed by `medusa-react` to perform cart operations on the Medusa server. You can use it to create a cart, start the checkout flow, authorize payment sessions, and so on.
+`CartProvider` makes use of some of the hooks already exposed by `medusa-react` to perform cart operations on the Medusa backend. You can use it to create a cart, start the checkout flow, authorize payment sessions, and so on.
It also manages one single global piece of state which represents a cart, exactly like the one created on your medusa backend.
@@ -432,7 +432,7 @@ const Cart = () => {
export default Cart
```
-In the example above, you retrieve the `createCart` mutation and `cart` state object using the `useCart` hook. If the `cart` is not set, a button is shown. When the button is clicked, the `createCart` mutation is executed, which interacts with the server and creates a new cart.
+In the example above, you retrieve the `createCart` mutation and `cart` state object using the `useCart` hook. If the `cart` is not set, a button is shown. When the button is clicked, the `createCart` mutation is executed, which interacts with the backend and creates a new cart.
After the cart is created, the `cart` state variable is set and its ID is shown instead of the button.
@@ -444,9 +444,9 @@ The example above does not store in the browser the ID of the cart created, so t
### SessionProvider
-Unlike the `CartProvider`, `SessionProvider` never interacts with the Medusa server. It can be used to implement the user experience related to managing a cart’s items. Its state variables are JavaScript objects living in the browser, but are in no way communicated with the server.
+Unlike the `CartProvider`, `SessionProvider` never interacts with the Medusa backend. It can be used to implement the user experience related to managing a cart’s items. Its state variables are JavaScript objects living in the browser, but are in no way communicated with the backend.
-You can use the `SessionProvider` as a lightweight client-side cart functionality. It’s not stored in any database or on the Medusa server.
+You can use the `SessionProvider` as a lightweight client-side cart functionality. It’s not stored in any database or on the Medusa backend.
To use `SessionProvider`, you first have to insert it somewhere in your component tree below the `MedusaProvider`.
diff --git a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md b/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md
similarity index 84%
rename from docs/content/advanced/backend/shipping/add-fulfillment-provider.md
rename to docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md
index a451aafc839fb..3ba9c30c8beb1 100644
--- a/docs/content/advanced/backend/shipping/add-fulfillment-provider.md
+++ b/docs/content/modules/carts-and-checkout/backend/add-fulfillment-provider.md
@@ -1,19 +1,19 @@
---
-description: 'Learn how to create a fulfillment provider in the Medusa server. This guide explains the different methods in the fulfillment provider.'
+description: 'Learn how to create a fulfillment provider in the Medusa backend. This guide explains the different methods in the fulfillment provider.'
addHowToData: true
---
# How to Add a Fulfillment Provider
-In this document, you’ll learn how to add a fulfillment provider to a Medusa server. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](overview.md).
+In this document, you’ll learn how to add a fulfillment provider to a Medusa backend. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](../shipping.md).
## Overview
A fulfillment provider is the shipping provider used to fulfill orders and deliver them to customers. An example of a fulfillment provider is FedEx.
-By default, a Medusa Server has a `manual` fulfillment provider which has minimal implementation. It allows you to accept orders and fulfill them manually. However, you can integrate any fulfillment provider into Medusa, and your fulfillment provider can interact with third-party shipping providers.
+By default, a Medusa Backend has a `manual` fulfillment provider which has minimal implementation. It allows you to accept orders and fulfill them manually. However, you can integrate any fulfillment provider into Medusa, and your fulfillment provider can interact with third-party shipping providers.
-Adding a fulfillment provider is as simple as creating one [service](../services/create-service.md) file in `src/services`. A fulfillment provider is essentially a service that extends the `FulfillmentService`. It requires implementing 4 methods:
+Adding a fulfillment provider is as simple as creating one [service](../../../development/services/create-service.md) file in `src/services`. A fulfillment provider is essentially a service that extends the `FulfillmentService`. It requires implementing 4 methods:
1. `getFulfillmentOptions`: used to retrieve available fulfillment options provided by this fulfillment provider.
2. `validateOption`: used to validate the shipping option when it’s being created by the admin.
@@ -22,7 +22,7 @@ Adding a fulfillment provider is as simple as creating one [service](../services
Also, the fulfillment provider class should have a static property `identifier`. It is the name that will be used to install and refer to the fulfillment provider throughout Medusa.
-Fulfillment providers are loaded and installed on the server startup.
+Fulfillment providers are loaded and installed on the backend startup.
---
@@ -44,7 +44,7 @@ Fulfillment provider services must extend the `FulfillmentService` class importe
:::note
-Following the naming convention of Services, the name of the file should be the slug name of the fulfillment provider, and the name of the class should be the camel case name of the fulfillment provider suffixed with “Service”. You can learn more in the [service documentation](../services/create-service.md).
+Following the naming convention of Services, the name of the file should be the slug name of the fulfillment provider, and the name of the class should be the camel case name of the fulfillment provider suffixed with “Service”. You can learn more in the [service documentation](../../../development/services/create-service.md).
:::
@@ -54,7 +54,7 @@ As mentioned in the overview, fulfillment providers should have a static `identi
The `FulfillmentProvider` entity has 2 properties: `identifier` and `is_installed`. The `identifier` property in the class will be used when the fulfillment provider is created in the database.
-The value of this property will also be used to reference the fulfillment provider throughout Medusa. For example, it is used to [add a fulfillment provider](https://docs.medusajs.com/api/admin/#tag/Region/operation/PostRegionsRegionFulfillmentProviders) to a region.
+The value of this property will also be used to reference the fulfillment provider throughout Medusa. For example, it is used to [add a fulfillment provider](/api/admin/#tag/Region/operation/PostRegionsRegionFulfillmentProviders) to a region.
```ts
import { FulfillmentService } from "medusa-interfaces"
@@ -72,7 +72,7 @@ You can use the `constructor` of your fulfillment provider to have access to dif
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
-Additionally, if you’re creating your fulfillment 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.
+Additionally, if you’re creating your fulfillment provider as an external plugin to be installed on any Medusa backend 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.
For example:
@@ -118,7 +118,7 @@ For that reason, the fulfillment option doesn't have any required structure and
### validateOption
-Once the admin creates the shipping option, the data will be validated first using this method in the underlying fulfillment provider of that shipping option. This method is called when a `POST` request is sent to [`/admin/shipping-options`](https://docs.medusajs.com/api/admin/#tag/Shipping-Option/operation/PostShippingOptions).
+Once the admin creates the shipping option, the data will be validated first using this method in the underlying fulfillment provider of that shipping option. This method is called when a `POST` request is sent to [`/admin/shipping-options`](/api/admin/#tag/Shipping-Option/operation/PostShippingOptions).
This method accepts the `data` object that is sent in the body of the request. You can use this data to validate the shipping option before it is saved.
@@ -141,7 +141,7 @@ If your fulfillment provider does not need to run any validation, you can simply
When the customer chooses a shipping option on checkout, the shipping option and its data are validated before the shipping method is created.
-`validateFulfillmentOption` is called when a `POST` request is sent to [`/carts/:id/shipping-methods`](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
+`validateFulfillmentOption` is called when a `POST` request is sent to [`/carts/:id/shipping-methods`](/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
This method accepts three parameters:
@@ -221,7 +221,7 @@ If this method returns `true`, that means that the price should be calculated dy
If the method returns `false`, an error is thrown as it means the selected shipping option can only be chosen if the price type is set to `flat_rate`.
-This method receives as a parameter the `data` object sent with the request that [creates the shipping option.](https://docs.medusajs.com/api/admin/#tag/Shipping-Option/operation/PostShippingOptions) You can use this data to determine whether the shipping option should be calculated or not. This is useful if the fulfillment provider you are integrating has both flat rate and dynamically priced fulfillment options.
+This method receives as a parameter the `data` object sent with the request that [creates the shipping option.](/api/admin/#tag/Shipping-Option/operation/PostShippingOptions) You can use this data to determine whether the shipping option should be calculated or not. This is useful if the fulfillment provider you are integrating has both flat rate and dynamically priced fulfillment options.
For example:
@@ -241,7 +241,7 @@ This method is called on checkout when the shipping method is being created if t
This method receives three parameters:
1. The `data` parameter of the selected shipping option.
-2. The `data` parameter sent with [the request](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
+2. The `data` parameter sent with [the request](/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
3. The customer’s cart data.
If your fulfillment provider does not provide any dynamically calculated rates you can keep the function empty:
@@ -270,7 +270,7 @@ class MyFulfillmentService extends FulfillmentService {
Fulfillment providers can also be used to return products. A shipping option can be used for returns if the `is_return` property is `true` or if an admin creates a Return Shipping Option from the settings.
-This method is called when the admin [creates a return request](https://docs.medusajs.com/api/admin/#tag/Order/operation/PostOrdersOrderReturns) for an order or when the customer [creates a return of their order](https://docs.medusajs.com/api/store/#tag/Return/operation/PostReturns).
+This method is called when the admin [creates a return request](/api/admin/#tag/Order/operation/PostOrdersOrderReturns) for an order or when the customer [creates a return of their order](/api/store/#tag/Return/operation/PostReturns).
It gives you access to the return being created in case you need to perform any additional actions with the third-party provider.
diff --git a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md b/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md
similarity index 85%
rename from docs/content/advanced/backend/payment/how-to-create-payment-provider.md
rename to docs/content/modules/carts-and-checkout/backend/add-payment-provider.md
index 46406c3618082..f129f59afc1a7 100644
--- a/docs/content/advanced/backend/payment/how-to-create-payment-provider.md
+++ b/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md
@@ -1,11 +1,11 @@
---
-description: 'Learn how to create a payment provider in the Medusa server. This guide explains the different methods available in a fulfillment provider.'
+description: 'Learn how to create a payment provider in the Medusa backend. This guide explains the different methods available in a fulfillment provider.'
addHowToData: true
---
# How to Create a Payment Provider
-In this document, you’ll learn how to add a Payment Provider to your Medusa server. If you’re unfamiliar with the Payment architecture in Medusa, make sure to check out the [overview](./overview.md) first.
+In this document, you’ll learn how to add a Payment Provider to your Medusa backend. If you’re unfamiliar with the Payment architecture in Medusa, make sure to check out the [overview](../payment.md) first.
## Overview
@@ -13,13 +13,13 @@ A Payment Provider is the payment method used to authorize, capture, and refund
By default, Medusa has a [manual payment provider](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) that has minimal implementation. It can be synonymous with a Cash on Delivery payment method. It allows store operators to manage the payment themselves but still keep track of its different stages on Medusa.
-Adding a Payment Provider is as simple as creating a [service](../services/create-service.md) file in `src/services`. A Payment Provider is essentially a service that extends `AbstractPaymentService` from the core Medusa package `@medusajs/medusa`.
+Adding a Payment Provider is as simple as creating a [service](../../../development/services/create-service.md) file in `src/services`. A Payment Provider is essentially a service that extends `AbstractPaymentService` from the core Medusa package `@medusajs/medusa`.
-Payment Provider Services must have a static property `identifier`. It's the name that will be used to install and refer to the Payment Provider in the Medusa server.
+Payment Provider Services must have a static property `identifier`. It's the name that will be used to install and refer to the Payment Provider in the Medusa backend.
:::tip
-Payment Providers are loaded and installed at the server startup.
+Payment Providers are loaded and installed at the backend startup.
:::
@@ -29,7 +29,7 @@ The Payment Provider service is also required to implement the following methods
2. `retrievePayment`: Used to retrieve payment data from the third-party provider, if there’s any.
3. `getStatus`: Used to get the status of a Payment or Payment Session.
4. `updatePayment`: Used to update the Payment Session whenever the cart and its related data are updated.
-5. `updatePaymentData`: Used to update the `data` field of Payment Sessions. Specifically called when a request is sent to the [Update Payment Session](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) endpoint.
+5. `updatePaymentData`: Used to update the `data` field of Payment Sessions. Specifically called when a request is sent to the [Update Payment Session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) endpoint.
6. `deletePayment`: Used to perform any action necessary before a Payment Session is deleted.
7. `authorizePayment`: Used to authorize the payment amount of the cart before the order or swap is created.
8. `getPaymentData`: Used to retrieve the data that should be stored in the `data` field of a new Payment instance after the payment amount has been authorized.
@@ -45,7 +45,7 @@ All these methods must be declared async in the Payment Provider Service.
These methods are used at different points in the Checkout flow as well as when processing the order after it’s placed.
-
+
---
@@ -68,7 +68,9 @@ class MyPaymentService extends AbstractPaymentService {
protected manager_: EntityManager
protected transactionManager_: EntityManager | undefined
- async getPaymentData(paymentSession: PaymentSession): Promise {
+ async getPaymentData(
+ paymentSession: PaymentSession
+ ): Promise {
throw new Error("Method not implemented.")
}
async updatePaymentData(
@@ -94,7 +96,10 @@ class MyPaymentService extends AbstractPaymentService {
async authorizePayment(
paymentSession: PaymentSession,
context: Data
- ): Promise<{ data: PaymentSessionData; status: PaymentSessionStatus }> {
+ ): Promise<{
+ data: PaymentSessionData;
+ status: PaymentSessionStatus
+ }> {
throw new Error("Method not implemented.")
}
async capturePayment(payment: Payment): Promise {
@@ -109,7 +114,9 @@ class MyPaymentService extends AbstractPaymentService {
async cancelPayment(payment: Payment): Promise {
throw new Error("Method not implemented.")
}
- async deletePayment(paymentSession: PaymentSession): Promise {
+ async deletePayment(
+ paymentSession: PaymentSession
+ ): Promise {
throw new Error("Method not implemented.")
}
async getStatus(data: Data): Promise {
@@ -127,7 +134,7 @@ Payment Providers must extend `AbstractPaymentService` from the core Medusa pack
:::tip
-Following the naming convention of Services, the name of the file should be the slug name of the Payment Provider, and the name of the class should be the camel case name of the Payment Provider suffixed with “Service”. In the example above, the name of the file should be `my-payment.js`. You can learn more in the [service documentation](../services/create-service.md).
+Following the naming convention of Services, the name of the file should be the slug name of the Payment Provider, and the name of the class should be the camel case name of the Payment Provider suffixed with “Service”. In the example above, the name of the file should be `my-payment.js`. You can learn more in the [service documentation](../../../development/services/create-service.md).
:::
@@ -137,7 +144,7 @@ As mentioned in the overview, Payment Providers should have a static `identifie
The `PaymentProvider` entity has 2 properties: `identifier` and `is_installed`. The value of the `identifier` property in the class will be used when the Payment Provider is created in the database.
-The value of this property will also be used to reference the Payment Provider throughout the Medusa server. For example, the identifier is used when a [Payment Session in a cart is selected on checkout](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSession).
+The value of this property will also be used to reference the Payment Provider throughout the Medusa backend. For example, the identifier is used when a [Payment Session in a cart is selected on checkout](/api/store/#tag/Cart/operation/PostCartsCartPaymentSession).
### constructor
@@ -145,7 +152,7 @@ You can use the `constructor` of your Payment Provider to have access to diffe
You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.
-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:
+Additionally, if you’re creating your Payment Provider as an external plugin to be installed on any Medusa backend 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
class MyPaymentService extends AbstractPaymentService {
@@ -160,7 +167,7 @@ class MyPaymentService extends AbstractPaymentService {
### createPayment
-This method is called during checkout when [Payment Sessions are initialized](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions) to present payment options to the customer. It is used to allow you to make any necessary calls to the third-party provider to initialize the payment.
+This method is called during checkout when [Payment Sessions are initialized](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessions) to present payment options to the customer. It is used to allow you to make any necessary calls to the third-party provider to initialize the payment.
For example, in Stripe this method is used to initialize a Payment Intent for the customer.
@@ -192,20 +199,25 @@ This method must return an object of type `PaymentSessionResponse`. It should ha
```ts
type PaymentSessionResponse = {
- update_requests: { customer_metadata: Record }
+ update_requests: {
+ customer_metadata: Record
+ }
session_data: Record
}
```
Where:
-- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point.
+- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](../payment.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point.
- `update_requests` is an object that can be used to pass data from the payment provider plugin to the core to update internal resources. Currently, it only has one attribute `customer_metadata` which allows updating the `metadata` field of the customer.
An example of a minimal implementation of `createPayment`:
```ts
-import { PaymentContext, PaymentSessionResponse } from "@medusajs/medusa"
+import {
+ PaymentContext,
+ PaymentSessionResponse,
+} from "@medusajs/medusa"
class MyPaymentService extends AbstractPaymentService {
// ...
@@ -281,7 +293,7 @@ This code block assumes the status is stored in the `data` field as demonstrated
### updatePayment
-This method is used to perform any necessary updates on the payment. This method is called whenever the cart or any of its related data is updated. For example, when a [line item is added to the cart](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartLineItems) or when a [shipping method is selected](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
+This method is used to perform any necessary updates on the payment. This method is called whenever the cart or any of its related data is updated. For example, when a [line item is added to the cart](/api/store/#tag/Cart/operation/PostCartsCartLineItems) or when a [shipping method is selected](/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
:::tip
@@ -319,14 +331,16 @@ This method must return an object of type `PaymentSessionResponse`. It should ha
```ts
type PaymentSessionResponse = {
- update_requests: { customer_metadata: Record }
+ update_requests: {
+ customer_metadata: Record
+ }
session_data: Record
}
```
Where:
-- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point.
+- `session_data` is the data that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](../payment.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point.
- `update_requests` is an object that can be used to request from the Medusa core to update internal resources. Currently, it only has one attribute `customer_metadata` which allows updating the `metadata` field of the customer.
An example of a minimal implementation of `updatePayment`:
@@ -357,7 +371,7 @@ class MyPaymentService extends AbstractPaymentService {
### updatePaymentData
-This method is used to update the `data` field of a Payment Session. Particularly, it is called when a request is sent to the [Update Payment Session](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) endpoint. This endpoint receives a `data` object in the body of the request that should be used to update the existing `data` field of the Payment Session.
+This method is used to update the `data` field of a Payment Session. Particularly, it is called when a request is sent to the [Update Payment Session](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionUpdate) endpoint. This endpoint receives a `data` object in the body of the request that should be used to update the existing `data` field of the Payment Session.
This method accepts the current `data` field of the Payment Session as the first parameter, and the new `data` field sent in the body request as the second parameter.
@@ -386,8 +400,8 @@ class MyPaymentService extends AbstractPaymentService {
This method is used to perform any actions necessary before a Payment Session is deleted. The Payment Session is deleted in one of the following cases:
-1. When a request is sent to [delete the Payment Session](https://docs.medusajs.com/api/store/#tag/Cart/operation/DeleteCartsCartPaymentSessionsSession).
-2. When the [Payment Session is refreshed](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionsSession). The Payment Session is deleted so that a newer one is initialized instead.
+1. When a request is sent to [delete the Payment Session](/api/store/#tag/Cart/operation/DeleteCartsCartPaymentSessionsSession).
+2. When the [Payment Session is refreshed](/api/store/#tag/Cart/operation/PostCartsCartPaymentSessionsSession). The Payment Session is deleted so that a newer one is initialized instead.
3. When the Payment Provider is no longer available. This generally happens when the store operator removes it from the available Payment Provider in the admin.
4. When the region of the store is changed based on the cart information and the Payment Provider is not available in the new region.
@@ -403,7 +417,9 @@ import { PaymentSession } from "@medusajs/medusa"
class MyPaymentService extends AbstractPaymentService {
// ...
- async deletePayment(paymentSession: PaymentSession): Promise {
+ async deletePayment(
+ paymentSession: PaymentSession
+ ): Promise {
return
}
}
@@ -411,7 +427,7 @@ class MyPaymentService extends AbstractPaymentService {
### authorizePayment
-This method is used to authorize payment using the Payment Session for an order. This is called when the [cart is completed](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartComplete) and before the order is created.
+This method is used to authorize payment using the Payment Session for an order. This is called when the [cart is completed](/api/store/#tag/Cart/operation/PostCartsCartComplete) and before the order is created.
This method is also used for authorizing payments of a swap of an order.
@@ -430,7 +446,7 @@ The payment authorization status is determined using the `getStatus` method as m
This method accepts the Payment Session as an object for its first parameter, and a `context` object as a second parameter. The `context` object contains the following properties:
1. `ip`: The customer’s IP.
-2. `idempotency_key`: The [Idempotency Key](./overview.md#idempotency-key) that is associated with the current cart. It is useful when retrying payments, retrying checkout at a failed point, or for payments that require additional actions from the customer.
+2. `idempotency_key`: The [Idempotency Key](../payment.md#idempotency-key) that is associated with the current cart. It is useful when retrying payments, retrying checkout at a failed point, or for payments that require additional actions from the customer.
This method must return an object containing the property `status` which is a string that indicates the current status of the payment, and the property `data` which is an object containing any additional information required to perform additional payment processing such as capturing the payment. The values of both of these properties are stored in the Payment Session’s `status` and `data` fields respectively.
@@ -452,7 +468,10 @@ class MyPaymentService extends AbstractPaymentService {
async authorizePayment(
paymentSession: PaymentSession,
context: Data
- ): Promise<{ data: PaymentSessionData; status: PaymentSessionStatus }> {
+ ): Promise<{
+ data: PaymentSessionData;
+ status: PaymentSessionStatus
+ }> {
return {
status: PaymentSessionStatus.AUTHORIZED,
data: {
@@ -479,7 +498,9 @@ import { Data, PaymentSession } from "@medusajs/medusa"
class MyPaymentService extends AbstractPaymentService {
// ...
- async getPaymentData(paymentSession: PaymentSession): Promise {
+ async getPaymentData(
+ paymentSession: PaymentSession
+ ): Promise {
return paymentSession.data
}
}
@@ -583,7 +604,7 @@ class MyPaymentService extends AbstractPaymentService {
This method can be added to your Payment Provider service if your third-party provider supports saving the customer’s payment methods. Please note that in Medusa there is no way to save payment methods.
-This method is called when a request is sent to [Retrieve Saved Payment Methods](https://docs.medusajs.com/api/store/#tag/Customer/operation/GetCustomersCustomerPaymentMethods).
+This method is called when a request is sent to [Retrieve Saved Payment Methods](/api/store/#tag/Customer/operation/GetCustomersCustomerPaymentMethods).
This method accepts the customer as an object for its first parameter.
@@ -591,7 +612,7 @@ 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.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.
+If you’re using Medusa’s [Next.js](../../../starters/nextjs-medusa-starter.mdx) storefront starter, 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.
:::
@@ -604,11 +625,14 @@ import { Customer, Data } from "@medusajs/medusa"
class MyPaymentService extends AbstractPaymentService {
// ...
/**
- * Fetches a customers saved payment methods if registered in Stripe.
+ * Fetches a customers saved payment methods
+ * if they're saved in Stripe.
* @param {object} customer - customer to fetch saved cards for
* @return {Promise>} saved payments methods
*/
- async retrieveSavedMethods(customer: Customer): Promise {
+ async retrieveSavedMethods(
+ customer: Customer
+ ): Promise {
if (customer.metadata && customer.metadata.stripe_id) {
const methods = await this.stripe_.paymentMethods.list({
customer: customer.metadata.stripe_id,
@@ -628,4 +652,3 @@ class MyPaymentService extends AbstractPaymentService {
## 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/modules/carts-and-checkout/overview.mdx b/docs/content/modules/carts-and-checkout/overview.mdx
new file mode 100644
index 0000000000000..edd410f467f3d
--- /dev/null
+++ b/docs/content/modules/carts-and-checkout/overview.mdx
@@ -0,0 +1,172 @@
+---
+description: "A cart is a virtual shopping basket that customers can use to pick products they want to purchase. Learn about the available features and guides."
+---
+
+import DocCardList from '@theme/DocCardList';
+import Icons from '@theme/Icon';
+
+# Carts and Checkout
+
+A cart is a virtual shopping basket that customers can use to pick products they want to purchase. Checkout is the process of the customer placing an order. This overview introduces the available features related to carts and checkout.
+
+## Features
+
+### Cart Management
+
+Customers can manage their cart including adding, updating, and removing items from the cart.
+
+
+
+### Shipping and Payment
+
+Developers can integrate any third-party provider or custom logic to offer shipping and payment options for customers during checkout. They can integrate them using existing plugins or by creating their own.
+
+Admins can specify available shipping and payment providers during checkout for customers based on their [Region](../regions-and-currencies/overview.mdx).
+
+
+
+### Checkout Flow
+
+Developers can implement a seamless checkout flow that include steps related to shipping and payment, tax calculation, and more.
+
+Customers can place orders using the checkout flow.
+
+
+
+---
+
+## Understand the Architecture
+
+Learn how cart-related entities are build, their relation to other modules, and more.
+
+
+
+---
+
+## Related Modules
+
+Discover Carts and Checkout’s relation to other modules in Medusa
+
+
\ No newline at end of file
diff --git a/docs/content/advanced/backend/payment/overview.md b/docs/content/modules/carts-and-checkout/payment.md
similarity index 81%
rename from docs/content/advanced/backend/payment/overview.md
rename to docs/content/modules/carts-and-checkout/payment.md
index f146244bdce3b..b345c8ea9bedc 100644
--- a/docs/content/advanced/backend/payment/overview.md
+++ b/docs/content/modules/carts-and-checkout/payment.md
@@ -1,5 +1,5 @@
---
-description: 'Learn about the payment architecture in the Medusa server. The payment architecture refers to all operations in the ecommerce store related to processing payments.'
+description: 'Learn about the payment architecture in the Medusa backend. The payment architecture refers to all operations in the ecommerce store related to processing payments.'
---
# Payment Architecture Overview
@@ -30,13 +30,13 @@ Payment Providers can also be related to a custom way of handling payment operat
### How Payment Provider is Created
-A Payment Provider is essentially a Medusa [service](../services/create-service.md) with a unique identifier, and it extends the ``AbstractPaymentService` from the core Medusa package `@medusajs/medusa`. It can be created as part of a [plugin](../plugins/overview.md), or it can be created just as a service file in your Medusa server.
+A Payment Provider is essentially a Medusa [service](../../development/services/create-service.md) with a unique identifier, and it extends the ``AbstractPaymentService` from the core Medusa package `@medusajs/medusa`. It can be created as part of a [plugin](../../development/plugins/overview.mdx), or it can be created just as a service file in your Medusa backend.
As a developer, you will mainly work with the Payment Provider when integrating a payment method in Medusa.
-When you run your Medusa server, the Payment Provider will be registered on your server if it hasn’t been already.
+When you run your Medusa backend, the Payment Provider will be registered on your backend 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.mdx) 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 backend, 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
@@ -46,7 +46,7 @@ It’s important to choose a payment provider in the list of payment providers i
### PaymentProvider Entity Overview
-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.
+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.
---
@@ -70,7 +70,7 @@ Among the Payment Sessions available only one will be selected based on the cust
### PaymentSession Entity Overview
-The [`PaymentSession`](../../../references/entities/classes/PaymentSession.md) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
+The [`PaymentSession`](../../references/entities/classes/PaymentSession.md) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
The `PaymentSession` also belongs to a `PaymentProvider`. This is the Payment Provider that was used to create the Payment Session and that controls it for further actions like authorizing the payment.
@@ -104,7 +104,7 @@ When the store operator then chooses to capture the order from the Medusa Admin,
### Payment Entity Overview
-The [`Payment`](../../../references/entities/classes/Payment.md) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment provider that the customer chose on checkout.
+The [`Payment`](../../references/entities/classes/Payment.md) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment provider that the customer chose on checkout.
In case a `Swap` is created for an order, `Payment` will be associated with that swap to handle payment operations related to it.
@@ -124,7 +124,7 @@ That Idempotency Key is then set in the header under the `Idempotency-Key` respo
If an error occurs or the purchase is interrupted at any step, the client can retry the payment by adding the Idempotency Key of the cart as the `Idempotency-Key` header field in their subsequent requests.
-The server wraps each essential part of the checkout completion in its own step and stores the current step of checkout with its associated Idempotency Key.
+The backend wraps each essential part of the checkout completion in its own step and stores the current step of checkout with its associated Idempotency Key.
If then the request is interrupted for any reason or the payment fails, the client can retry completing the check out using the Idempotency Key, and the flow will continue from the last stored step.
@@ -134,5 +134,5 @@ This prevents any payment issues from occurring with the customers and allows fo
## 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)
+- [Available Payment Plugins](../../plugins/payment/index.mdx)
+- [Create a Payment Provider](./backend/add-payment-provider.md)
\ No newline at end of file
diff --git a/docs/content/advanced/backend/shipping/overview.md b/docs/content/modules/carts-and-checkout/shipping.md
similarity index 83%
rename from docs/content/advanced/backend/shipping/overview.md
rename to docs/content/modules/carts-and-checkout/shipping.md
index a12fb128d76bd..bb64b96451345 100644
--- a/docs/content/advanced/backend/shipping/overview.md
+++ b/docs/content/modules/carts-and-checkout/shipping.md
@@ -1,5 +1,5 @@
---
-description: 'Learn how the shipping architecture is implemented in the Medusa server. This includes an overview of what the Fulfillment Provider, Shipping Profile, Shipping Option, and Shipping Methods.'
+description: 'Learn how the shipping architecture is implemented in the Medusa backend. This includes an overview of what the Fulfillment Provider, Shipping Profile, Shipping Option, and Shipping Methods.'
---
# Shipping Architecture Overview
@@ -18,12 +18,12 @@ It’s also constructed to support multiple regions, provide different shipment
## 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.
+- **Fulfillment Provider:** Fulfillment providers are plugins or [Services](../../development/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.
- **Shipping Profiles:** created by the admin. They are used to group products that should be shipped in a different manner than the default. Shipping profiles can have multiple shipping options.
- **Shipping Options:** created by the admin and belong to a shipping profile. They are specific to certain regions and can have cart conditions. They use an underlying fulfillment provider. Once a customer checks out, they can choose the shipping option that’s available and most relevant to them.
- **Shipping Method:** created when the customer chooses a shipping option on checkout. The shipping method is basically a copy of the shipping option, but with values specific to the customer and the cart it’s associated with. When the order is placed, the shipping method will then be associated with the order and fulfilled based on the integration with the fulfillment provider.
-
+
---
@@ -39,17 +39,17 @@ Fulfillment Providers can also be related to a custom way of handling fulfillmen
### How Fulfillment Provider is Created
-A Fulfillment Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the `FulfillmentService` provided by the `medusa-interfaces` package. It can be created as part of a [plugin](../plugins/overview.md), or it can be created just as a Service file in your Medusa server.
+A Fulfillment Provider is essentially a Medusa [Service](../../development/services/create-service.md) with a unique identifier, and it extends the `FulfillmentService` provided by the `medusa-interfaces` package. It can be created as part of a [plugin](../../development/plugins/overview.mdx), or it can be created just as a Service file in your Medusa backend.
As a developer, you will mainly work with the Fulfillment Provider when integrating a fulfillment method in Medusa.
-When you run your Medusa server, the Fulfillment Provider will be registered on your server if it hasn’t been already.
+When you run your Medusa backend, the Fulfillment Provider will be registered on your backend 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.mdx) the Fulfillment Provider with shipping options.
+Once the Fulfillment Provider is added to the backend, the store operator will be able to associate on the [Medusa Admin](../../development/backend/install.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.
+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.
---
@@ -73,7 +73,7 @@ For example, shipping heavy items might be more expensive than others, which wou
### ShippingProfile Entity Overview
-The [`ShippingProfile`](../../../references/entities/classes/ShippingProfile.md) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
+The [`ShippingProfile`](../../references/entities/classes/ShippingProfile.md) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
The `ShippingProfile` has a `type` attribute that can be `default`, `gift_card`, or `custom`.
@@ -101,7 +101,7 @@ Think of a shipping option as a template defined by the admin that indicates wha
### ShippingOption Entity Overview
-The [`ShippingOption`](../../../references/entities/classes/ShippingOption.md) entity belongs to the `ShippingProfile` entity.
+The [`ShippingOption`](../../references/entities/classes/ShippingOption.md) entity belongs to the `ShippingProfile` entity.
The `ShippingOption` entity also belongs to a `FulfillmentProvider`. This can be either a custom third-party provider or one of Medusa’s default fulfillment providers.
@@ -139,7 +139,7 @@ This separation allows for developers to implement the custom integration with t
A lot of the shipping method’s attributes are similar to the shipping option’s attribute.
-The [`ShippingMethod`](../../../references/entities/classes/ShippingMethod.md) entity belongs to a `ShippingOption`.
+The [`ShippingMethod`](../../references/entities/classes/ShippingMethod.md) entity belongs to a `ShippingOption`.
Similar to the `data` attribute explained for the `ShippingOption` entity, a `ShippingMethod` has a similar `data` attribute that includes all the data to be sent to the fulfillment provider when fulfilling the order.
@@ -153,5 +153,5 @@ The `ShippingMethod` instance holds a `price` attribute, which will either b
## See Also
-- [Create a Fulfillment Provider](./add-fulfillment-provider.md)
+- [Create a Fulfillment Provider](./backend/add-fulfillment-provider.md)
- [Available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages)
diff --git a/docs/content/guides/carts-in-medusa.mdx b/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx
similarity index 87%
rename from docs/content/guides/carts-in-medusa.mdx
rename to docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx
index 5e3357024b74a..b70387bb2b730 100644
--- a/docs/content/guides/carts-in-medusa.mdx
+++ b/docs/content/modules/carts-and-checkout/storefront/implement-cart.mdx
@@ -18,7 +18,7 @@ This document helps you understand how to add the cart functionality to your sto
:::note
-This document does not cover implementing the checkout flow. You can refer to [this documentation instead to learn how to implement the checkout flow](../advanced/storefront/how-to-implement-checkout-flow.mdx).
+This document does not cover implementing the checkout flow. You can refer to [this documentation instead to learn how to implement the checkout flow](./implement-checkout-flow.mdx).
:::
@@ -28,23 +28,23 @@ This document does not cover implementing the checkout flow. You can refer to [t
### 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's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [quickstart guide](../../../development/backend/install.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.
+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 the [Next.js starter storefront](../../../starters/nextjs-medusa-starter.mdx).
### JS Client
-This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, among other methods.
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
-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).
+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).
### Medusa React
-This guide also includes code snippets to send requests to your Medusa server using Medusa React, among other methods.
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
-If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../medusa-react/overview.md#usage).
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
-It's also assumed you already have [used CartProvider higher in your component tree](../medusa-react/overview.md#cartprovider).
+It's also assumed you already have [used CartProvider higher in your component tree](../../../medusa-react/overview.md#cartprovider).
---
@@ -77,7 +77,9 @@ const Cart = () => {
createCart.mutate(
{}, // create an empty cart
{
- onSuccess: ({ cart }) => localStorage.setItem("cart_id", cart.id),
+ onSuccess: ({ cart }) => {
+ localStorage.setItem("cart_id", cart.id)
+ },
}
)
}
@@ -92,7 +94,7 @@ export default Cart
```ts
-fetch(`/store/carts`, {
+fetch(`/store/carts`, {
method: "POST",
credentials: "include",
})
@@ -142,7 +144,9 @@ const Cart = () => {
region_id,
},
{
- onSuccess: ({ cart }) => localStorage.setItem("cart_id", cart.id),
+ onSuccess: ({ cart }) => {
+ localStorage.setItem("cart_id", cart.id)
+ },
}
)
}
@@ -157,7 +161,7 @@ export default Cart
```jsx
-fetch(`/store/carts`, {
+fetch(`/store/carts`, {
method: "POST",
credentials: "include",
headers: {
@@ -178,7 +182,7 @@ fetch(`/store/carts`, {
-Check out the [API Reference](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCart) for a full list of available request body parameters.
+Check out the [API Reference](/api/store/#tag/Cart/operation/PostCart) for a full list of available request body parameters.
:::note
@@ -228,7 +232,7 @@ export default Cart
const id = localStorage.getItem("cart_id")
if (id) {
- fetch(`/store/carts/${id}`, {
+ fetch(`/store/carts/${id}`, {
credentials: "include",
})
.then((response) => response.json())
@@ -241,7 +245,7 @@ if (id) {
This request accepts the ID of the cart as a path parameter and returns the cart of that ID.
-You can run this code snippet every time the storefront is opened. If a customer has a cart ID stored in their local storage, it’s loaded from the server.
+You can run this code snippet every time the storefront is opened. If a customer has a cart ID stored in their local storage, it’s loaded from the backend.
:::tip
@@ -294,7 +298,7 @@ export default Cart
```ts
-fetch(`/store/carts/${cartId}`, {
+fetch(`/store/carts/${cartId}`, {
method: "POST",
credentials: "include",
headers: {
@@ -315,7 +319,7 @@ This request accepts the ID of the cart as a path parameter. In its body, you ca
It returns the updated cart.
-Check out the full list of available request body parameters in the [API Reference](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCart).
+Check out the full list of available request body parameters in the [API Reference](/api/store/#tag/Cart/operation/PostCartsCart).
### Associate a Logged-In Customer with the Cart
@@ -360,7 +364,7 @@ export default Cart
```ts
-fetch(`/store/carts/${cartId}`, {
+fetch(`/store/carts/${cartId}`, {
method: "POST",
credentials: "include",
headers: {
@@ -422,7 +426,7 @@ export default Cart
```ts
-fetch(`/store/carts/${cartId}`, {
+fetch(`/store/carts/${cartId}`, {
method: "POST",
credentials: "include",
headers: {
@@ -484,7 +488,7 @@ export default Cart
```jsx
-fetch(`/store/carts/${cartId}/line-items`, {
+fetch(`/store/carts/${cartId}/line-items`, {
method: "POST",
credentials: "include",
headers: {
@@ -557,8 +561,10 @@ export default Cart
+
+
```ts
-fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
+fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
method: "POST",
credentials: "include",
headers: {
@@ -619,8 +625,10 @@ export default Cart
+
+
```ts
-fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
+fetch(`/store/carts/${cartId}/line-items/${lineItemId}`, {
method: "DELETE",
credentials: "include",
})
@@ -639,5 +647,4 @@ It returns the updated cart.
## 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)
+- [Implement the checkout flow in your storefront](./implement-checkout-flow.mdx)
\ No newline at end of file
diff --git a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx b/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx
similarity index 76%
rename from docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx
rename to docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx
index 22d66d070ff31..bf0df098107c6 100644
--- a/docs/content/advanced/storefront/how-to-implement-checkout-flow.mdx
+++ b/docs/content/modules/carts-and-checkout/storefront/implement-checkout-flow.mdx
@@ -18,7 +18,7 @@ This document will take you through the general process of a checkout flow. You
:::note
-It’s recommended to go through the [Shipping Architecture Overview](../backend/shipping/overview.md) and [Payment Architecture Overview](../backend/payment/overview.md) first to have a better understanding of Medusa’s architecture.
+It’s recommended to go through the [Shipping Architecture Overview](../shipping.md) and [Payment Architecture Overview](../payment.md) first to have a better understanding of Medusa’s architecture.
:::
@@ -28,29 +28,29 @@ It’s recommended to go through the [Shipping Architecture Overview](../backend
### 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's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [quickstart guide](../../../development/backend/install.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.
+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 the [Next.js starter storefront](../../../starters/nextjs-medusa-starter.mdx).
### JS Client
-This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client and JavaScript’s Fetch API.
+This guide includes code snippets to send requests to your Medusa backend 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).
+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).
### Medusa React
-This guide also includes code snippets to send requests to your Medusa server using Medusa React, among other methods.
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
-If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../medusa-react/overview.md#usage).
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
-It's also assumed you already have [used CartProvider higher in your component tree](../../medusa-react/overview.md#cartprovider).
+It's also assumed you already have [used CartProvider higher in your component tree](../../../medusa-react/overview.md#cartprovider).
### Previous Steps
This document assumes you’ve already taken care of the add-to-cart flow. So, you should have a [cart created](/api/store/#tag/Cart/operation/PostCart) for the customer with at least [one product in it](/api/store/#tag/Cart/operation/PostCartsCartLineItems).
-You can learn how to implement the cart flow using [this documentation](../../guides/carts-in-medusa.mdx).
+You can learn how to implement the cart flow using [this documentation](./implement-cart.mdx).
---
@@ -96,22 +96,23 @@ const Cart = () => {
const { updateCart } = useCart()
- const addShippingAddress = (address: Record) => {
- updateCart.mutate({
- shipping_address: {
- company: address.company,
- first_name: address.first_name,
- last_name: address.last_name,
- address_1: address.address_1,
- address_2: address.address_2,
- city: address.city,
- country_code: address.country_code,
- province: address.province,
- postal_code: address.postal_code,
- phone: address.phone,
- },
- })
- }
+ const addShippingAddress =
+ (address: Record) => {
+ updateCart.mutate({
+ shipping_address: {
+ company: address.company,
+ first_name: address.first_name,
+ last_name: address.last_name,
+ address_1: address.address_1,
+ address_2: address.address_2,
+ city: address.city,
+ country_code: address.country_code,
+ province: address.province,
+ postal_code: address.postal_code,
+ phone: address.phone,
+ },
+ })
+ }
// ...
}
@@ -123,7 +124,7 @@ export default Cart
```ts
-fetch(`/store/carts/${cartId}`, {
+fetch(`/store/carts/${cartId}`, {
method: "POST",
credentials: "include",
body: JSON.stringify({
@@ -161,7 +162,7 @@ The request returns the updated cart, with the new shipping address available in
### 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.
+After updating the cart with the customer’s address, the list of available [shipping options](../shipping.md#shipping-option) for that cart might change. So, you should retrieve the updated list of options.
You can retrieve the list of shipping options by sending a `GET` request to the [Retrieve Shipping Options for Cart API](/api/store/#tag/Shipping-Option/operation/GetShippingOptionsCartId) endpoint:
@@ -187,7 +188,8 @@ type Props = {
}
const ShippingOptions = ({ cartId }: Props) => {
- const { shipping_options, isLoading } = useCartShippingOptions(cartId)
+ const { shipping_options, isLoading } =
+ useCartShippingOptions(cartId)
return (
@@ -197,9 +199,13 @@ const ShippingOptions = ({ cartId }: Props) => {
)}
{shipping_options && (
- {shipping_options.map((shipping_option: ShippingOption) => (
- - {shipping_option.name}
- ))}
+ {shipping_options.map(
+ (shipping_option: ShippingOption) => (
+ -
+ {shipping_option.name}
+
+ )
+ )}
)}
- {!cart?.payment_sessions.length && No payment providers}
+ {!cart?.payment_sessions.length && (
+ No payment providers
+ )}
- {cart?.payment_sessions.map((paymentSession: PaymentSession) => (
- - {paymentSession.provider_id}
- ))}
+ {cart?.payment_sessions.map(
+ (paymentSession: PaymentSession) => (
+ -
+ {paymentSession.provider_id}
+
+ )
+ )}
| | 
+
+
+