Imports

Imports let you load large volumes of products into your catalog from CSV, Excel, JSON, or XML files. Jobs are processed asynchronously — poll the job status endpoint to know when they complete.

All import endpoints are under the /api/v1/imports prefix, except mapping templates (/api/v1/mapping-templates) and recurring automations (/api/v1/import-configs), which are separate routers.

Job lifecycle

A job moves through some or all of these statuses depending on its source and size. Large files (≥ 5,000 rows) are queued on Celery (queued → downloading/persisting); small files run inline.

pending → analyzing → awaiting_mapping → ready → processing → completed
   ↓          ↓                                       ↓      → completed_with_errors
queued   downloading                              persisting → failed
                                                              → cancelled
                                                              → paused

Status	Description
`pending`	Queued, not yet started
`queued`	Large file handed off to a Celery worker
`connecting` / `downloading`	Fetching the source file (FTP/SFTP/email/URL)
`analyzing`	File is being parsed and headers detected
`awaiting_mapping`	File analyzed, column mapping required before proceeding
`ready`	Mapping saved (or auto-detected), ready to process
`processing` / `persisting`	Rows are being validated and written to the catalog
`paused`	Temporarily suspended (e.g. multi-instance coordination)
`completed`	Finished with no errors
`completed_with_errors`	Finished, but some rows failed (see job errors)
`failed`	Aborted due to a critical error
`cancelled`	Cancelled by the user

A job in failed, cancelled, or completed_with_errors can be retried.

POST/imports/upload

Upload a file

Starts a new import job by uploading a file via multipart/form-data. The file is analyzed immediately; the job reaches awaiting_mapping (if column mapping is required) or pending/ready (if a template is provided and matches automatically).

Body parameters (multipart/form-data)

Name
file
Type
file
Description
The import file. Accepted formats: .csv, .xlsx, .json, .xml.
Name
supplier_code
Type
string
Description
Supplier code to associate with all imported products.
Name
supplier_id
Type
string
Description
UUID of the supplier record (alternative to supplier_code).
Name
template_id
Type
string
Description
UUID of a saved mapping template to apply automatically.
Name
import_type
Type
string
Description
Import type identifier (default: "manual").
Name
auto_process
Type
boolean
Description
If true and a template is provided, start processing immediately after analysis (default: false). If false, the job stops at pending/awaiting_mapping so the mapping can be reviewed first.
Name
skip_header_rows
Type
integer
Description
Number of leading rows to skip before the header row (default: 0).
Name
sheet_name
Type
string
Description
For .xlsx files, the worksheet to read. Omit to use the first sheet.

The file field is the only required parameter. The response's data.file_analysis includes suggested_mapping (auto-detected column → field mapping) and suggested_languages (column → language code, guessed from header suffixes such as title_en, among your enabled languages only) as a convenience — the mapping you save is always what you send to POST /imports/{import_id}/save-mapping.

Request

POST

/imports/upload

curl -X POST https://api.pixeepim.com/api/v1/imports/upload \
  -H "Authorization: Bearer {api_key}" \
  -F "file=@catalog.csv" \
  -F "supplier_code=SUPPLIER_A" \
  -F "auto_process=false"

Response

{
  "status": "success",
  "message": "File uploaded successfully and queued for processing",
  "data": {
    "file_info": {
      "original_filename": "catalog.csv",
      "size": 524288,
      "extension": ".csv",
      "content_type": "text/csv"
    },
    "file_analysis": {
      "columns": ["EAN", "Titre", "Prix HT"],
      "row_count": 1250,
      "sample_data": [{ "EAN": "3760000000001", "Titre": "Widget Pro", "Prix HT": "29.99" }],
      "suggested_mapping": { "EAN": "ean", "Titre": "title", "Prix HT": "price" },
      "suggested_languages": {}
    },
    "import_job": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "created_at": "2026-09-15T09:00:00Z"
    }
  },
  "processing_method": "async"
}

POST/imports/upload-from-url

Upload from URL

Starts an import job by fetching a file from a public URL. Useful for one-off downloads without configuring a full FTP/SFTP automation.

Body parameters (JSON)

