Skip to main content

Partner data import

The console's bulk importer has a one-shot API twin for partners: validate and apply in a single call, scoped to a key that can do nothing else. Attribute validation rules, SKU generation and normalisation behave exactly as they do for a staff upload.

Before you begin​

  • A staff member creates an API key under Settings → API keys with the single scope import.ingest and hands you the tgk_… secret. See Authentication.
  • Agree the target (for example products, or a custom object type) and, for updates, the match field.

Discover the target's shape​

curl https://api.example.com/admin/imports/targets \
  -H "Authorization: Bearer tgk_…"

curl "https://api.example.com/admin/imports/template?target=products" \
  -H "Authorization: Bearer tgk_…"          # a CSV with exactly the expected headers

For products the columns are sku, name, slug, type, status, unit, cost_price, description, attributes, images, categories, config.

Ingest​

curl -X POST "https://api.example.com/admin/imports/ingest?target=products&format=csv&normalize=trim,collapse" \
  -H "Authorization: Bearer tgk_…" \
  -F file=@products.csv

or send JSON rows directly:

curl -X POST "https://api.example.com/admin/imports/ingest?target=products&format=json&match=sku" \
  -H "Authorization: Bearer tgk_…" -H "Content-Type: application/json" \
  -d '[{"sku":"M12-HEX-40","name":"M12 x 40 hex bolt","unit":"each","attributes":{"material":"A4-80"}}]'
Query parameterMeaning
targetRequired. The record type.
formatcsv, json or xlsx.
matchField to upsert on — rows matching an existing record update it; without it everything is created.
normalizeComma-separated cleansing applied to string values: trim, lower, upper, collapse.

The result​

{
  "run": { "id": 118, "target": "products", "status": "committed", "…": "…" },
  "applied": 240, "created": 12, "updated": 228, "errors": 3,
  "results": [
    { "row_number": 17, "status": "error", "message": "attribute material: value not in allowed set" },
    { "row_number": 18, "status": "update", "message": "" }
  ]
}

Valid rows are applied; error rows are skipped and reported individually with the same messages the console shows, so fix exactly those rows and send them again (with match set so they update rather than duplicate). Every ingest appears in the console's Recent imports with its counts.

Vendors​

Marketplace vendors have the same engine confined to their own catalog: POST /vendor/products/import with a vendor session token (and GET /vendor/products/import/template). New SKUs become listings awaiting the operator's approval; existing SKUs are updated in place.