# Imports

> Bulk-load catalog data from a CSV, TSV or XLSX file, and follow the import job until it is processed.
{/* generated:versioned-pages - edit _pm-authored, not this file */}

An **Import** bulk-loads catalog data from a file rather than one API call per record. Each import targets an **import type** - the kind of data being loaded, such as `product`, `collections` or `suppliers` - which defines the columns the file is expected to carry and the `metadata` it accepts.

An import is a **job**: the upload is synchronous, but processing is asynchronous. The job starts `pending`, moves to `processing`, then ends `completed` or `failed`, and its `report` gives the per-row result once processing is done.

## The Import object

## How it fits together

1. **Pick the type.** [List import types](/api/product-management/imports/list-types/) to see the supported types and the `metadata` each accepts (such as the `locale`, or the XLSX `sheetName`).
2. **Prepare the file.** In the `unstable` version, [download an example file](/api/product-management/imports/sample/) for the type rather than guessing the column layout.
3. **Upload it.** [Create an import](/api/product-management/imports/create/) with the `file`, its `type` and any `metadata`, as `multipart/form-data`.
4. **Follow the job.** [Retrieve the import](/api/product-management/imports/retrieve/) until its `status` is `completed` or `failed`, then read its `report`: `totalRows`, `imported`, `failed`, and the `errors` of each rejected line.

## Start from an example

The example download is only available in the `unstable` version. It returns a ready-to-fill file for a given type, in `csv` (default) or `xlsx`, and serves two different needs through its `mode`:

- `sample` (default) - a small, hand-crafted illustrative file showing the expected columns and a few example rows. Useful to discover the format.
- `data` - a full, re-importable export of your existing tenant data for that type. Useful to bulk-edit what you already have and load it back.

The two modes differ in what they require: `sample` needs only `imports:read`, while `data` also needs the read permissions of the target domain - for the product type, `products:read` or `products:org:read` plus `medias:read`.

## Conventions

### Authentication and headers

All requests require an OAuth 2.0 bearer token:

```
Authorization: Bearer <token>
```

Reading imports requires the `imports:read` scope; creating one also requires `imports:write`.