Name
url
Type
string
Description
Public URL of the file to import (HTTP or HTTPS).
Name
supplier_id
Type
string
Description
UUID of the supplier to link imported products to.
Name
template_id
Type
string
Description
UUID of a saved mapping template to apply automatically.
Name
skip_header_rows
Type
integer
Description
Number of rows to skip before the header (default: 0).
Name
sheet_name
Type
string
Description
For .xlsx files, the worksheet to read. Omit to use the first sheet.

Request

POST

/imports/upload-from-url

curl -X POST https://api.pixeepim.com/api/v1/imports/upload-from-url \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://supplier.com/exports/products.xlsx",
    "supplier_id": "b1e9c3d2-1111-4abc-8def-000000000001",
    "sheet_name": "Catalogue"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "status": "analyzing",
  "created_at": "2026-09-15T10:00:00Z"
}

POST/imports/detect-format

Detect file format

Analyzes a sample of a CSV file to detect its character encoding and delimiter, without creating an import job. Useful to pre-fill an automated import config (encoding, delimiter) before the first run.

Body parameters (multipart/form-data)

Name
file
Type
file
Description
A sample of the file to analyze.

Request

POST

/imports/detect-format

curl -X POST https://api.pixeepim.com/api/v1/imports/detect-format \
  -H "Authorization: Bearer {api_key}" \
  -F "file=@sample.csv"

Response

{
  "encoding": "utf-8",
  "delimiter": ";",
  "encoding_confidence": 0.99,
  "sample_rows": 100
}

POST/imports/import/ftp

Import via FTP / SFTP / email

Trigger a one-off import by fetching a file from a remote FTP, SFTP, or email (IMAP) source. These endpoints create a job immediately and return its ID; the file is then downloaded and analyzed in the background.

FTP — `POST /imports/import/ftp`

Name
host
Type
string
Description
FTP server hostname or IP.
Name
port
Type
integer
Description
FTP port (default: 21).
Name
username
Type
string
Description
FTP username.
Name
password
Type
string
Description
FTP password.
Name
directory_path
Type
string
Description
Remote directory to scan.
Name
file_pattern
Type
string
Description
Glob pattern to filter files (default: *.csv).
Name
supplier_code
Type
string
Description
Supplier code to associate with imported products.

SFTP — `POST /imports/import/sftp`

Name
host
Type
string
Description
SFTP server hostname.
Name
port
Type
integer
Description
SFTP port (default: 22).
Name
username
Type
string
Description
SFTP username.
Name
password
Type
string
Description
Password (alternative to key-based auth).
Name
key_file_path
Type
string
Description
Path to the private key file on the server.
Name
key_passphrase
Type
string
Description
Passphrase for the private key, if any.
Name
directory_path
Type
string
Description
Remote directory to scan.
Name
file_pattern
Type
string
Description
Glob pattern to filter files (default: *.csv).
Name
supplier_code
Type
string
Description
Supplier code to associate with imported products.

Excel sheet selection (sheet_name) is not exposed on this one-off SFTP endpoint. For a recurring SFTP source that reads a specific worksheet, use an automated import config with import_type: "sftp", which does accept sheet_name.

Email (IMAP) — `POST /imports/import/email`

Name
imap_host
Type
string
Description
IMAP server hostname.
Name
imap_port
Type
integer
Description
IMAP port (default: 993).
Name
email
Type
string
Description
Email address to connect with.
Name
password
Type
string
Description
Email account password or app password.
Name
folder
Type
string
Description
IMAP folder to scan (default: INBOX).
Name
sender_filter
Type
string
Description
Only process emails from this sender address.
Name
subject_filter
Type
string
Description
Only process emails whose subject matches.
Name
unseen_only
Type
boolean
Description
Only process unread emails (default: true).
Name
mark_as_read
Type
boolean
Description
Mark processed emails as read (default: true).
Name
supplier_code
Type
string
Description
Supplier code to associate with imported products.

FTP request

POST

/imports/import/ftp

curl -X POST https://api.pixeepim.com/api/v1/imports/import/ftp \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "ftp.supplier.com",
    "username": "ftpuser",
    "password": "s3cr3t",
    "directory_path": "/exports",
    "file_pattern": "products_*.csv",
    "supplier_code": "SUPPLIER_A"
  }'

SFTP request

POST

/imports/import/sftp

