Skip to main content
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 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} to find out when the work has finished.

Endpoints and scopes

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 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.
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).
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: 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. 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.
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

Wait for the export to finish

Poll GET /jobs/{task_id} until status is final: Poll every 5 to 30 seconds. A large project can take several minutes.

Download the export

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

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.

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.
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).
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} and check successful_items, failed_items and skipped_items as well as status.

Send the file from a URL

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.
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.
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: 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.
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}. Then read the affected products, or call GET /products?updated_since=..., to confirm the changes.

Common errors

Actions and jobs

How background jobs work, what the progress counters mean and how to cancel a job.

Products and variants

Sync products record by record when a whole file is more than you need.

Import templates

List the saved templates your imports can use.

Authentication and scopes

Every scope, and how the key creator’s role limits what a key can do.