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:executestands in for the role’s Export product permission.imports:executestands in for the role’s Import product permission. If the role loses that permission, requests return403 issuer_permission_denied.- Like every
:execute,:writeand:deletescope, both also require that the member can still edit the project. If they cannot, requests return403 issuer_cannot_write.
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.
Locales and other options
Wait for the export to finish
PollGET /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 yourAuthorization 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. TheIdempotency-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 withGET /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
- 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_failedwith 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-Encodingsuch asgzip,brorzstd, the import fails with422 file_fetch_failed. Configure the server to send the plain file.
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,.xlsor.xlsx, for example/export.php, WISEPIM does not look at the content and the import checks reject the file. Setfile_name(for example"prices.csv") for these URLs.
Send the file inline
For files your integration already holds, send the contents as base64 with afile_name. The extension in file_name tells WISEPIM whether it is CSV or Excel.
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.
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
eaninidentifiers.
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 is422 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_capacitywithactive_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
202with the task that is already active. No second import runs.
Retrying an import
Send anIdempotency-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, withcodeset toimport_rejectedor a more specific code from those checks. - Some keep their own status:
403 import_rejectedwhen the import is not allowed, and409 supplier_contract_changedwhen the file’s columns no longer match the supplier contract the template is bound to. 500 import_start_failedmeans WISEPIM could not start the import. Try again later.
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.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
Related
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.