curl -X POST https://api.pixeepim.com/api/v1/imports/import/sftp \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "sftp.supplier.com",
    "username": "sftpuser",
    "key_file_path": "/keys/supplier_rsa",
    "directory_path": "/exports",
    "supplier_code": "SUPPLIER_A"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440020",
  "supplier_code": "SUPPLIER_A",
  "import_type": "ftp",
  "status": "pending",
  "message": "FTP import from ftp.supplier.com queued for processing"
}

GET/imports/

List jobs

Returns a paginated list of import jobs, ordered by creation date (most recent first). Supports either offset (page/per_page) or cursor pagination.

Query parameters

Name
status
Type
string
Description
Filter by job status (e.g. completed, failed, processing).
Name
supplier_code
Type
string
Description
Filter by supplier code.
Name
page
Type
integer
Description
Page number, offset mode (default: 1).
Name
per_page
Type
integer
Description
Items per page, max 100 (default: 20).
Name
use_cursor
Type
boolean
Description
Use cursor pagination instead of page/per_page (default: false).
Name
cursor
Type
string
Description
Opaque cursor returned by a previous call, when use_cursor=true.
Name
limit
Type
integer
Description
Page size in cursor mode.

Request

GET

/imports/

curl "https://api.pixeepim.com/api/v1/imports/?status=failed&page=1&per_page=20" \
  -H "Authorization: Bearer {api_key}"

Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed",
      "file_name": "catalog.csv",
      "supplier_code": "SUPPLIER_A",
      "total_rows": 1250,
      "failed_rows": 1250,
      "created_at": "2026-09-15T09:00:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 20, "total_pages": 1, "has_next": false, "has_previous": false }
}

GET/imports/templates

Import templates

Returns the built-in field templates available to configure a column mapping (as opposed to a saved mapping template, which is a specific supplier's reusable mapping). Created on first call if none exist yet.

Request

GET

/imports/templates

curl https://api.pixeepim.com/api/v1/imports/templates \
  -H "Authorization: Bearer {api_key}"

Response

{ "templates": [{ "id": "generic", "name": "Generic catalog", "fields": ["ean", "title", "price"] }] }

GET/imports/{import_id}

Get a job

Returns the full detail of a single import job, including progress counters.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Key response fields

Name
status
Type
string
Description
Current status — see job lifecycle.
Name
current_step
Type
string
Description
Human-readable description of what the job is doing right now.
Name
total_rows
Type
integer
Description
Total rows detected in the file.
Name
processed_rows
Type
integer
Description
Rows processed so far.
Name
successful_rows
Type
integer
Description
Rows imported without error.
Name
failed_rows
Type
integer
Description
Rows that raised a blocking error.
Name
skipped_rows
Type
integer
Description
Rows skipped (e.g. duplicates, empty lines).
Name
products_created
Type
integer
Description
New products created.
Name
products_updated
Type
integer
Description
Existing products updated.
Name
prices_updated
Type
integer
Description
Supplier price relations updated.
Name
stock_updated
Type
integer
Description
Stock quantities updated.
Name
error_count
Type
integer
Description
Total error-level rows.
Name
warning_count
Type
integer
Description
Total warning-level rows.
Name
duration_seconds
Type
integer
Description
Wall-clock processing time, once finished.

Request

GET

/imports/{import_id}

curl https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {api_key}"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed_with_errors",
  "current_step": null,
  "file_name": "catalog.csv",
  "supplier_code": "SUPPLIER_A",
  "total_rows": 1250,
  "processed_rows": 1250,
  "successful_rows": 1245,
  "failed_rows": 5,
  "skipped_rows": 0,
  "products_created": 980,
  "products_updated": 265,
  "prices_updated": 1240,
  "stock_updated": 1180,
  "error_count": 5,
  "warning_count": 12,
  "duration_seconds": 94,
  "started_at": "2026-09-15T09:00:00Z",
  "completed_at": "2026-09-15T09:01:34Z",
  "created_at": "2026-09-15T08:59:55Z"
}

GET/imports/{import_id}/errors

Job errors

Returns per-row errors for a job, with a classified error_type (cause) and severity.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Query parameters

