docs: publish restructure (#3496)

* docs: added features and guides overview page

* added image

* added version 2

* added version 3

* added version 4

* docs: implemented new color scheme

* docs: redesigned sidebar (#3193)

* docs: redesigned navbar for restructure (#3199)

* docs: redesigned footer (#3209)

* docs: redesigned cards (#3230)

* docs: redesigned admonitions (#3231)

* docs: redesign announcement bar (#3236)

* docs: redesigned large cards (#3239)

* docs: redesigned code blocks (#3253)

* docs: redesigned search modal and page (#3264)

* docs: redesigned doc footer (#3268)

* docs: added new sidebars + refactored css and assets (#3279)

* docs: redesigned api reference sidebar

* docs: refactored css

* docs: added code tabs transition

* docs: added new sidebars

* removed unused assets

* remove unusued assets

* Fix deploy errors

* fix incorrect link

* docs: fixed code responsivity + missing icons (#3283)

* docs: changed icons (#3296)

* docs: design fixes to the sidebar (#3297)

* redesign fixes

* docs: small design fixes

* docs: several design fixes after restructure (#3299)

* docs: bordered icon fixes

* docs: desgin fixes

* fixes to code blocks and sidebar scroll

* design adjustments

* docs: restructured homepage (#3305)

* docs: restructured homepage

* design fixes

* fixed core concepts icon

* docs: added core concepts page (#3318)

* docs: restructured homepage

* design fixes

* docs: added core concepts page

* changed text of different components

* docs: added architecture link

* added missing prop for user guide

* docs: added regions overview page (#3327)

* docs: added regions overview

* moved region pages to new structure

* docs: fixed description of regions architecture page

* small changes

* small fix

* docs: added customers overview page (#3331)

* docs: added regions overview

* moved region pages to new structure

* docs: fixed description of regions architecture page

* small changes

* small fix

* docs: added customers overview page

* fix link

* resolve link issues

* docs: updated regions architecture image

* docs: second-iteration fixes (#3347)

* docs: redesigned document

* design fixes

* docs: added products overview page (#3354)

* docs: added carts overview page (#3363)

* docs: added orders overview (#3364)

* docs: added orders overview

* added links in overview

* docs: added vercel redirects

* docs: added soon badge for cards (#3389)

* docs: resolved feedback changes + organized troubleshooting pages (#3409)

* docs: resolved feedback changes

* added extra line

* docs: changed icons for restructure (#3421)

* docs: added taxes overview page (#3422)

* docs: added taxes overview page

* docs: fix sidebar label

* added link to taxes overview page

* fixed link

* docs: fixed sidebar scroll (#3429)

* docs: added discounts overview (#3432)

* docs: added discounts overview

* fixed links

* docs: added gift cards overview (#3433)

* docs: added price lists overview page (#3440)

* docs: added price lists overview page

* fixed links

* docs: added sales channels overview page (#3441)

* docs: added sales overview page

* fixed links

* docs: added users overview (#3443)

* docs: fixed sidebar border height (#3444)

* docs: fixed sidebar border height

* fixed svg markup

* docs: added possible solutions to feedback component (#3449)

* docs: added several overview pages + restructured files (#3463)

* docs: added several overview pages

* fixed links

* docs: added feature flags + PAK overview pages (#3464)

* docs: added feature flags + PAK overview pages

* fixed links

* fix link

* fix link

* fixed links colors

* docs: added strategies overview page (#3468)

* docs: automated upgrade guide (#3470)

* docs: automated upgrade guide

* fixed vercel redirect

* docs: restructured files in docs codebase (#3475)

* docs: restructured files

* docs: fixed eslint exception

* docs: finished restructure loose-ends (#3493)

* fixed uses of backend

* docs: finished loose ends

* eslint fixes

* fixed links

* merged master

* added update instructions for v1.7.12
This commit is contained in:
Shahed Nasser
2023-03-16 17:03:10 +02:00
committed by GitHub
parent f312ce1e0f
commit 1decaa27c7
415 changed files with 12422 additions and 5098 deletions
@@ -0,0 +1,414 @@
---
description: 'Learn how to import products into Medusa using the Admin REST APIs. The steps include uploading a CSV file, creating a batch job for the import, and confirming the batch job.'
addHowToData: true
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# How to Bulk Import Products
In this document, youll learn how to use the Admin APIs to bulk import products into a Medusa backend.
## Overview
Using Medusas [Batch Job Admin APIs](/api/admin/#tag/Batch-Job), you can import products into your Medusa backend. This will either add new products or update existing products.
---
## Prerequisites
### Medusa Components
It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.
### Redis
Redis is required for batch jobs to work. Make sure you [install Redis](../../../development/backend/prepare-environment.mdx#redis) and [configure it with the Medusa backend](../../../development/backend/configurations.md#redis).
### File Service Plugin
Part of the process of importing products is uploading a CSV file. This requires a file service plugin to be installed on your backend. If you dont have any installed, you can install one of the following options:
- [MinIO](../../../plugins/file-service/minio.md) (At least version `1.1.0`)
- [Spaces](../../../plugins/file-service/spaces.md)
### CSV File
You must have a CSV file that you will use to import products into your Medusa backend. You can check [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/product-import-1.3.8.csv) to see which format is required for your import.
:::note
If you have Sales Channels enabled on your backend, you must use [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/product-import-sales-channels.csv) instead.
:::
### JS Client
This guide includes code snippets to send requests to your Medusa backend using Medusas JS Client, among other methods.
If you follow the JS Client code blocks, its assumed you already have [Medusas 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 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).
### Authenticated Admin User
You must be an authenticated admin user before following along with the steps in the tutorial.
You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
---
## 1. Upload CSV File
The first step is to upload the CSV file that you want to import products.
You can do that by sending the following request to the [Upload Files](/api/admin/#tag/Upload/operation/PostUploads) endpoint:
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.uploads.create(file) // file is an instance of File
.then(({ uploads }) => {
const key = uploads[0].key
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminUploadFile } from "medusa-react"
const ImportProducts = () => {
const uploadFile = useAdminUploadFile()
// ...
const handleFileUpload = (file: File) => {
uploadFile.mutate(file)
}
// ...
}
export default ImportProducts
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
const formData = new FormData()
formData.append("files", file) // file is an instance of File
fetch(`<BACKEND_URL>/admin/uploads`, {
method: "POST",
credentials: "include",
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 -L -X POST '<BACKEND_URL>/admin/uploads' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: text/csv' \
-F '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`. Youll need the `key` to import the products next.
---
## 2. Create a Batch Job for Product Import
To start a new product import, you must create a batch job.
You can do that by sending the following request to the [Create a Batch Job](/api/admin/#tag/Batch-Job/operation/PostBatchJobs) endpoint:
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.batchJobs.create({
type: "product-import",
context: {
fileKey: key, // obtained from previous step
},
dry_run: true,
})
.then(( batch_job ) => {
console.log(batch_job.status)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminCreateBatchJob } from "medusa-react"
const ImportProducts = () => {
const createBatchJob = useAdminCreateBatchJob()
// ...
const handleCreateBatchJob = () => {
createBatchJob.mutate({
type: "product-import",
context: {
fileKey: key, // obtained from previous step
},
dry_run: true,
})
}
// ...
}
export default ImportProducts
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(`<BACKEND_URL>/admin/batch-jobs`, {
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "product-import",
context: {
fileKey: key, // obtained from previous step
},
dry_run: true,
}),
})
.then((response) => response.json())
.then(({ batch_job }) => {
console.log(batch_job.status)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/batch-jobs' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"type": "product-import",
"context": {
"fileKey": "<KEY>"
},
"dry_run": true
}'
# <KEY> is the key you obtained from the previous step
```
</TabItem>
</Tabs>
In the body of the request, you must pass the following parameters:
- `type`: Batch jobs can be of different types. For product imports, the type should always be `product-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.
- `dry_run`: This is optional to include. If not set or if its value is `false`, the product 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 products that will be added or updated, or the number of rejected products.
This request returns the batch job with its details such as the `status` or `id`.
:::note
If you dont set `dry_run` or you set it to `false`, you dont 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 products to add and update, or that are rejected are counted.
You can retrieve all the details of the batch job, including its status and the brief statistics related to the products by sending the following request:
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.batchJobs.retrieve(batchJobId)
.then(( batch_job ) => {
console.log(batch_job.status, batch_job.result)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminBatchJob } from "medusa-react"
const ImportProducts = () => {
const { batch_job, isLoading } = useAdminBatchJob(batchJobId)
// ...
return (
<div>
{/* ... */}
{isLoading && <span>Loading</span>}
{batch_job && (
<span>
Status: {batch_job.status}.
Number of Products: {batch_job.result.count}
</span>
)}
</div>
)
}
export default ImportProducts
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(`<BACKEND_URL>/admin/batch-jobs/${batchJobId}`, {
credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
console.log(batch_job.status, batch_job.result)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X GET '<BACKEND_URL>/admin/batch-jobs/<BATCH_JOB_ID>' \
-H 'Authorization: Bearer <API_TOKEN>'
# <BATCH_JOB_ID> is the ID of the batch job
```
</TabItem>
</Tabs>
This request accepts the batch jobs 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.
Heres an example of the `result` property:
```json noReport
"result": {
"count": 5, // Total number of products to be created or updated
"stat_descriptors": [ //details about the products to be created/updated
{
"key": "product-import-count",
"name": "Products/variants to import",
"message": "There will be 2 products created..."
}
],
"advancement_count": 0 //number of products processed so far.
},
```
---
## 3. Confirm Batch Job
A batch job can be confirmed only once the batch job has the status `pre_processed`. Once you confirm a batch job, the product import will start which will create or update products on your backend.
To confirm a batch job send the following request:
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.batchJobs.confirm(batchJobId)
.then(( batch_job ) => {
console.log(batch_job.status)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminConfirmBatchJob } from "medusa-react"
const ImportProducts = () => {
const confirmBatchJob = useAdminConfirmBatchJob(batchJobId)
// ...
const handleConfirmJob = () => {
confirmBatchJob.mutate()
}
// ...
}
export default ImportProducts
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(`<BACKEND_URL>/admin/batch-jobs/${batchJobId}/confirm`, {
method: "POST",
credentials: "include",
})
.then((response) => response.json())
.then(({ batch_job }) => {
console.log(batch_job.status)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/batch-jobs/<BATCH_JOB_ID>/confirm' \
-H '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](#optional-retrieve-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 products have been created or updated 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.
---
## See Also
- [Batch Jobs Overview](../../../development/batch-jobs/index.mdx)
+221
View File
@@ -0,0 +1,221 @@
---
description: "Products are items or services that businesses sell to their customers. Learn about the available features and guides."
---
import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
# Products
Products are items or services that businesses sell to their customers. This overview introduces the available features related to products.
:::note
💡 Not a developer? Check out the [Products user guide](../../user-guide/products/manage.mdx).
:::
## Features
### Products Management
Admins can manage unlimited amount of products and their variants. They can manage the products details including their pricing, inventory, and more.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '#',
label: 'Admin: Manage Products',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to manage products using Admin APIs.',
isSoon: true,
}
},
{
type: 'link',
href: '/user-guide/products/manage',
label: 'User Guide: Manage Products',
customProps: {
icon: Icons['users-solid'],
description: 'Manage products in Medusa Admin.'
}
},
{
type: 'link',
href: '#',
label: 'Storefront: Show Products',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to show products in a storefront.',
isSoon: true,
}
},
]} />
### Product Organization
Admins can organize products into collections, tags, types, and more.
Customers can use this organization to filter products while browsing them.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '#',
label: 'Admin: Manage Collections',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to manage collections using Admin APIs.',
isSoon: true,
}
},
{
type: 'link',
href: '/user-guide/products/collections',
label: 'User Guide: Manage Collections',
customProps: {
icon: Icons['users-solid'],
description: 'Learn how to manage collections in Medusa Admin.'
}
},
{
type: 'link',
href: '#',
label: 'Storefront: Show Collections',
customProps: {
icon: Icons['server-solid'],
description: 'Learn how to show collections in a storefront.',
isSoon: true,
}
},
]} />
### Product Import and Export
Admins can bulk import and export products using CSV files. This facilitates moving data from other ecommerce platforms to Medusa.
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/products/admin/import-products',
label: 'Admin: Import Products',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to import products into Medusa using Admin APIs.'
}
},
{
type: 'link',
href: '/user-guide/products/import',
label: 'User Guide: Import',
customProps: {
icon: Icons['users-solid'],
description: 'Learn how to import products into Medusa Admin.'
}
},
{
type: 'link',
href: '/user-guide/products/export',
label: 'User Guide: Export',
customProps: {
icon: Icons['users-solid'],
description: 'Learn how to export products from Medusa Admin.'
}
},
]} />
---
## Understand the Architecture
Learn how product-related entities are build, their relation to other modules, and more.
<DocCardList colSize={6} items={[
{
type: 'link',
href: '#',
label: 'Architecture: Product',
customProps: {
icon: Icons['circle-stack-solid'],
description: 'Learn about the Product Architecture.',
isSoon: true,
}
},
{
type: 'link',
href: '#',
label: 'Architecture: Collection',
customProps: {
icon: Icons['circle-stack-solid'],
description: 'Learn about the Collection Architecture.',
isSoon: true,
}
},
]} />
---
## Related Modules
Discover Products relation to other modules in Medusa
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/sales-channels/overview',
label: 'Sales Channels',
customProps: {
icon: Icons['channels-solid'],
description: 'Products availability can be specific to sales channels.',
}
},
{
type: 'link',
href: '/modules/price-lists/overview',
label: 'Price Lists',
customProps: {
icon: Icons['currency-dollar'],
description: 'Override prices of products based on specific conditions.',
}
},
{
type: 'link',
href: '/modules/discounts/overview',
label: 'Discounts',
customProps: {
icon: Icons['receipt-percent'],
description: 'Discounts can be created for specific products or collections.',
}
},
]} />
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/modules/gift-cards/overview',
label: 'Gift Cards',
customProps: {
icon: Icons['gift-solid'],
description: 'Gift cards can be sold as Products.',
}
},
{
type: 'link',
href: '/modules/carts-and-checkout/overview',
label: 'Carts and Checkout',
customProps: {
icon: Icons['shopping-cart-solid'],
description: 'Allow customers to purchase your products.'
}
},
{
type: 'link',
href: '/modules/orders/overview',
label: 'Orders',
customProps: {
icon: Icons['check-circle-solid'],
description: 'Product purchases can be managed as orders.'
}
},
]} />