Skip to main content

How to Import Products

In this document, you’ll learn how to use the Admin APIs to import products into a Medusa server.

Overview

Using Medusa’s Batch Job Admin APIs, you can import products into your Medusa server. This will either add new products or update existing products.

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 to get started.

Redis

Redis is required for batch jobs to work. Make sure you install Redis and configure it with your Medusa server.

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 server. If you don’t have any installed, you can install one of the following options:

CSV File

You must have a CSV file that you will use to import products into your Medusa server. You can check this CSV example file to see which format is required for your import.

If you have Sales Channels enabled on your server, you must use this CSV example file instead.

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 and have created an instance of the client.

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 endpoint:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
medusa.admin.uploads.create(file) //file is an instance of File
.then(({ uploads }) => {
const key = uploads[0].key;
});
Copy to Clipboard

This request returns an array of uploads. Each item in the array is an object that includes the properties Copy to Clipboard and Copy to Clipboard. You’ll need the Copy to Clipboard 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 endpoint:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
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);
});
Copy to Clipboard

In the body of the request, you must pass the following parameters:

  • Copy to Clipboard: Batch jobs can be of different types. For product imports, the type should always be Copy to Clipboard.
  • Copy to Clipboard: An object that must contain the Copy to Clipboard property. The value of this property is the key received when you uploaded the CSV file.
  • Copy to Clipboard: This is optional to include. If not set or if its value is Copy to Clipboard, the product import will start right after you send this request. Settings its value to Copy to Clipboard 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 Copy to Clipboard or Copy to Clipboard.

If you don’t set Copy to Clipboard or you set it to Copy to Clipboard, 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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
medusa.admin.batchJobs.retrieve(batchJobId)
.then(( batch_job ) => {
console.log(batch_job.status, batch_job.result);
});
Copy to Clipboard

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 Copy to Clipboard and the Copy to Clipboard property will contain details about the import.

Here’s an example of the Copy to Clipboard 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 (0 updated).\n 3 variants will be created and 0 updated"
}
],
"advancement_count": 0 //number of products processed so far. Will be 0 before the import is confirmed.
},
Copy to Clipboard

3. Confirm Batch Job

A batch job can be confirmed only once the batch job has the status Copy to Clipboard. Once you confirm a batch job, the product import will start which will create or update products on your server.

To confirm a batch job send the following request:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
medusa.admin.batchJobs.confirm(batchJobId)
.then(( batch_job ) => {
console.log(batch_job.status);
});
Copy to Clipboard

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 Copy to Clipboard, 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 Copy to Clipboard, it means that the import is currently in progress. You can also check Copy to Clipboard to find out how many products have been created or updated so far.
  • If the status is Copy to Clipboard, it means an error has occurred during the import. You can check the error in Copy to Clipboard.
  • If the status is Copy to Clipboard, it means the import has finished successfully.

What’s Next