Name
page
Type
integer
Description
Page number (default: 1).
Name
per_page
Type
integer
Description
Items per page, max 200 (default: 50).
Name
offset
Type
integer
Description
Row offset, alternative to page.
Name
error_type
Type
string
Description
Filter by cause, e.g. ean_checksum_invalid, ean_missing, ean_format_invalid, ean_too_short, ean_too_long, ean_non_numeric, missing_required_field.
Name
severity
Type
string
Description
Filter by severity: error or warning.
Name
search
Type
string
Description
Full-text search within error messages.

Request

GET

/imports/{import_id}/errors

curl "https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/errors?error_type=ean_checksum_invalid" \
  -H "Authorization: Bearer {api_key}"

Response

{
  "items": [
    {
      "row_number": 42,
      "severity": "error",
      "error_type": "ean_checksum_invalid",
      "field": "ean",
      "message": "EAN checksum invalide",
      "raw_value": "123ABC7890",
      "created_at": "2026-09-15T09:01:30Z"
    }
  ],
  "meta": { "total": 5, "page": 1, "per_page": 50, "total_pages": 1, "has_next": false, "has_previous": false }
}

GET/imports/{import_id}/report

Download report / invalid EANs

Two CSV downloads for a finished job:

Endpoint	Content
`GET /imports/{import_id}/report`	Full report: job summary and every error row
`GET /imports/{import_id}/export-invalid-eans`	Rows filtered to EAN-related causes only (`ean_missing`, `ean_checksum_invalid`, `ean_format_invalid`, `ean_too_short`, `ean_too_long`, `ean_non_numeric`, `ean_finder_pending`, `ean_pending_resolution`), with the raw SKU/name/EAN echoed for each row

Both return text/csv as a streaming download, capped to the job's stored errors (MAX_ERRORS_PER_REPORT).

Request

GET

/imports/{import_id}/report

curl https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/report \
  -H "Authorization: Bearer {api_key}" -o report.csv

Invalid EANs

GET

/imports/{import_id}/export-invalid-eans

curl https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/export-invalid-eans \
  -H "Authorization: Bearer {api_key}" -o invalid_eans.csv

POST/imports/{import_id}/save-mapping

Save column mapping

Saves the column mapping for a job in awaiting_mapping status. After this call the job moves to ready and can be processed.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Body parameters (JSON)

Name
column_mapping
Type
object
Description
Map of file column names to a target: either a field name string ("ean"), or an object {"field": "title", "language": "en"} to route a column to a specific enabled language.
Name
validation_rules
Type
object
Description
Optional per-field validation overrides.
Name
import_options
Type
object
Description
Optional processing options (e.g. {"overwrite_existing": true}).

Row-level supplier fields are ordinary mapping targets: supplier_code carries the supplier for that row (a file can mix several suppliers), and supplier_cost_price carries that row's purchase price for it. This is separate from primary_supplier_code / primary_supplier_name, which name the article's constant principal supplier and must be mapped as a pair — the name alone cannot be attributed to a supplier without its code. When a file maps both cost_price and price (or price_excluding_tax), the purchase price is read in the order cost_price → price → price_excluding_tax.

Request

POST

/imports/{import_id}/save-mapping

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/save-mapping \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "column_mapping": {
      "EAN Code": "ean",
      "Titre produit": "title",
      "Title (EN)": { "field": "title", "language": "en" },
      "Prix Achat": "supplier_cost_price",
      "Code Fournisseur": "supplier_code"
    },
    "import_options": { "overwrite_existing": true }
  }'

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "ready" }

POST/imports/{import_id}/reanalyze

Reanalyze a file

Re-runs file analysis with a different skip_header_rows, for a job whose headers were on the wrong row. Allowed only while the job is pending, awaiting_mapping, or failed.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Body parameters (JSON)

Name
skip_header_rows
Type
integer
Description
Number of rows to skip before the header row.

Request

POST

/imports/{import_id}/reanalyze

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/reanalyze \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"skip_header_rows": 2}'

Response

{ "columns": ["EAN", "Titre", "Prix HT"], "row_count": 1248, "sample_data": [] }

POST/imports/{import_id}/start-processing

Start processing

Triggers the actual import processing for a job in ready status. The job transitions to processing and rows are persisted to the catalog asynchronously.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Request

POST

/imports/{import_id}/start-processing

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/start-processing \
  -H "Authorization: Bearer {api_key}"

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing", "started_at": "2026-09-15T09:01:00Z" }

