How to import CSV files in Saleor

How to Import CSV Files into Saleor Using CSVBox

Bulk data import is a critical need in modern e-commerce stacks—especially when managing large product catalogs, customer records, or inventory updates. Saleor, a popular headless e-commerce platform, offers great flexibility via GraphQL but lacks a built-in CSV import feature. This tutorial walks through how to integrate CSV import functionality into Saleor using CSVBox, a user-friendly CSV uploader widget.

Ideal for developers building with Saleor, this guide helps you support non-technical users who want to drag and drop spreadsheets instead of wrangling GraphQL manually.

Why Add CSV Import to Saleor?

If you’re running a growing Saleor storefront, data entry becomes a bottleneck. Scenarios like these are common:

• Updating 1,000+ SKUs
• Importing customer data from offline channels
• Managing shipping zones and inventory in bulk
• Migrating data from spreadsheets to your storefront

Without automation, teams end up writing scripts or manually uploading entries via the admin UI—error-prone and time-consuming.

By integrating CSVBox with Saleor, you unlock:

• ✅ Drag-and-drop spreadsheet uploads
• 🔍 Field validation and duplicate checks upfront
• 🔗 Seamless transformation of CSV rows into GraphQL mutation calls
• ⚠️ Prevention of malformed data before hitting your backend

What Is CSVBox and How Does It Help?

CSVBox is a SaaS widget for importing validated CSV files directly into your web apps. It solves key pain points of CSV ingestion:

• Visual uploader + spreadsheet preview for end users
• Real-time validation and feedback
• Customizable column mappings, required fields, and data types
• Secure uploads and webhook integrations

For Saleor teams, CSVBox acts as the middle layer between spreadsheets and your APIs—catching errors before they corrupt your system.

Step-by-Step Saleor Integration Guide

You can embed CSVBox into the Saleor Dashboard (React-based), your custom admin panel, or even a standalone tool for store managers. Here’s how:

Prerequisites

To follow this guide, you’ll need:

• A running instance of Saleor (hosted or self-managed)
• Access to modify or extend your React Frontend
• A backend GraphQL endpoint to receive validated data
• A free CSVBox account → Sign up at csvbox.io

1. Set Up Your CSVBox Widget

Start by configuring what your CSV importer should accept.

1. Go to your CSVBox Dashboard
2. Click “Create Widget” — choose target data (e.g., Products)
3. Define the template headers:
   Example columns: title, sku, price, inventory
4. Save, then copy:
   • 📌 client_key
   • 🧩 widget_hash

You’ll need these to initialize the widget on your frontend.

2. Add the CSVBox Uploader to Your Saleor Dashboard

Saleor’s admin dashboard is built with React, which makes it easy to integrate the widget.

First, include the CSVBox JS file:

<script src="https://js.csvbox.io/widget.js"></script>

Now, add a button in your React component that launches the CSVBox importer:

<button
  onClick={() => {
    window.CSVBox && window.CSVBox.show({
      client_key: "your_client_key",
      widget_hash: "your_widget_hash",
      user: {
        user_id: "[email protected]"
      },
      metadata: {
        source: "saleor-dashboard"
      },
      onUploadDone: function (result) {
        console.log("Upload successful", result);
        // Pass rows to your mutation handler
        processCSVRows(result.row_data);
      }
    });
  }}
>
  Import Products via CSV
</button>

🔐 Make sure this component is rendered within a secure admin route. Optionally include auth context in the widget metadata.

3. Transform and Send Data to Saleor API

The uploaded data (result.row_data) needs to be converted to match your GraphQL mutation.

Example JavaScript code to handle this upload:

const handleUpload = async (result) => {
  const rowData = result.row_data;

  const products = rowData.map(row => ({
    name: row.title,
    sku: row.sku,
    basePrice: parseFloat(row.price),
    quantity: parseInt(row.inventory),
  }));

  const response = await fetch("/api/bulk-create-products", {
    method: "POST",
    body: JSON.stringify({ products }),
    headers: {
      "Content-Type": "application/json"
    }
  });

  const data = await response.json();
  if (data.errors) {
    console.error("Import failed", data.errors);
  } else {
    alert("Products imported successfully");
  }
};

4. Create a Backend Handler to Trigger Saleor Mutations

Your backend now needs to accept the validated array and invoke the Saleor GraphQL API.

Example using Express.js and graphql-request:

import { createClient } from 'urql';

const graphqlClient = createClient({
  url: 'https://your-saleor-host/graphql/',
  fetchOptions: () => ({
    headers: {
      authorization: 'Bearer YOUR_ADMIN_TOKEN',
    })
});

app.post("/api/bulk-create-products", async (req, res) => {
  const input = req.body.products;

  const mutation = `
    mutation BulkCreateProduct($input: [ProductCreateInput!]!) {
      bulkCreateProduct(input: $input) {
        errors {
          field
          message
        }
        products {
          id
          name
          sku
        }
      }
    }
  `;

  const result = await graphqlClient
    .mutation(mutation, { input })
    .toPromise();

  if (result.error) {
    return res.status(500).json({ errors: [result.error.message] });
  }

  res.status(200).json(result.data.bulkCreateProduct);
});

This endpoint acts as a secure bridge between the validated CSV rows and your GraphQL layer.

Common CSV Import Issues & Troubleshooting

🧪 Tip: Use console logging (console.log(result)) to inspect the data shape from CSVBox before sending to your API.

Why Developers Choose CSVBox for CSV Uploads

CSVBox is more than a file uploader. It’s purpose-built for highly structured, validated CSV imports in production-grade SaaS apps—all without building complex parsers from scratch.

Key benefits:

• 🧩 Custom header templates per use case (SKUs, inventory, etc.)
• ⛔ Prevents invalid or duplicate uploads
• 🧹 Ensures only clean rows go to backend APIs
• 🔁 Retry-friendly and user-verifiable import experience
• 📬 Optional webhooks and callbacks for further automation

Thousands of teams use CSVBox to let users manage data without breaking internal logic.

Real-World Use Cases for Saleor Teams

Here are example questions developers often ask—answered by this integration:

• “How can I allow store admins to bulk-import products without giving them deep tech access?”
• “What’s the easiest way to validate CSV headers and formats before calling GraphQL mutations?”
• “How do I let managers upload seasonal promos without engineering help?”

CSVBox integration helps you solve all of the above with zero spreadsheet parsing logic on your side.

Next Steps for Production-Ready Import Workflows

To go from MVP to hardened implementation:

• 🔐 Secure your backend endpoints with auth tokens or middleware
• 📈 Add import logs, tracking, and metrics for observability
• ✨ Enable custom widgets for different roles (e.g., inventory managers vs catalog admins)
• 🔄 Integrate CSVBox webhooks to trigger background tasks or analytics
• 🧪 Write test cases for malformed data, required fields, and edge cases

Helpful links:

• CSVBox Docs
• Getting Started Guide
• Saleor Developer Portal

Conclusion

Implementing a CSV import feature inside Saleor can significantly boost operational efficiency—especially for teams managing high-volume data like products or fulfillment zones. With CSVBox, you get a polished, secure, and flexible upload experience for your users—and a clean data pipeline for your backend.

Instead of building your own importer stack, plug in CSVBox and focus on core product logic.

Let your users bring their spreadsheets—we’ll make sure they don’t break your app.