Skip to main content
POST
Stage rows onto a catalog import job

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
job_id
string<shortuuid>
required

job_id returned when the job was opened.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

Body

application/json

A batch of normalised rows to stage onto an open job.

​
rows
CatalogRowIn · object[]
required

Rows to stage, at most 1,000 per call. Appends are additive and ordered; a job holds at most 400,000 rows in total. Re-sending a call duplicates its rows in the staged file but not in the result — the engine reports a repeated barcode as duplicate_gtins_in_feed and writes one listing.

Required array length: 1 - 1000 elements

Response

OK

A job's current state. The same shape from open, append, start and poll.

​
job_id
string<shortuuid>
required

Identifier of the job. Use it on the row, start and poll calls.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
status
string
required

staging — accepting rows; the run has not started. queued — start accepted, waiting for a worker. running — the merge is executing; chunks_done and result advance as it goes. completed — finished; result carries the whole feed's census. failed — the run gave up; error says why, result carries the census of the work that did finish, and POST .../start resumes from where it stopped.

​
source
string
required

Catalog source this run merges under.

​
dry_run
boolean
required

Whether this run rolls back each batch.

​
reclaim_unattributed
boolean
required

Whether this run may claim unattributed fields.

​
staged_rows
integer
required

Rows accepted into the job so far.

Required range: x >= 0
​
chunk_rows
integer
required

Staged rows merged by one chunk task. The run is a sequential chain of these, so no single task approaches the worker's time limit. Set at open time from dry_run unless you named one: 10,000 for a dry run, 2,000 for a commit, because a commit does an order of magnitude more work per row.

Required range: x >= 1
​
chunks_total
integer
required

Chunks this job's staged rows divide into. Zero until rows are staged.

Required range: x >= 0
​
chunks_done
integer
required

Chunks fully merged and recorded. A resumed run continues from here, so these rows are never merged twice.

Required range: x >= 0
​
processed_rows
integer
required

Staged rows already merged. A floor, not an estimate: rows counted here are recorded and survive a restart. It advances within a chunk as well as between chunks — a chunk checkpoints every batch_size rows — so it keeps moving during the minutes a commit chunk takes, and is the field to watch to tell a slow run from a stopped one.

Required range: x >= 0
​
poll_url
string
required

Path to poll for this job's status and result.

​
source_file
string
default:""

Feed drop name recorded as listing provenance.

​
started_at
string<date-time> | null

When the run began. Null before it starts.

​
completed_at
string<date-time> | null

When the run reached a terminal state.

​
error
string | null

Why the run failed. Null unless status is failed.

​
result
Result · object

The engine's census. Empty until the first chunk finishes, then the running total for the chunks merged so far, and the whole feed's figures once status is completed — so read status, not this field, to decide whether a run is done. Carries rows_read, products_created / products_enriched / products_unchanged, listings_created / listings_updated, dual_listed (products another retailer's feed had already created — the cross-retailer overlap), duplicate_gtins_in_feed, quarantined with quarantine_reasons, brand and ingredient counts, field_decisions (per field, how each value was decided), reclaimable_fields, and quarantine — the refused rows themselves, capped at 500 entries with quarantined remaining the true total. errors is capped the same way, with errors_total as its true count. census is the same figures as human-readable lines.