POST/imports/{import_id}/dry-run

Dry-run (preview)

Runs the import pipeline without persisting any data. Returns a preview of rows that would be created or updated, along with detected validation errors. Allowed while the job is pending, ready, or awaiting_mapping.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

A dry-run does not advance the job status. Call POST /imports/{import_id}/start-processing to actually run the import.

Request

POST

/imports/{import_id}/dry-run

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/dry-run \
  -H "Authorization: Bearer {api_key}"

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_rows": 1250,
  "products_to_create": 980,
  "products_to_update": 265,
  "rows_with_errors": 5,
  "validation_errors": [{ "row_number": 42, "field": "ean", "message": "EAN checksum invalide" }]
}

POST/imports/{import_id}/cancel

Cancel a job

Cancels an import job. Only jobs in an active status (pending, connecting, downloading, analyzing, processing, persisting) can be cancelled. Rows already committed before cancellation are not rolled back.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Request

POST

/imports/{import_id}/cancel

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer {api_key}"

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "cancelled" }

POST/imports/{import_id}/retry

Retry a job

Re-queues a job that ended in failed, cancelled, or completed_with_errors status.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Request

POST

/imports/{import_id}/retry

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/retry \
  -H "Authorization: Bearer {api_key}"

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending" }

POST/imports/{import_id}/archive

Archive / unarchive

Archive a completed job to hide it from the default list view, or unarchive it to restore visibility. Archived jobs are not deleted.

Endpoint	Effect
`POST /imports/{import_id}/archive`	Archive the job
`POST /imports/{import_id}/unarchive`	Restore to active list
`GET /imports/archive/stats`	Archive statistics (optionally scoped to `job_id`)
`POST /imports/archive/run`	Manually trigger the archival sweep (`archive_type`, `days`, `max_errors` query params); normally runs on a schedule

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Archive request

POST

/imports/{import_id}/archive

curl -X POST https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000/archive \
  -H "Authorization: Bearer {api_key}"

Response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "is_archived": true }

DELETE/imports/{import_id}

Delete a job

Permanently deletes an import job and its associated error records. This action is irreversible.

Path parameters

Name
import_id
Type
string
Description
The import job UUID.

Request

DELETE

/imports/{import_id}

curl -X DELETE https://api.pixeepim.com/api/v1/imports/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {api_key}"

Response

{ "deleted": true, "id": "550e8400-e29b-41d4-a716-446655440000" }

GET/imports/recent

Recent jobs, stats & CSV export

Convenience endpoints for dashboards:

Endpoint	Description
`GET /imports/recent`	Last N jobs (default: 10, query param `limit`)
`GET /imports/stats`	Aggregated statistics (total jobs, success rate, rows processed)
`GET /imports/export`	CSV export of the job list, filterable by `status_filter`, `supplier_code`, `start_date`, `end_date`

Recent jobs

GET

/imports/recent

curl "https://api.pixeepim.com/api/v1/imports/recent?limit=5" \
  -H "Authorization: Bearer {api_key}"

Stats

GET

/imports/stats

curl https://api.pixeepim.com/api/v1/imports/stats \
  -H "Authorization: Bearer {api_key}"

Stats response

{
  "total_jobs": 142,
  "completed_jobs": 138,
  "failed_jobs": 4,
  "total_rows_processed": 1842500,
  "total_products_created": 980000,
  "total_products_updated": 250000,
  "success_rate": 97.2
}

GET/imports/ean-pending

EANs pending resolution

Lists EAN codes encountered during imports that could not be matched to an existing product and are queued for the EAN Finder or manual resolution.

Query parameters

Name
page
Type
integer
Description
Page number (default: 1).
Name
per_page
Type
integer
Description
Items per page, max 500 (default: 50).
Name
supplier_code
Type
string
Description
Filter by supplier code(s), comma-separated for multiple.
Name
ean_type
Type
string
Description
Filter by classification: ean_to_resolve or ean_not_resolvable.
Name
search
Type
string
Description
Search by SKU, product name, or manufacturer reference.
Name
sort_by
Type
string
Description
first_seen_at, last_seen_at, import_count, or resolution_score.
Name
sort_order
Type
string
Description
asc or desc (default: desc).

