Public imports API

Send a market-data bundle from your system, then read its validation report. The file-based import guide covers CSV and XLSX uploads.

Prepare access

Create a supplier API key in Settings → Developers. Submission requires api:write; status reads require api:read or api:write. Send the key as a bearer token or with X-API-Key. The plan must include api.access. Check your assigned entitlements rather than assuming access from a plan name.

Submit a dry run

Use Content-Type: application/x-ndjson. Each line is a contract record with an entity field. Supported tables include companies, brands, products, product_identifiers, offers, assortment_mappings and suppressions. An optional single manifest line carries the version and counts.

The public API reference defines the current schemas. Foreign references must resolve within the bundle or existing source namespace. The server forces the source namespace to your tenant.

This example uses a placeholder key and your own bundle file:

curl -X POST "https://api.test.stockisto.com/api/public/v1/imports?mode=dry-run" \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @your-bundle.ndjson

Replace sk_... and your-bundle.ndjson locally. Keep real keys and customer data out of repositories.

A successful submission answers 202 with importId, status, mode and statusUrl. Record statusUrl; validation continues asynchronously.

Read the result

GET /api/public/v1/imports/{importId}

Use the same tenant's key. An unknown batch, another tenant's batch or a dashboard upload answers 404.

A completed dry run has a report and writes no live rows. Check rejected rows in report, including broken_json, unsupported_country and dangling_fk. A row rejection can coexist with accepted rows; inspect the counts even when processing completes.

Submit for review

Correct the bundle, then submit it again with mode=apply. It stages a changeset for a Stockisto operator. pending-review lasts until the operator applies it; completed means that application finished.

If quotaExceeded is true, the changeset remains staged. Read quota, resolve the limit and have the staged changeset applied again. Dry runs and rejected changesets do not spend the import-row quota. Approved rows do. Each API call also uses the API-request quota.

After application, an import.completed webhook carries the import id and row counts for subscribers configured in Developers. Keep webhook signature verification enabled.

Recover from a refusal

Omitting mode selects dry-run. Importing does not publish the locator. Review publication separately on Publish.