docs: added import prices how-to (#2266)
This commit is contained in:
Shahed Nasser
GitHub
306
docs/content/advanced/admin/import-prices.mdx
Normal file
306
docs/content/advanced/admin/import-prices.mdx
Normal file
@@ -0,0 +1,306 @@
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Import Prices
|
||||
|
||||
In this document, you’ll learn how to import prices into a price list using the Admin APIs.
|
||||
|
||||
## Overview
|
||||
|
||||
Using Medusa’s [Batch Job Admin APIs](https://docs.medusajs.com/api/admin/#tag/Batch-Job), you can import prices into a price list.
|
||||
|
||||
:::caution
|
||||
|
||||
Importing prices into a price list removes all existing prices in the price list and adds the imported prices.
|
||||
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../quickstart/quick-start.md) to get started.
|
||||
|
||||
### Redis
|
||||
|
||||
Redis is required for batch 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).
|
||||
|
||||
### File Service Plugin
|
||||
|
||||
Part of the process of importing prices is uploading a CSV file. This requires a file service plugin to be installed on your server. If you don’t have any installed, you can install one of the following options:
|
||||
|
||||
- [MinIO](../../add-plugins/minio.md) (At least version `1.1.0`)
|
||||
- [Spaces](../../add-plugins/spaces.md)
|
||||
|
||||
### CSV File
|
||||
|
||||
You must have a CSV file that you will use to import prices into your Medusa server. You can check [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/price-list-import-template.csv) to see which format is required for your import.
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL.
|
||||
|
||||
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../js-client/overview.md) installed and have [created an instance of the client](../../js-client/overview.md#configuration).
|
||||
|
||||
### Authenticated Admin User
|
||||
|
||||
You must be an authenticated admin user before following along with the steps in the tutorial.
|
||||
|
||||
You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin/#section/Authentication).
|
||||
|
||||
### Created Price List
|
||||
|
||||
Before importing the prices, you must have a price list to import them to.
|
||||
|
||||
You can use the [Create Price List](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceList) endpoint, or follow the [how-to guide to learn how to create and manage price lists using the Admin API](../backend/price-lists/use-api.mdx).
|
||||
|
||||
## 1. Upload CSV File
|
||||
|
||||
The first step is to upload the CSV file to import prices from.
|
||||
|
||||
You can do that by sending the following request to the [Upload Files](https://docs.medusajs.com/api/admin/#tag/Upload/operation/PostUploads) endpoint:
|
||||
|
||||
<Tabs groupId="request-type">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```jsx
|
||||
medusa.admin.uploads.create(file) //file is an instance of File
|
||||
.then(({ uploads }) => {
|
||||
const key = uploads[0].key;
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```jsx
|
||||
const formData = new FormData();
|
||||
formData.append('files', file); //file is an instance of File
|
||||
|
||||
fetch(`<YOUR_SERVER>/admin/uploads`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'multipart/form-data',
|
||||
},
|
||||
body: formData
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ uploads }) => {
|
||||
const key = uploads[0].key;
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl --location --request POST '<YOUR_SERVER>/admin/uploads' \
|
||||
--header 'Authorization: Bearer {api_token}' \
|
||||
--header 'Content-Type: text/csv' \
|
||||
--form 'files=@"<FILE_PATH_1>"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the prices next.
|
||||
|
||||
## 2. Create a Batch Job for Prices Import
|
||||
|
||||
To start a new price import, you must create a batch job.
|
||||
|
||||
You can do that by sending the following request to the [Create a Batch Job](https://docs.medusajs.com/api/admin/#tag/Batch-Job/operation/PostBatchJobs) endpoint:
|
||||
|
||||
<Tabs groupId="request-type">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```jsx
|
||||
medusa.admin.batchJobs.create({
|
||||
type: 'price-list-import',
|
||||
context: {
|
||||
fileKey: key, //obtained from previous step
|
||||
price_list_id
|
||||
},
|
||||
dry_run: true
|
||||
})
|
||||
.then(( batch_job ) => {
|
||||
console.log(batch_job.status);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```jsx
|
||||
fetch(`<YOUR_SERVER>/admin/batch-jobs`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
type: 'price-list-import',
|
||||
context: {
|
||||
fileKey: key, //obtained from previous step
|
||||
price_list_id
|
||||
},
|
||||
dry_run: true
|
||||
})
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ batch_job }) => {
|
||||
console.log(batch_job.status);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs' \
|
||||
--header 'Authorization: Bearer {api_token}' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"type": "price-list-import",
|
||||
"context": {
|
||||
"fileKey": "<KEY>",
|
||||
"price_list_id": "<PRICE_LIST_ID>"
|
||||
},
|
||||
"dry_run": true
|
||||
}'
|
||||
# <KEY> is the key you obtained from the previous step
|
||||
# <PRICE_LIST_ID> is the ID of the price list to import prices into
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
In the body of the request, you must pass the following parameters:
|
||||
|
||||
- `type`: Batch jobs can be of different types. For price imports, the type should always be `price-list-import`.
|
||||
- `context`: An object that must contain:
|
||||
- The `fileKey` property. The value of this property is the key received when you uploaded the CSV file.
|
||||
- The `price_list_id` property. The value of this property is the ID of the price list you’re importing the prices into.
|
||||
- `dry_run`: This is optional to include. If not set or if its value is `false`, the price import will start right after you send this request. Settings its value to `true` allows you to retrieve afterward a brief of the number of prices that will be added.
|
||||
|
||||
This request returns the batch job with its details such as the `status` or `id`.
|
||||
|
||||
:::note
|
||||
|
||||
If you don’t set `dry_run` or you set it to `false`, you don’t need to follow the rest of these steps.
|
||||
|
||||
:::
|
||||
|
||||
## (Optional) Retrieve Batch Job
|
||||
|
||||
After creating the batch job, it will be pre-processed. At this point, the CSV file will be validated, and the number of prices to add are counted.
|
||||
|
||||
You can retrieve all the details of the batch job, including its status and the brief statistics related to the prices by sending the following request:
|
||||
|
||||
<Tabs groupId="request-type">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```jsx
|
||||
medusa.admin.batchJobs.retrieve(batchJobId)
|
||||
.then(( batch_job ) => {
|
||||
console.log(batch_job.status, batch_job.result);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```jsx
|
||||
fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}`)
|
||||
.then((response) => response.json())
|
||||
.then(({ batch_job }) => {
|
||||
console.log(batch_job.status, batch_job.result);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl --location --request GET '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>' \
|
||||
--header 'Authorization: Bearer {api_token}'
|
||||
# <BATCH_JOB_ID> is the ID of the batch job
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the batch job’s ID as a parameter, which can be retrieved from the previous request. It returns the batch job in the response.
|
||||
|
||||
If the batch job has been pre-processed, the status of the batch job will be `pre_processed` and the `result` property will contain details about the import.
|
||||
|
||||
Here’s an example of the `result` property:
|
||||
|
||||
```json
|
||||
"result": {
|
||||
"count": 5, // Total number of prices to be added
|
||||
"stat_descriptors": [ //details about the prices to be added
|
||||
{
|
||||
"key": "price-list-import-count",
|
||||
"name": "PriceList to import",
|
||||
"message": "5 prices will be added"
|
||||
}
|
||||
],
|
||||
"advancement_count": 0 //number of prices processed so far. Will be 0 before the import is confirmed.
|
||||
},
|
||||
```
|
||||
|
||||
## 3. Confirm Batch Job
|
||||
|
||||
A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the price import will start which will add prices to the price list
|
||||
|
||||
To confirm a batch job send the following request:
|
||||
|
||||
<Tabs groupId="request-type">
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```jsx
|
||||
medusa.admin.batchJobs.confirm(batchJobId)
|
||||
.then(( batch_job ) => {
|
||||
console.log(batch_job.status);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```jsx
|
||||
fetch(`<YOUR_SERVER>/admin/batch-jobs/${batchJobId}/confirm`, {
|
||||
method: 'POST'
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ batch_job }) => {
|
||||
console.log(batch_job.status);
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl --location --request POST '<YOUR_SERVER>/admin/batch-jobs/<BATCH_JOB_ID>/confirm' \
|
||||
--header 'Authorization: Bearer {api_token}'
|
||||
# <BATCH_JOB_ID> is the ID of the batch job
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the ID of the batch job as a path parameter and returns the updated batch job. The returned batch job should have the status `confirmed`, which indicates that the batch job will now start processing.
|
||||
|
||||
### Checking the Status After Confirmation
|
||||
|
||||
After confirming the batch job, you can check the status while it is processing at any given point by retrieving the batch job. Based on the status, you can infer the progress of the batch job:
|
||||
|
||||
- If the status is `processing`, it means that the import is currently in progress. You can also check `result.advancement_count` to find out how many prices have been added so far.
|
||||
- If the status is `failed`, it means an error has occurred during the import. You can check the error in `result.errors`.
|
||||
- If the status is `completed`, it means the import has finished successfully.
|
||||
|
||||
## What’s Next 🚀
|
||||
|
||||
- Learn more about [Batch Jobs and how they work](../backend/batch-jobs/index.md).
|
||||
- Check out the [Batch Jobs API Reference](https://docs.medusajs.com/api/admin/#tag/Batch-Job).
|
||||
@@ -215,6 +215,11 @@ module.exports = {
|
||||
id: "advanced/admin/import-products",
|
||||
label: "Import Products"
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "advanced/admin/import-prices",
|
||||
label: "Import Prices"
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "advanced/backend/taxes/manual-calculation",
|
||||
|
||||
Reference in New Issue
Block a user