Endpoint	Description
`GET /imports/ean-pending`	List unresolved EANs
`DELETE /imports/ean-pending/{resolution_id}`	Ignore a single entry
`POST /imports/ean-pending/bulk-delete`	Ignore multiple entries

Despite the name, these two operations are a soft delete: the entry's status moves to ignored in supplier_ean_resolutions, it is not physically removed. deleted_count in the bulk response can be lower than the number of IDs sent (invalid UUIDs or already-resolved items are skipped silently). Max 500 IDs per bulk request.

Request

GET

/imports/ean-pending

curl "https://api.pixeepim.com/api/v1/imports/ean-pending?ean_type=ean_to_resolve&per_page=20" \
  -H "Authorization: Bearer {api_key}"

Response

{
  "items": [
    {
      "id": "aabb1234-0000-0000-0000-000000000001",
      "sku": "SUP-A-9001",
      "name": "Widget Pro 3000",
      "supplier_code": "SUPPLIER_A",
      "status": "pending",
      "ean_type": "ean_to_resolve",
      "resolution_score": 40,
      "import_count": 3,
      "created_at": "2026-09-10T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "pages": 1,
  "stats": { "total": 1, "by_reason": {}, "by_supplier": { "SUPPLIER_A": 1 }, "by_ean_type": { "ean_to_resolve": 1 } }
}

Bulk ignore

POST

/imports/ean-pending/bulk-delete

curl -X POST https://api.pixeepim.com/api/v1/imports/ean-pending/bulk-delete \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '["aabb1234-0000-0000-0000-000000000001", "aabb1234-0000-0000-0000-000000000002"]'

Bulk ignore response

{ "status": "success", "deleted_count": 2, "message": "2 item(s) ignored" }

GET/mapping-templates

Mapping templates

A mapping template saves a supplier's column mapping (and optional custom columns, default values, computed columns, and auto-rules) for reuse on future uploads via template_id.

Endpoint	Description
`GET /mapping-templates`	List all templates (`skip`/`limit`)
`GET /mapping-templates/supplier/{supplier_id}`	Templates for one supplier
`POST /mapping-templates/supplier/{supplier_id}`	Create a template for that supplier
`POST /mapping-templates/supplier`	Create a template (supplier optional, generic)
`GET /mapping-templates/{template_id}`	Get one template
`PUT /mapping-templates/{template_id}`	Update a template
`DELETE /mapping-templates/{template_id}`	Delete a template
`PUT /mapping-templates/{template_id}/set-default`	Mark as the supplier's default template

Body parameters — create/update (JSON)

Name
name
Type
string
Description
Template name.
Name
description
Type
string
Description
Free-text description.
Name
supplier_id
Type
string
Description
UUID of the supplier this template belongs to.
Name
column_mapping
Type
object
Description
Same format as save column mapping: file column → field name, or {"field", "language"}.
Name
custom_columns
Type
object
Description
Additional column definitions not tied to a standard field.
Name
default_values
Type
object
Description
Values applied to every row when the source column is empty.
Name
computed_columns
Type
object
Description
Columns derived from other columns.
Name
auto_rules
Type
array
Description
Automatic transformation rules applied during import.
Name
is_default
Type
boolean
Description
Make this the supplier's default template (default: false).

List

GET

/mapping-templates

curl https://api.pixeepim.com/api/v1/mapping-templates \
  -H "Authorization: Bearer {api_key}"

Create for supplier

POST

/mapping-templates/supplier/{supplier_id}

curl -X POST https://api.pixeepim.com/api/v1/mapping-templates/supplier/b1e9c3d2-1111-4abc-8def-000000000001 \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier A — standard export",
    "column_mapping": { "EAN": "ean", "Titre": "title", "Prix Achat": "supplier_cost_price" },
    "is_default": true
  }'

Response

{
  "id": "0e0e0e0e-1111-2222-3333-444444444444",
  "name": "Supplier A — standard export",
  "supplier_id": "b1e9c3d2-1111-4abc-8def-000000000001",
  "column_mapping": { "EAN": "ean", "Titre": "title", "Prix Achat": "supplier_cost_price" },
  "is_default": true,
  "usage_count": 0,
  "created_at": "2026-09-15T09:00:00Z"
}

GET/mapping-templates/code2asin

Code2ASIN templates

A separate, smaller template family used by the Code2ASIN lookup pipeline to map a supplier's product-code column to the fields it needs to find the matching Amazon ASIN.

Endpoint	Description
`GET /mapping-templates/code2asin`	List Code2ASIN templates
`POST /mapping-templates/code2asin`	Create one
`POST /mapping-templates/code2asin/{template_id}/set-default`	Mark as default
`DELETE /mapping-templates/code2asin/{template_id}`	Delete

Body parameters — create (JSON)

Name
name
Type
string
Description
Template name.
Name
description
Type
string
Description
Free-text description.
Name
column_mapping
Type
object
Description
File column → field mapping.
Name
is_default
Type
boolean
Description
Make this the default (default: false).

Request

POST

/mapping-templates/code2asin

curl -X POST https://api.pixeepim.com/api/v1/mapping-templates/code2asin \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EAN → ASIN",
    "column_mapping": { "EAN": "ean" },
    "is_default": true
  }'

