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

docs: added how-to guide for "Mange Sales Channels" (#2344)

Browse Source 
* fix id in example

* docs: added admin sales channel how-to guide

* docs: small fixes

* docs: added sidebar link

* revert change in api reference

* added link in conceptual guide
This commit is contained in:
Shahed Nasser
2022-10-05 10:45:51 +03:00
committed by GitHub
parent bd94130916
commit d27d995c51
6 changed files with 542 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/content/advanced/admin/import-products.mdx
View File

@@ -89,7 +89,7 @@ fetch(`<YOUR_SERVER>/admin/uploads`, {
```bash
curl --location --request POST '<YOUR_SERVER>/admin/uploads' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: text/csv' \
--form 'files=@"<FILE_PATH_1>"'
```
@@ -149,7 +149,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs`, {
```bash
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "product-import",
@@ -210,7 +210,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}`)
```bash
curl --location --request GET '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
# <BATCH_JOB_ID> is the ID of the batch job
```
@@ -271,7 +271,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}/confirm`, {
```bash
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>/confirm' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
# <BATCH_JOB_ID> is the ID of the batch job
```

6
docs/content/advanced/backend/batch-jobs/create.md
View File

@@ -285,7 +285,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs`, {
```bash
# using cURL
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "publish-products",
@@ -322,7 +322,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}`)
```bash
# using cURL
curl --location --request GET '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
# <BATCH_JOB_ID> is the ID of the batch job
```
@@ -368,7 +368,7 @@ fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}/confirm`, {
```bash
# using cURL
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>/confirm' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
# <BATCH_JOB_ID> is the ID of the batch job
```

14
docs/content/advanced/backend/price-lists/use-api.mdx
View File

@@ -135,7 +135,7 @@ fetch(`<SERVER_URL>/admin/price-lists`, {
```bash
curl --location --request POST '<YOUR_SERVER_URL>/admin/price-lists' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "New Price List",
@@ -198,7 +198,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}`)
```jsx
curl --location --request GET '<SERVER_URL>/admin/price-lists/{id}' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
@@ -248,7 +248,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}`, {
```bash
curl --location --request POST '<SERVER_URL>/admin/price-lists/<PRICE_LIST_ID>' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"ends_at": "2022-10-11"
@@ -322,7 +322,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}/prices/batch`, {
```bash
curl --location --request POST '<SERVER_URL>/admin/price-lists/<PRICE_LIST_ID>' \
--header 'Authorization: Bearer {api_token}' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"prices": [
@@ -374,7 +374,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}/products/${productId}/price
```bash
curl --location --request DELETE '<SERVER_URL>/admin/price-lists/<PRICE_LIST_ID>/products/<PRODUCT_ID>/prices' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
@@ -414,7 +414,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}/variants/${variantId}/price
```jsx
curl --location --request DELETE '<SERVER_URL>/admin/price-lists/<PRICE_LIST_ID>/variants/<VARIANT_ID>/prices' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
@@ -456,7 +456,7 @@ fetch(`<SERVER_URL>/admin/price-lists/${priceListId}`, {
```jsx
curl --location --request DELETE '<SERVER_URL>/admin/price-lists/<PRICE_LIST_ID>' \
--header 'Authorization: Bearer {api_token}'
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>

1
docs/content/advanced/backend/sales-channels/index.md
View File

@@ -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).

522
docs/content/advanced/backend/sales-channels/manage-admin.mdx Normal file
View File

@@ -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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.create({
name: 'App',
description: 'Mobile app'
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/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)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request POST '<SERVER_URL>/admin/sales-channels' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
name: 'App',
description: 'Mobile app'
}'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.list()
.then(({ sales_channels, limit, offset, count }) => {
console.log(sales_channels.length);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/admin/sales-channels`)
.then((response) => response.json())
.then(({ sales_channels, limit, offset, count }) => {
console.log(sales_channels.length)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request GET '<SERVER_URL>/admin/sales-channels' \
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.retrieve(salesChannelId)
.then(({ sales_channel }) => {
console.log(sales_channel.id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/admin/sales-channels/${salesChannelId}`)
.then((response) => response.json())
.then(({ sales_channels, limit, offset, count }) => {
console.log(sales_channels.length)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request GET '<SERVER_URL>/admin/sales-channels/<SALES_CHANNEL_ID>' \
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.update(salesChannelId, {
is_disabled: false
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/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)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request POST '<SERVER_URL>/admin/sales-channels/<SALES_CHANNEL_ID>' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"is_disabled": false
}'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.delete(salesChannelId)
.then(({ id, object, deleted }) => {
console.log(id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/admin/sales-channels/${salesChannelId}`, {
method: 'DELETE'
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
console.log(id)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request DELETE '<SERVER_URL>/admin/sales-channels/<SALES_CHANNEL_ID>' \
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.addProducts(salesChannelId, {
product_ids: [
{
id: productId
}
]
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/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)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request POST '<SERVER_URL>/admin/sales-channels/<SALES_CHANNEL_ID>/products/batch' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "<PRODUCT_ID>"
}
]
}'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.products.list({
sales_channel_id: [
salesChannelId
]
})
.then(({ products, limit, offset, count }) => {
console.log(products.length);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/admin/products?sales_channel_id[0]=${salesChannelId}`)
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
console.log(products.length)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl --location --request GET '<SERVER_URL>/admin/products?sales_channel_id[0]=<SALES_CHANNEL_ID>' \
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.salesChannels.removeProducts(salesChannelId, {
product_ids: [
{
id: productId
}
]
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/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)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```jsx
curl --location --request DELETE '<SERVER_URL>/admin/sales-channels/<SALES_CHANNEL_ID>/products/batch' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "<PRODUCT_ID>"
}
]
}'
```
</TabItem>
</Tabs>
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:
<Tabs groupId="request-type">
<TabItem value="client" label="Medusa JS Client" default>
```jsx
medusa.admin.orders.list({
sales_channel_id: [
salesChannelId
],
limit: 50,
offset: 0
})
.then(({ orders, limit, offset, count }) => {
console.log(orders.length);
});
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```jsx
fetch(`<SERVER_URL>/admin/orders?sales_channel_id[0]=${salesChannelId}`)
.then((response) => response.json())
.then(({ orders, limit, offset, count }) => {
console.log(orders.length)
});
```
</TabItem>
<TabItem value="curl" label="cURL">
```jsx
curl --location --request GET '<SERVER_URL>/admin/orders?sales_channel_id[0]=<SALES_CHANNEL_ID>' \
--header 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
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).

5
www/docs/sidebars.js
View File

@@ -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"
},
]
},
{