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, 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 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:
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 to see which format is required for your import.
Expected columns
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 installed and have created an instance of the client.
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 and have used MedusaProvider higher in your component tree.
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.
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 Route:
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
})
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 API Route:
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
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)
})
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 beproduct-import
.context
: An object that must contain thefileKey
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 isfalse
, the product import will start right after you send this request. Settings its value totrue
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
.
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:
import { useAdminBatchJob } from "medusa-react"
type Props = {
batchJobId: string
}
const ImportProducts = ({ batchJobId }: Props) => {
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
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:
"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:
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 checkresult.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 inresult.errors
. - If the status is
completed
, it means the import has finished successfully.