Response

{ "id": "1a1a1a1a-0000-0000-0000-000000000001", "name": "EAN → ASIN", "is_default": true }

POST/import-configs/configs

Automated import configs

Automated import configurations are managed under a separate router: /api/v1/import-configs/. Each config defines a source (FTP, SFTP, email, HTTP, Google Drive, MinIO…), file parsing options, and a field mapping. Recurring runs are driven by import schedules.

These endpoints use the prefix /api/v1/import-configs/, not /api/v1/imports/automations.

Endpoint	Description
`GET /import-configs/configs`	List configs (`supplier_code`, `import_type`, `is_active`, `page`, `per_page`)
`POST /import-configs/configs`	Create a config
`GET /import-configs/configs/{config_id}`	Get one config
`PUT /import-configs/configs/{config_id}`	Update a config
`DELETE /import-configs/configs/{config_id}`	Delete a config
`POST /import-configs/configs/{config_id}/toggle?enabled=true`	Enable/disable
`POST /import-configs/configs/{config_id}/test`	Test the connection without running an import
`POST /import-configs/configs/{config_id}/trigger`	Run this config immediately, outside its schedule

Body parameters — create (JSON)

Name
name
Type
string
Description
Configuration name.
Name
supplier_code
Type
string
Description
Supplier identifier code.
Name
import_type
Type
string
Description
One of manual, email, gmail, ftp, sftp, gdrive, google_drive, minio, http, http_file, api.
Name
connection_config
Type
object
Description
Credentials/connection details for import_type (IMAP/FTP/SFTP/…).
Name
description
Type
string
Description
Free-text description.
Name
is_active
Type
boolean
Description
Whether the config is active (default: true).
Name
file_pattern
Type
string
Description
File pattern to match, e.g. *.csv.
Name
file_format
Type
string
Description
CSV, Excel, or JSON.
Name
encoding
Type
string
Description
File encoding (default: UTF-8).
Name
delimiter
Type
string
Description
CSV delimiter (default: ;).
Name
skip_header_rows
Type
integer
Description
Rows to skip before the header (default: 0).
Name
sheet_name
Type
string
Description
Excel worksheet to read (empty = the first one).
Name
field_mapping
Type
object
Description
Column mapping configuration.
Name
mapping_template_id
Type
integer
Description
ID of a mapping template to reuse.
Name
notification_emails
Type
array
Description
Addresses notified on run completion.
Name
notify_on_success
Type
boolean
Description
Notify on success (default: false).
Name
notify_on_failure
Type
boolean
Description
Notify on failure (default: true).

List configs

GET

/import-configs/configs

curl https://api.pixeepim.com/api/v1/import-configs/configs \
  -H "Authorization: Bearer {api_key}"

Create config

POST

/import-configs/configs

curl -X POST https://api.pixeepim.com/api/v1/import-configs/configs \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Supplier A SFTP Import",
    "supplier_code": "SUPPLIER_A",
    "import_type": "sftp",
    "connection_config": {
      "host": "sftp.supplier.com",
      "username": "sftpuser",
      "key_file_path": "/keys/supplier_rsa",
      "directory_path": "/exports"
    },
    "file_pattern": "products_*.xlsx",
    "file_format": "Excel",
    "sheet_name": "Catalogue",
    "notify_on_failure": true
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440099",
  "name": "Daily Supplier A SFTP Import",
  "supplier_code": "SUPPLIER_A",
  "import_type": "sftp",
  "is_active": true,
  "next_scheduled_run": null,
  "created_at": "2026-09-15T09:00:00Z"
}

