---
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, you’ll learn how to use the Admin APIs to bulk import products into a Medusa backend.

## Overview

Using Medusa’s [Batch Job Admin APIs](https://docs.medusajs.com/api/admin#batch-jobs_getbatchjobs), 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. The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.

### 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 don’t 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)

:::note

The local file service can't be used for product import.

:::

### 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-sales-channels.csv) to see which format is required for your import.

<details>
<summary>
Expected columns
</summary>

#### Product columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Product Handle
</td>
<td>
The handle of the product
</td>
<td>
Yes
</td>
</tr>

<tr>
<td>
Product Id
</td>
<td>
The ID of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Title
</td>
<td>
The title of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Subtitle
</td>
<td>
The subtitle of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Description
</td>
<td>
The description of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Status
</td>
<td>
The status of the product. Its value can be `draft`, `proposed`, `published`, or `rejected`.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Thumbnail
</td>
<td>
A URL to the thumbnail of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Image (number) Url
</td>
<td>
A URL to a product image. To add more than one image, you can specify the image number in the column title. For example, "Image 1 Url".
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Weight
</td>
<td>
The weight of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Length
</td>
<td>
The length of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Width
</td>
<td>
The width of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Height
</td>
<td>
The height of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product HS Code
</td>
<td>
The HS Code of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Origin Country
</td>
<td>
The origin country of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product MID Code
</td>
<td>
The MID code of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Material
</td>
<td>
The material of the product
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Discountable
</td>
<td>
A boolean value indicating whether the product is discountable.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product External Id
</td>
<td>
The external ID of the product. Useful if the product is being imported from another platform and you want to maintain the link to it.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Profile Name
</td>
<td>
The name of the product's shipping profile.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Profile Type
</td>
<td>
The type of the product's shipping profile. Its value can be `default`, `gift_card`, or `custom`.
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Collection columns

:::note

A product collection is only associated with the product if the handle provided exists. Otherwise, it's skipped.

:::

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Product Collection Title
</td>
<td>
The title of the product collection
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Collection Handle
</td>
<td>
The handle of the product collection
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Type columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Product Type
</td>
<td>
The value of the product type
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Tag columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Product Tags
</td>
<td>
A comma-separated list of product tags
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Option columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
"Option Name" or "Option (number) Name"
</td>
<td>
The name of the product option. If you name the column "Option Name", it means only one option will be added, and there should be no duplicate column with the same name for another option. To add more than one option, use the "Option (number) Name" name. For example, "Option 1 Name".
</td>
<td>
No
</td>
</tr>

<tr>
<td>
"Option Value" or "Option (number) Value"
</td>
<td>
The value of the product option. If you name the column "Option Value", it means only one option will be added, and there should be no duplicate column with the same name for another option. To add more than one option value, use the "Option (number) Value" name. For example, "Option 1 Value". The number of the value should correspond to the same option name number.
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Variant Columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Variant Id
</td>
<td>
The ID of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Title
</td>
<td>
The title of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant SKU
</td>
<td>
The SKU of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Barcode
</td>
<td>
The barcode of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Inventory Quantity
</td>
<td>
The inventory quantity of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Allow Backorder
</td>
<td>
A boolean value indicating if the variant can be back-ordered.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Manage Inventory
</td>
<td>
A boolean value indicating if the variant's inventory can be managed.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Weight
</td>
<td>
The weight of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Length
</td>
<td>
The length of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Width
</td>
<td>
The width of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Height
</td>
<td>
The height of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant HS Code
</td>
<td>
The HS Code of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Origin Country
</td>
<td>
The origin country of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant MID Code
</td>
<td>
The MID code of the product variant
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Variant Material
</td>
<td>
The material of the product variant
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Prices columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Price (region name)
</td>
<td>
The price amount for a particular region, where (region name) is the name of the region.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Price (currency code)
</td>
<td>
The price amount for a particular currency, where (currency code) is the 3 character ISO code of the currency. For example, "Price USD".
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Sales channel columns

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Sales Channel (number) Id
</td>
<td>
The ID of the sales channel this product is available in, if it already exists.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Sales Channel (number) Name
</td>
<td>
The name of the sales channel this product is available in. To specify more than one sales channel, include a number in the name. For example, "Sales Channel 1 Name".
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Sales Channel (number) Description
</td>
<td>
The description of the sales channel this product is available in. Make sure the column name has the same number as the corresponding sales channel name.
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

#### Product Category columns

:::note

The [product categories beta feature](../../../beta.md) must be enabled first. Otherwise, these columns will be ignored.

:::

<table class="reference-table">
<thead>
<tr>
<th>
Column name
</th>
<th>
Description
</th>
<th>
Is required?
</th>
</tr>
</thead>

<tbody>

<tr>
<td>
Product Category (number) Handle
</td>
<td>
The handle of the product category this product belongs to. If you're specifying more than one product category, you must include a number in the column name. For example, "Product Category 1 Handle". If a product category with this handle doesn't exist, the product category will be ignored.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Category (number) Name
</td>
<td>
The name of the product category this product belongs to. Make sure to use the same number as that of the corresponding product category handle.
</td>
<td>
No
</td>
</tr>

<tr>
<td>
Product Category (number) Description
</td>
<td>
The description of the product category this product belongs to. Make sure to use the same number as that of the corresponding product category handle.
</td>
<td>
No
</td>
</tr>

</tbody>
</table>

</details>

### JS Client

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

### 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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#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](https://docs.medusajs.com/api/admin#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](https://docs.medusajs.com/api/admin#uploads_postuploads) endpoint:

<Tabs groupId="request-type" isCodeTabs={true}>
<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>' \
  -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`. You’ll need the `key` to import the products next.

Where `<FILE_PATH_1>` is a full path to the file. For example, `/Users/medusa/product-import-sales-channels.csv`

---

## 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](https://docs.medusajs.com/api/admin#batch-jobs_postbatchjobs) endpoint:

<Tabs groupId="request-type" isCodeTabs={true}>
<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 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 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" isCodeTabs={true}>
<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 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 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" isCodeTabs={true}>
<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)
