diff --git a/docs/content/advanced/admin/import-products.mdx b/docs/content/advanced/admin/import-products.mdx index 10be36b145..e988e1396a 100644 --- a/docs/content/advanced/admin/import-products.mdx +++ b/docs/content/advanced/admin/import-products.mdx @@ -89,7 +89,7 @@ fetch(`/admin/uploads`, { ```bash curl --location --request POST '/admin/uploads' \ - --header 'Authorization: Bearer {api_token}' \ + --header 'Authorization: Bearer ' \ --header 'Content-Type: text/csv' \ --form 'files=@""' ``` @@ -149,7 +149,7 @@ fetch(`/admin/batch-jobs`, { ```bash curl --location --request POST '/admin/batch-jobs' \ ---header 'Authorization: Bearer {api_token}' \ +--header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "product-import", @@ -210,7 +210,7 @@ fetch(`/admin/batch-jobs/${batchJobId}`) ```bash curl --location --request GET '/admin/batch-jobs/' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' # is the ID of the batch job ``` @@ -271,7 +271,7 @@ fetch(`/admin/batch-jobs/${batchJobId}/confirm`, { ```bash curl --location --request POST '/admin/batch-jobs//confirm' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' # is the ID of the batch job ``` diff --git a/docs/content/advanced/backend/batch-jobs/create.md b/docs/content/advanced/backend/batch-jobs/create.md index 2077ddf357..5822de390b 100644 --- a/docs/content/advanced/backend/batch-jobs/create.md +++ b/docs/content/advanced/backend/batch-jobs/create.md @@ -285,7 +285,7 @@ fetch(`/admin/batch-jobs`, { ```bash # using cURL curl --location --request POST '/admin/batch-jobs' \ ---header 'Authorization: Bearer {api_token}' \ +--header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "type": "publish-products", @@ -322,7 +322,7 @@ fetch(`/admin/batch-jobs/${batchJobId}`) ```bash # using cURL curl --location --request GET '/admin/batch-jobs/' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' # is the ID of the batch job ``` @@ -368,7 +368,7 @@ fetch(`/admin/batch-jobs/${batchJobId}/confirm`, { ```bash # using cURL curl --location --request POST '/admin/batch-jobs//confirm' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' # is the ID of the batch job ``` diff --git a/docs/content/advanced/backend/price-lists/use-api.mdx b/docs/content/advanced/backend/price-lists/use-api.mdx index 5f4fe353a1..10b30f6265 100644 --- a/docs/content/advanced/backend/price-lists/use-api.mdx +++ b/docs/content/advanced/backend/price-lists/use-api.mdx @@ -135,7 +135,7 @@ fetch(`/admin/price-lists`, { ```bash curl --location --request POST '/admin/price-lists' \ ---header 'Authorization: Bearer {api_token}' \ +--header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "New Price List", @@ -198,7 +198,7 @@ fetch(`/admin/price-lists/${priceListId}`) ```jsx curl --location --request GET '/admin/price-lists/{id}' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' ``` @@ -248,7 +248,7 @@ fetch(`/admin/price-lists/${priceListId}`, { ```bash curl --location --request POST '/admin/price-lists/' \ ---header 'Authorization: Bearer {api_token}' \ +--header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "ends_at": "2022-10-11" @@ -322,7 +322,7 @@ fetch(`/admin/price-lists/${priceListId}/prices/batch`, { ```bash curl --location --request POST '/admin/price-lists/' \ ---header 'Authorization: Bearer {api_token}' \ +--header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "prices": [ @@ -374,7 +374,7 @@ fetch(`/admin/price-lists/${priceListId}/products/${productId}/price ```bash curl --location --request DELETE '/admin/price-lists//products//prices' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' ``` @@ -414,7 +414,7 @@ fetch(`/admin/price-lists/${priceListId}/variants/${variantId}/price ```jsx curl --location --request DELETE '/admin/price-lists//variants//prices' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' ``` @@ -456,7 +456,7 @@ fetch(`/admin/price-lists/${priceListId}`, { ```jsx curl --location --request DELETE '/admin/price-lists/' \ ---header 'Authorization: Bearer {api_token}' +--header 'Authorization: Bearer ' ``` diff --git a/docs/content/advanced/backend/sales-channels/index.md b/docs/content/advanced/backend/sales-channels/index.md index c4f57715ed..e2f678975a 100644 --- a/docs/content/advanced/backend/sales-channels/index.md +++ b/docs/content/advanced/backend/sales-channels/index.md @@ -70,4 +70,5 @@ The relation is implemented in the [Order](../../../references/entities/classes/ ## What’s Next 🚀 +- Learn how to [manage Sales Channels using the Admin APIs](./manage-admin.mdx). - Check out the [Sales Channel’s Admin APIs](https://docs.medusajs.com/api/admin/#tag/Sales-Channel). diff --git a/docs/content/advanced/backend/sales-channels/manage-admin.mdx b/docs/content/advanced/backend/sales-channels/manage-admin.mdx new file mode 100644 index 0000000000..72c03cf14b --- /dev/null +++ b/docs/content/advanced/backend/sales-channels/manage-admin.mdx @@ -0,0 +1,522 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Manage Sales Channels + +In this document, you’ll learn how to manage sales channels and their products and orders using the Admin APIs. + +:::note + +If you’re looking to learn more in-depth about what Sales Channels are and how they work, check out [this documentation](./index.md) instead. + +::: + +## Overview + +Using Medusa’s Admin APIs, you can manage Sales Channels including creating, retrieving, updating, and deleting sales channels. You can also manage their products and orders. + +This guide explains how to perform all these operations using the Admin APIs. + +--- + +## Prerequisites + +### Medusa Components + +It's assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started. + +### Enabled Feature Flags + +The Sales Channels feature is currently in beta mode and 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. + +### JS Client + +This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. + +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client installed](../../../js-client/overview.md) and [have created an instance of the client](../../../js-client/overview.md#configuration). + +### Authenticated Admin User + +You must be an authenticated admin user before following along with the steps in this guide. + +You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin/#section/Authentication). + +--- + +## Create Sales Channels + +You can create a sales channel by sending a request to the Create a Sales Channel endpoint: + + + + +```jsx +medusa.admin.salesChannels.create({ + name: 'App', + description: 'Mobile app' +}) +.then(({ sales_channel }) => { + console.log(sales_channel.id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + name: 'App', + description: 'Mobile app' + }) +}) +.then((response) => response.json()) +.then(({ sales_channel }) => { + console.log(sales_channel.id) +}); +``` + + + + +```bash +curl --location --request POST '/admin/sales-channels' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + name: 'App', + description: 'Mobile app' +}' +``` + + + + +This request requires the request body parameters `name`, and optionally accepts the `description` and `is_disabled` request body parameters. + +It returns the created sales channel. + +--- + +## List Sales Channels + +You can list all sales channels by sending a request to the List Sales Channels endpoint: + + + + +```jsx +medusa.admin.salesChannels.list() +.then(({ sales_channels, limit, offset, count }) => { + console.log(sales_channels.length); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels`) +.then((response) => response.json()) +.then(({ sales_channels, limit, offset, count }) => { + console.log(sales_channels.length) +}); +``` + + + + +```bash +curl --location --request GET '/admin/sales-channels' \ +--header 'Authorization: Bearer ' +``` + + + + +This request returns an array of all sales channels in your store. You can also pass query parameters to filter or customize the pagination of the results. Check out [the API Reference for a full list of query parameters.](https://docs.medusajs.com/api/admin/#tag/Sales-Channel/operation/GetSalesChannels) + +--- + +## Retrieve a Sales Channel + +You can retrieve a sales channel’s details by its ID using the Get Sales Channel endpoint: + + + + +```jsx +medusa.admin.salesChannels.retrieve(salesChannelId) +.then(({ sales_channel }) => { + console.log(sales_channel.id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels/${salesChannelId}`) +.then((response) => response.json()) +.then(({ sales_channels, limit, offset, count }) => { + console.log(sales_channels.length) +}); +``` + + + + +```bash +curl --location --request GET '/admin/sales-channels/' \ +--header 'Authorization: Bearer ' +``` + + + + +This request returns the sales channel with the specified ID. + +--- + +## Update a Sales Channel + +You can update a Sales Channel’s details and attributes by sending a request to the Update Sales Channel endpoint: + + + + +```jsx +medusa.admin.salesChannels.update(salesChannelId, { + is_disabled: false +}) +.then(({ sales_channel }) => { + console.log(sales_channel.id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels/${salesChannelId}`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + is_disabled: false + }) +}) +.then((response) => response.json()) +.then(({ sales_channel }) => { + console.log(sales_channel.id) +}); +``` + + + + +```bash +curl --location --request POST '/admin/sales-channels/' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "is_disabled": false +}' +``` + + + + +In this example, you enable a sales channel by changing the value of the `is_disabled` attribute. + +This request returns the updated sales channel. + +You can check out [the API Reference for a full list of body parameters](https://docs.medusajs.com/api/admin/#tag/Sales-Channel/operation/PostSalesChannelsSalesChannel) that you can pass to this request. + +--- + +## Delete a Sales Channel + +You can delete a sales channel by sending a request to the Delete Sales Channel endpoint with the ID of the sales channel to delete: + + + + +```jsx +medusa.admin.salesChannels.delete(salesChannelId) +.then(({ id, object, deleted }) => { + console.log(id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels/${salesChannelId}`, { + method: 'DELETE' +}) +.then((response) => response.json()) +.then(({ id, object, deleted }) => { + console.log(id) +}); +``` + + + + +```bash +curl --location --request DELETE '/admin/sales-channels/' \ +--header 'Authorization: Bearer ' +``` + + + + +The ID of the deleted sales channel is returned in the response. + +--- + +## Manage Products + +### Add Product to a Sales Channel + +To add a product to a sales channel, send a request to the Sales Channel’s Add Products endpoint: + + + + +```jsx +medusa.admin.salesChannels.addProducts(salesChannelId, { + product_ids: [ + { + id: productId + } + ] +}) +.then(({ sales_channel }) => { + console.log(sales_channel.id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels/${salesChannelId}/products/batch`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + product_ids: [ + { + id: productId + } + ] + }) +}) +.then((response) => response.json()) +.then(({ sales_channel }) => { + console.log(sales_channel.id) +}); +``` + + + + +```bash +curl --location --request POST '/admin/sales-channels//products/batch' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "product_ids": [ + { + "id": "" + } + ] +}' +``` + + + + +This request accepts the `product_ids` body parameter, which is an array of objects. Each object in the array must have an `id` property with the ID of the product to add as a value. + +This request returns the sales channel. + +### List Products Available in a Sales Channel + +You can list the products available in a sales channel by sending a request to the List Products endpoint and passing the `sales_channel_id` query parameter to filter by a specific sales channel: + + + + +```jsx +medusa.admin.products.list({ + sales_channel_id: [ + salesChannelId + ] +}) +.then(({ products, limit, offset, count }) => { + console.log(products.length); +}); +``` + + + + +```jsx +fetch(`/admin/products?sales_channel_id[0]=${salesChannelId}`) +.then((response) => response.json()) +.then(({ products, limit, offset, count }) => { + console.log(products.length) +}); +``` + + + + +```bash +curl --location --request GET '/admin/products?sales_channel_id[0]=' \ +--header 'Authorization: Bearer ' +``` + + + + +The request returns an array of products that are available in the specified sales channel. + +### Delete Products from a Sales Channel + +:::info + +Deleting a product from a sales channel doesn't delete it completely. It only makes it unavailable in that sales channel. + +::: + +You can delete a product from a sales channel by sending a request to the Sales Channel’s Delete Products endpoint: + + + + +```jsx +medusa.admin.salesChannels.removeProducts(salesChannelId, { + product_ids: [ + { + id: productId + } + ] +}) +.then(({ sales_channel }) => { + console.log(sales_channel.id); +}); +``` + + + + +```jsx +fetch(`/admin/sales-channels/${salesChannelId}/products/batch`, { + method: 'DELETE', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + product_ids: [ + { + id: productId + } + ] + }) +}) +.then((response) => response.json()) +.then(({ sales_channel }) => { + console.log(sales_channel.id) +}); +``` + + + + +```jsx +curl --location --request DELETE '/admin/sales-channels//products/batch' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "product_ids": [ + { + "id": "" + } + ] +}' +``` + + + + +This request accepts the `product_ids` body parameter, which is an array of objects. Each object in the array must have an `id` property with the ID of the product to delete as a value. + +This request returns the sales channel. + +--- + +## List Orders by Sales Channels + +You can filter orders by a specific sales channel by sending a request to the List Orders endpoint and passing the `sales_channel_id` query parameter to filter by a specific sales channel: + + + + +```jsx +medusa.admin.orders.list({ + sales_channel_id: [ + salesChannelId + ], + limit: 50, + offset: 0 +}) +.then(({ orders, limit, offset, count }) => { + console.log(orders.length); +}); +``` + + + + +```jsx +fetch(`/admin/orders?sales_channel_id[0]=${salesChannelId}`) +.then((response) => response.json()) +.then(({ orders, limit, offset, count }) => { + console.log(orders.length) +}); +``` + + + + +```jsx +curl --location --request GET '/admin/orders?sales_channel_id[0]=' \ +--header 'Authorization: Bearer ' +``` + + + + +The request returns an array of orders that are associated with the specified sales channel. + +--- + +## What’s Next 🚀 + +- Learn more about [Sales Channels and how they work](./index.md). \ No newline at end of file diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 924f0354e9..f20d044baa 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -224,6 +224,11 @@ module.exports = { type: "doc", id: "advanced/backend/price-lists/use-api" }, + { + type: "doc", + id: "advanced/backend/sales-channels/manage-admin", + label: "Manage Sales Channels" + }, ] }, {