GET/import-configs/schedules

Import schedules

A schedule attaches a cron expression to an import config. A Celery Beat task checks every 5 minutes for schedules whose next_run_at has passed and triggers a job.

Endpoint	Description
`GET /import-configs/schedules`	List schedules (`config_id`, `is_active`, `page`, `per_page`)
`POST /import-configs/schedules`	Create a schedule
`GET /import-configs/schedules/{schedule_id}`	Get one schedule
`PUT /import-configs/schedules/{schedule_id}`	Update a schedule
`DELETE /import-configs/schedules/{schedule_id}`	Delete a schedule
`POST /import-configs/schedules/{schedule_id}/toggle?enabled=true`	Enable/disable
`POST /import-configs/schedules/{schedule_id}/execute`	Run this schedule immediately
`POST /import-configs/schedules/recalculate-next-runs`	Recompute `next_run_at` for every active schedule (e.g. after a timezone or DST change)

Body parameters — create (JSON)

Name
config_id
Type
string
Description
UUID of the associated import config.
Name
schedule_name
Type
string
Description
Descriptive name.
Name
cron_expression
Type
string
Description
Cron expression (e.g. 0 2 * * *).
Name
timezone
Type
string
Description
IANA timezone (default: Europe/Paris).
Name
is_active
Type
boolean
Description
Activate immediately (default: true).
Name
max_retries
Type
integer
Description
Retries on failure (default: 3).
Name
retry_delay_seconds
Type
integer
Description
Delay between retries, in seconds (default: 300).

Create schedule

POST

/import-configs/schedules

curl -X POST https://api.pixeepim.com/api/v1/import-configs/schedules \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "550e8400-e29b-41d4-a716-446655440099",
    "schedule_name": "Nightly run",
    "cron_expression": "0 2 * * *",
    "timezone": "Europe/Paris"
  }'

Response

{
  "id": "77770000-0000-0000-0000-000000000001",
  "config_id": "550e8400-e29b-41d4-a716-446655440099",
  "schedule_name": "Nightly run",
  "cron_expression": "0 2 * * *",
  "timezone": "Europe/Paris",
  "is_active": true,
  "next_run_at": "2026-09-16T02:00:00+02:00",
  "run_count": 0
}

GET/import-configs/dashboard/stats

Automation dashboard

Read-only summaries for an automation dashboard.

Endpoint	Description
`GET /import-configs/dashboard/stats`	Aggregate counts across all configs and schedules
`GET /import-configs/dashboard/upcoming-executions`	Next N scheduled runs (`limit`)
`GET /import-configs/dashboard/recent-executions`	Last N executions (`limit`)

Request

GET

/import-configs/dashboard/stats

curl https://api.pixeepim.com/api/v1/import-configs/dashboard/stats \
  -H "Authorization: Bearer {api_key}"

Imports

Job lifecycle

Body parameters (multipart/form-data)

Request

Response

Body parameters (JSON)

Request

Response

Body parameters (multipart/form-data)

Request

Response

FTP — POST /imports/import/ftp

SFTP — POST /imports/import/sftp

Email (IMAP) — POST /imports/import/email

FTP request

SFTP request

Response

Query parameters

Request

Response

Request

Response

Path parameters

Key response fields

Request

Response

Path parameters

Query parameters

Request

Response

Request

Invalid EANs

Path parameters

Body parameters (JSON)

Request

Response

Path parameters

Body parameters (JSON)

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Request

Response

Path parameters

Archive request

Response

Path parameters

Request

Response

Recent jobs

Stats

Stats response

Query parameters

Request

Response

Bulk ignore

Bulk ignore response

Body parameters — create/update (JSON)

List

Create for supplier

Response

Body parameters — create (JSON)

Request

Response

Body parameters — create (JSON)

List configs

Create config

Response

Body parameters — create (JSON)

Create schedule

Response

FTP — `POST /imports/import/ftp`

SFTP — `POST /imports/import/sftp`

Email (IMAP) — `POST /imports/import/email`