> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import and export product files

> Start CSV and Excel product exports and imports through the API, poll them as jobs, and download the finished export file with a one-hour link.

File exports and imports run the same pipelines as the export dialog and the import wizard in the WISEPIM app. Use them when another system works with whole files: a nightly CSV feed for a marketplace, an Excel price list from a supplier, or a full catalog snapshot for a backup. For record-by-record sync, the [product endpoints](https://docs.wisepim.com/en/api-reference/products/batch.md) are usually a better fit.

Both are background jobs. A `202 Accepted` response means WISEPIM accepted the work and gave it a `task_id`. It does not mean the file exists or the products changed. Poll [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get) to find out when the work has finished.

## Endpoints and scopes

| Endpoint | Required scopes | Purpose |
| - | - | - |
| [`POST /exports`](https://docs.wisepim.com/en/api-reference/transfers/start-export) | `products:read` + `exports:execute` | Queue a CSV or Excel export |
| [`GET /exports/{task_id}/download`](https://docs.wisepim.com/en/api-reference/transfers/download-export) | `products:read` + `exports:execute` | Get a one-hour link to the finished file |
| [`POST /imports`](https://docs.wisepim.com/en/api-reference/transfers/start-import) | `products:write` + `imports:execute` | Queue a CSV or Excel import that uses a saved import template |
| [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get) | `jobs:read` | Read the status and progress counters of either job |

Add `jobs:read` to the key if the integration polls for results, which almost every integration does. Existing keys do not gain new scopes. Create a replacement key with the [scopes](https://docs.wisepim.com/en/api-reference/authentication.md#scopes) you need.

### What the person who created the key must be allowed to do

A key never has more authority than the project member who created it. WISEPIM checks that member's role on every request, not only when the key was created.

* `exports:execute` stands in for the role's **Export** product permission. `imports:execute` stands in for the role's **Import** product permission. If the role loses that permission, requests return `403 issuer_permission_denied`.
* Like every `:execute`, `:write` and `:delete` scope, both also require that the member can still **edit** the project. If they cannot, requests return `403 issuer_cannot_write`.

> [!WARNING]
>
> A viewer cannot use an export key, even when their role lets them export in the web app. Export keys need edit access because they start work on the project. Have a member with edit access create the key.

## Export products to a file

An export has three parts: the file format, the layout (which columns appear and how they are named), and the selection (which products appear).

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/exports \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: nightly-export-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "export_template_id": 12, "export_locales": ["en", "nl"]}'
```

```json theme={null}
{
  "task_id": "6f1c2a7e-3b4d-4e8a-9c21-5d0f7b8e1a44",
  "task_type": "csv_export",
  "status": "pending",
  "total_items": 4812
}
```

`total_items` is the number of products WISEPIM expects to write. Save `task_id`; you need it to poll the job and to download the file.

### Format

`format` is `csv` (the default) or `excel`. The job's `task_type` is `csv_export` or `excel_export` to match.

An Excel file holds one worksheet. An Excel export with more than 1,048,574 products, or with more columns than Excel allows (16,384), fails. WISEPIM does not cut the file short: the job ends as `failed`, and retrying it gives the same result. Use `csv` for very large catalogs.

### Layout

The layout decides the columns. Pick one of these:

| Option | Body | Result |
| - | - | - |
| Project default | Leave out `export_template_id` and `preset_code` | The project's default export template |
| Saved template | `"export_template_id": 12` | One of the project's active [export templates](https://docs.wisepim.com/en/api-reference/export-templates/list.md) |
| Built-in preset | `"preset_code": "shopify_csv"` | A ready-made layout: `shopify_csv`, `akeneo_csv` or `google_merchant_csv` |
| Plain layout | `"use_default_template": false` | No template; the plain export layout |

Send `export_template_id` or `preset_code`, never both. A template that is inactive or belongs to another project returns `404 not_found`. An unknown preset returns `422 unknown_preset_code`.

### Selection

Send at most one selector. With none, the export contains **every product in the project**.

| Selector | Accepts | Notes |
| - | - | - |
| `product_ids` | 1 to 1,000 distinct product IDs | Every ID must exist in the key's project |
| `skus` | 1 to 1,000 distinct SKUs | Every SKU must exist in the key's project |
| `category_id` | One category ID | The category's products and the variants of its products, as the product grid shows them |
| (none) | | The whole project |

If any ID or SKU in the list is unknown, the whole request fails with `404 selection_not_found`. Nothing is exported partially. An unknown category returns `404 not_found`. Sending two selectors returns a `422` validation error.

> [!TIP]
>
> To export more than 1,000 specific products, use a category or the whole project, or split the list across several exports.

### Locales and other options

| Field | Values | Effect |
| - | - | - |
| `export_locales` | 1 to 25 distinct locale codes | Which content languages to include. Every locale must be enabled on the project, otherwise `422 invalid_locales`. [`GET /project`](https://docs.wisepim.com/en/api-reference/key/project) lists the enabled locales. |
| `split_locale_files` | `true` or `false` (default) | Write one file per locale, as the export dialog does. With `format` `csv`, the download is a single `.zip` archive that holds one CSV per locale. |
| `uom_export_mode` | `default`, `append`, `separate`, `ignore` | How units of measure appear, as in the export dialog. Defaults to `default`. |

### Wait for the export to finish

Poll [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get) until `status` is final:

| `status` | Meaning | Next step |
| - | - | - |
| `pending`, `running` | Still running | Wait and poll again |
| `completed`, `completed_with_errors` | A file is ready | Call the download endpoint |
| `failed`, `cancelled`, `stopped` | Ended without a file | Check the job, fix the cause, start a new export |

Poll every 5 to 30 seconds. A large project can take several minutes.

## Download the export

```bash theme={null}
curl "https://wisepim.com/api/public/v1/exports/$TASK_ID/download" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

```json theme={null}
{
  "task_id": "6f1c2a7e-3b4d-4e8a-9c21-5d0f7b8e1a44",
  "download_url": "https://storage.example.com/exports/...&X-Amz-Expires=3600&X-Amz-Signature=...",
  "filename": "products_export_2026-11-20.csv",
  "expires_in": 3600,
  "product_count": 4812,
  "export_format": "csv",
  "finished_at": "2026-11-20T02:04:31Z"
}
```

`filename` has the real extension of the file: `.csv`, `.xlsx`, or `.zip` for a CSV export with `split_locale_files`. Use it when you save the file instead of assuming `.csv`.

Then fetch `download_url` with a plain `GET`. The link is signed and works for **one hour** (`expires_in` is in seconds). Do not send your API key to it; the link carries its own signature. When it expires, call the download endpoint again for a fresh link. You do not need to export again.

### Why the response is JSON and not a redirect

The endpoint returns the link in a JSON body instead of redirecting you to the file. Many HTTP clients follow redirects and resend headers, so a redirect could pass your `Authorization` header to the storage host. A JSON response keeps your key on WISEPIM. It also gives you `filename`, `product_count` and `finished_at` before you download, so you can check the file is the one you expect.

### When the download endpoint returns 409

| Code | Cause | What to do |
| - | - | - |
| `export_not_ready` | The job is still running | Keep polling [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get), then try again |
| `export_failed` | The job ended without a file (`failed`, `cancelled` or `stopped`). The body's `status` says which. | Start a new export |
| `export_file_unavailable` | The job finished, but WISEPIM cannot confirm the file belongs to this project | Start a new export |

The download endpoint only signs files from the key's own project. Exports that finished before WISEPIM started recording which project a file's rows came from can never be downloaded with an API key. They return `export_file_unavailable`. Run the export again to get a file you can download.

A `task_id` that is not an export in this project returns `404 not_found`.

## Example: nightly export

This script starts one export a night, waits for it and saves the file under the name WISEPIM returns. The `Idempotency-Key` contains the date, so if the script crashes and runs again the same night, WISEPIM returns the original `task_id` instead of starting a second export.

Reusing a key with a different body returns `409 idempotency_conflict`. If you change the template, locales or selection during the day, the next run that day needs a different key, for example one with a version suffix. WISEPIM keeps each key for 30 days; after that the key can be used again.

```python Python theme={null}
import datetime
import os
import time

import requests

BASE = "https://wisepim.com/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WISEPIM_API_KEY']}"}
FINAL = {"completed", "completed_with_errors", "failed", "cancelled", "stopped"}

today = datetime.date.today().isoformat()

# 1. Start the export. Retrying with the same key returns the same task.
start = requests.post(
    f"{BASE}/exports",
    headers={**HEADERS, "Idempotency-Key": f"nightly-export-{today}"},
    json={"format": "csv", "export_template_id": 12, "export_locales": ["en", "nl"]},
    timeout=30,
)
start.raise_for_status()
task_id = start.json()["task_id"]

# 2. Poll the job until it reaches a final status.
while True:
    job = requests.get(f"{BASE}/jobs/{task_id}", headers=HEADERS, timeout=30)
    job.raise_for_status()
    status = job.json()["status"]
    if status in FINAL:
        break
    time.sleep(15)

if status not in {"completed", "completed_with_errors"}:
    raise SystemExit(f"Export {task_id} ended as {status}")

# 3. Get the signed link, then download it without the API key.
link = requests.get(f"{BASE}/exports/{task_id}/download", headers=HEADERS, timeout=30)
link.raise_for_status()
info = link.json()

with requests.get(info["download_url"], stream=True, timeout=300) as file:
    file.raise_for_status()
    # filename ends in .csv, .xlsx or .zip; basename() keeps it in this folder.
    with open(os.path.basename(info["filename"]), "wb") as out:
        for chunk in file.iter_content(chunk_size=1 << 20):
            out.write(chunk)

print(f"Saved {info['product_count']} products from {info['filename']}")
```

```javascript Node.js theme={null}
import { writeFile } from "node:fs/promises";
import { basename } from "node:path";

const BASE = "https://wisepim.com/api/public/v1";
const HEADERS = { Authorization: `Bearer ${process.env.WISEPIM_API_KEY}` };
const FINAL = new Set(["completed", "completed_with_errors", "failed", "cancelled", "stopped"]);
const today = new Date().toISOString().slice(0, 10);

async function api(path, init = {}) {
  const res = await fetch(`${BASE}${path}`, { ...init, headers: { ...HEADERS, ...init.headers } });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

// 1. Start the export. Retrying with the same key returns the same task.
const { task_id } = await api("/exports", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Idempotency-Key": `nightly-export-${today}` },
  body: JSON.stringify({ format: "csv", export_template_id: 12, export_locales: ["en", "nl"] }),
});

// 2. Poll the job until it reaches a final status.
let status;
do {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  ({ status } = await api(`/jobs/${task_id}`));
} while (!FINAL.has(status));

if (status !== "completed" && status !== "completed_with_errors") {
  throw new Error(`Export ${task_id} ended as ${status}`);
}

// 3. Get the signed link, then download it without the API key.
const info = await api(`/exports/${task_id}/download`);
const file = await fetch(info.download_url);
if (!file.ok) throw new Error(`Download failed: ${file.status}`);
// filename ends in .csv, .xlsx or .zip; basename() keeps it in this folder.
await writeFile(basename(info.filename), Buffer.from(await file.arrayBuffer()));

console.log(`Saved ${info.product_count} products from ${info.filename}`);
```

## Import a file

An import always uses a **saved import template**. The template holds everything the import wizard asks you for: which column maps to which field, value choices, transformations and how to handle products that already exist. Build and test the template once in the app, then find its ID with [`GET /import-templates`](https://docs.wisepim.com/en/api-reference/import-templates/list).

**1. Build the template in the app**

Run the import once in the import wizard with a sample file and save the mapping as a template. Make sure it does not depend on choices you made by hand (see [Templates that cannot run unattended](#templates-that-cannot-run-unattended)).

**2. Start the import**

Send `import_template_id` and the file, either as a URL or inline.

**3. Poll the job**

Poll [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get) and check `successful_items`, `failed_items` and `skipped_items` as well as `status`.

### Send the file from a URL

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/imports \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: supplier-prices-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{
    "import_template_id": 7,
    "file_url": "https://feeds.example-supplier.com/wisepim/prices-2026-11-20.csv",
    "duplicate_handling": {"strategy": "update", "identifiers": ["sku"], "new_products": "skip"}
  }'
```

```json theme={null}
{
  "task_id": "b2e48f10-7c3a-4d95-a1f6-0e8d2c9b4f73",
  "task_type": "csv_import",
  "status": "pending",
  "total_items": 1250
}
```

WISEPIM downloads the file once, while it handles your request. The download has these limits:

* **http or https only**, and only to public addresses. WISEPIM looks up the host name once and connects only to the address it checked, so the host cannot point the request at an internal address. Every redirect is checked the same way. A refused address returns `422 file_fetch_failed` with a fixed message that does not name the host or its addresses.
* **50 MiB** at most by default.
* **30 seconds** in total for connecting, headers, redirects and the body. One stalled read can add up to 10 seconds more.
* **Uncompressed.** WISEPIM asks for the file without compression. If the server still sends it with `Content-Encoding` such as `gzip`, `br` or `zstd`, the import fails with `422 file_fetch_failed`. Configure the server to send the plain file.

WISEPIM picks the file reader from `file_name`, or from the last part of the URL path when you leave `file_name` out.

* If that name has no extension, WISEPIM looks at the content. XML is refused with `422 unsupported_file_type`. Anything else is read as Excel or CSV.
* If the URL ends in something other than `.csv`, `.xls` or `.xlsx`, for example `/export.php`, WISEPIM does not look at the content and the import checks reject the file. Set `file_name` (for example `"prices.csv"`) for these URLs.

### Send the file inline

For files your integration already holds, send the contents as base64 with a `file_name`. The extension in `file_name` tells WISEPIM whether it is CSV or Excel.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/imports \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: erp-stock-2026-11-20-0600" \
  -H "Content-Type: application/json" \
  -d "{\"import_template_id\": 7, \"file_name\": \"stock.xlsx\", \"sheet_name\": \"Stock\", \"file_base64\": \"$(base64 < stock.xlsx | tr -d '\n')\"}"
```

The whole request, including the base64 text, must fit within the **10 MiB** request limit. Base64 makes a file about a third larger, so the file itself must be under about 7.5 MiB. A larger body returns `413 payload_too_large` with `max_bytes`. Use `file_url` for larger files. Invalid base64 or an empty file returns `422 invalid_file`.

Send exactly one of `file_url` and `file_base64`. Multipart file uploads and XML feeds are not available on this endpoint.

### Override the template for one run

The template's settings apply unless you override them in the request. Overrides apply to this run only and do not change the saved template.

| Field | Values | Effect |
| - | - | - |
| `duplicate_handling.strategy` | `update`, `skip` | Update products that already exist, or leave them unchanged |
| `duplicate_handling.identifiers` | `["sku"]`, `["ean"]`, `["sku", "ean"]` | Which columns identify an existing product |
| `duplicate_handling.new_products` | `create`, `skip` | Create products that do not exist yet, or skip them |
| `sheet_name` | Sheet name | Which sheet of an Excel file to read |

> [!TIP]
>
> For an **update-only** import, such as a price or stock file that must never create new products, send `"strategy": "update"` and `"new_products": "skip"`.

Two combinations are refused with `422 invalid_duplicate_handling`:

* `"strategy": "skip"` together with `"new_products": "skip"`, because the import would change nothing.
* Matching on a column the template does not map. Matching needs a mapped SKU column, or a mapped EAN column with `ean` in `identifiers`.

### Templates that cannot run unattended

In the import wizard a person can confirm choices as the import runs. The API has no one to ask, so WISEPIM refuses templates that would need that. The response is `422 import_template_not_runnable`, usually with a `reasons` list:

| Reason | Meaning | Fix in the import wizard |
| - | - | - |
| `unsupported_or_missing_target:<target>` | A column maps to a field that does not exist or cannot be imported | Remap or remove that column |
| `schema_creation_requires_separate_acceptance` | The template would create new fields or attributes | Create them first, then map to them |
| `option_creation_requires_separate_acceptance` | The template would create new options for a select attribute | Add the options first, or change the template's value handling |
| `sku_or_ean_identity_required` | The template has no SKU or EAN to identify products | Map a SKU or EAN column |
| `policy_would_import_nothing` | The duplicate settings skip both existing and new products | Change the duplicate handling |
| `platform_adapter_not_supported` | The template is built for a platform-specific format | Use a template for a plain CSV or Excel file |

Fix the template in the app and start the import again. The `reasons` list can contain more than one entry.

When the saved template configuration itself is invalid, the same code comes back **without** `reasons`, and `error` describes the problem. Examples are two columns mapped to the same field and locale, a localized value on a field that cannot be localized, or invalid duplicate, separator or value settings. Read `reasons` only when it is present.

### One import at a time

One CSV or Excel import can be active (pending or running) at a time across **all projects of the project owner's account**. That includes imports started in the WISEPIM app, not only the ones your key started. This limit is separate from the per-key rate limit.

* Starting different work while an import is active returns `429 import_capacity` with `active_task_id`, the job that is still active. Poll that job and start the next import once it has finished.
* Starting the identical file with the identical template and options in the same project returns `202` with the task that is already active. No second import runs.

### Retrying an import

Send an `Idempotency-Key` with every import. A retry with the same key and body returns the original `task_id` and does not download the file again. Use a new key for each new file. If a file at the same URL changes between runs, put the date or a version in the key so each run is a new import.

Reusing a key with a different body, for example another template or other overrides on the same day, returns `409 idempotency_conflict`. Keys are kept for 30 days and can be reused after that.

### Check the result

`202` means the import was queued. The same checks that run in the import wizard reject unreadable files and mapping problems before the job starts:

* Most rejections return `422`, with `code` set to `import_rejected` or a more specific code from those checks.
* Some keep their own status: `403 import_rejected` when the import is not allowed, and `409 supplier_contract_changed` when the file's columns no longer match the supplier contract the template is bound to.
* `500 import_start_failed` means WISEPIM could not start the import. Try again later.

Branch on `code` and show `error` to the person who owns the file.

> [!NOTE]
>
> A `422` with no `code` means the request body failed schema validation. Examples are two export selectors, both `file_url` and `file_base64`, `file_base64` without `file_name`, or the same locale listed twice. The body has `"error": "Validation error"` and a `detail` list with the field errors.

The import task's `task_type` is `csv_import` for both CSV and Excel files. Once the job has finished, read `successful_items`, `failed_items` and `skipped_items` from [`GET /jobs/{task_id}`](https://docs.wisepim.com/en/api-reference/jobs/get). Then read the affected products, or call [`GET /products?updated_since=...`](https://docs.wisepim.com/en/api-reference/products/list), to confirm the changes.

## Common errors

| Status and code | Endpoint | Cause | What to do |
| - | - | - | - |
| `403 insufficient_scope` | All | The key lacks a required scope. `missing_scopes` lists them. | Create a key with the scopes in [Endpoints and scopes](#endpoints-and-scopes) |
| `403 issuer_cannot_write` | All | The member who created the key can no longer edit the project, for example a viewer | Have a member with edit access create the key |
| `403 issuer_permission_denied` | All | That member's role no longer has the Export or Import permission | Restore the permission or use another member's key |
| `404 selection_not_found` | `POST /exports` | One or more `product_ids` or `skus` are not in this project | Remove the unknown values and start again |
| `404 not_found` | All | Unknown or inactive template, unknown category, or a `task_id` that is not an export in this project | Check the ID against the project |
| `422 invalid_locales` | `POST /exports` | A locale is not enabled on the project, or two locales differ only in spelling (for example `en` and `EN`) | Use each locale from [`GET /project`](https://docs.wisepim.com/en/api-reference/key/project) once |
| `422` (no `code`) | `POST /exports`, `POST /imports` | The body failed schema validation, for example two selectors, both file sources, or the same locale twice | Read `detail` for the field errors |
| `409 idempotency_conflict` | `POST /exports`, `POST /imports` | The same `Idempotency-Key` was sent with a different request | Use a new key for new work |
| `413 payload_too_large` | `POST /imports` | The request body is over 10 MiB, usually a large `file_base64` | Send the file with `file_url` instead |
| `422 unknown_preset_code` | `POST /exports` | `preset_code` is not a known preset | Use `shopify_csv`, `akeneo_csv` or `google_merchant_csv` |
| `409 export_not_ready` | Download | The export is still running | Poll the job, then try again |
| `409 export_failed` | Download | The export ended without a file | Start a new export |
| `409 export_file_unavailable` | Download | The file cannot be confirmed as this project's, including exports from before project tracking | Start a new export |
| `422 import_template_not_runnable` | `POST /imports` | The template needs a person to confirm choices (see `reasons`), or its saved configuration is invalid (no `reasons`; read `error`) | Fix the template in the import wizard |
| `422 invalid_duplicate_handling` | `POST /imports` | The overrides would import nothing, or match on an unmapped column | Change `duplicate_handling` |
| `422 file_fetch_failed` | `POST /imports` | The URL is not public, timed out, returned an error, is too large or is compressed | Check the URL and the server's response, or send the file inline |
| `422 invalid_file` | `POST /imports` | `file_base64` is not valid base64, or the file is empty | Re-encode the file |
| `422 unsupported_file_type` | `POST /imports` | The downloaded file has no extension and its content is XML | Send a CSV or Excel file |
| `422 import_rejected` | `POST /imports` | The file or mapping failed the import checks (`403` when the import is not allowed) | Read `error`, fix the file or template |
| `409 supplier_contract_changed` | `POST /imports` | The file's columns no longer match the supplier contract the template is bound to | Review the template in the import wizard |
| `429 import_capacity` | `POST /imports` | Different import work is already active on the project owner's account | Wait for `active_task_id` to finish |
| `500 import_start_failed` | `POST /imports` | WISEPIM could not start the import | Try again later |
| `429 rate_limited` | All | Over the per-key rate limit | Wait for `Retry-After` |
| `503 task_admission_blocked` | `POST /exports` | WISEPIM is not accepting new jobs right now | Retry after `retry_after_seconds` with the same `Idempotency-Key` |

## Related

> [card] [Actions and jobs](https://docs.wisepim.com/en/api-reference/actions-and-jobs.md)
>
> How background jobs work, what the progress counters mean and how to cancel a job.

> [card] [Products and variants](https://docs.wisepim.com/en/api-reference/products-and-variants.md)
>
> Sync products record by record when a whole file is more than you need.

> [card] [Import templates](https://docs.wisepim.com/en/api-reference/import-templates/list.md)
>
> List the saved templates your imports can use.

> [card] [Authentication and scopes](https://docs.wisepim.com/en/api-reference/authentication.md#scopes)
>
> Every scope, and how the key creator's role limits what a key can do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.