Endpoint
catalog:submit scope. A submission carries an optional externalSubmissionId (your
own idempotency/correlation handle) and a list of items.
Submission item fields
string
required
Identity key used to match the proposal back to a product. Must resolve to exactly one product in
your organization, or the item comes back
UNMATCHED.integer
Your certainty, 0–100. Optional but strongly recommended — it drives reviewer triage. Omit it
(or send
null) only when you genuinely have no signal.string
A free-text note to the reviewer — your reasoning, sources, or caveats. Shown alongside the proposal
in the review screen. Leading/trailing whitespace is trimmed, blank values are dropped, and anything
over 5000 characters is truncated. Optional; not an enrichable field.
string
The brand name you believe the product belongs to. Shown to the reviewer as a suggestion only —
approving the revision never changes the product’s brand. Trimmed, blanks dropped, truncated at
255 characters. Optional; not an enrichable field.
string
Proposed product name. Enrichable.
string
Proposed URL slug. Enrichable.
string
Proposed long-form description. HTML or Markdown — Markdown (headings, lists, tables, bold, links)
is converted to HTML before review, so the reviewer sees and approves exactly what will be stored.
Enrichable.
string[]
Proposed Global Trade Item Numbers (EAN/UPC), as strings. Send several when the product has one per
packaging level — single unit first, then e.g. the box of 100 — in that order. A lone string is
accepted as a one-element list, and the plural key
gtins works too. Values are trimmed, blanks
dropped, and duplicates removed (keeping your order). On approval the list replaces all of the
product’s GTINs. Enrichable.string[]
Proposed Manufacturer Part Numbers. Same rules as
gtin: a lone string or the plural key mpns is
accepted, values are trimmed and de-duplicated, and on approval the list replaces all of the
product’s MPNs. Enrichable.array
Proposed structured attributes. Align each to a template option via
templateOption.optionId — see
Attribute templates. Each attribute is
{ "attribute": string, "detail": string, "templateOption": { ... } | null }. The reviewer decides
on each attribute separately, and approved attributes are merged into the product’s existing
ones by attribute name. Attributes you don’t send are left alone, so propose only the ones you
want to add or change. Enrichable.array
Proposed document references (array of strings). Enrichable.
object
Proposed ETIM classification for the product, as a
free-form JSON object. Verzla doesn’t validate its shape — it is stored exactly as you send it. The
reviewer approves or rejects it like any other field; on approval it replaces the product’s
existing ETIM data wholesale (no merging). An empty object is treated as not sent. Enrichable.
Include at least one non-empty enrichable field (
name, slug, description, gtin, mpn,
attributes, files, etimClass) per item — an item with nothing to propose is rejected as REJECTED_FIELDS.
confidence, comment, and brand are metadata for the reviewer and don’t count on their own.Confidence: help reviewers triage
Confidence isn’t just a number we store — it’s how the merchant decides what to review first.- 80–100 — high confidence. Strong source signal, schema-aligned values. Reviewers can batch these and accept quickly.
- 50–79 — moderate. Worth a glance; usually a spot-check.
- 0–49 — low. Flag for careful review; you’re proposing despite weak signal.
How your proposal is reviewed
A proposal isn’t approved or rejected as a single unit. Knowing how reviewers work through it helps you shape what you send.Every field — and every attribute — is its own decision
Each proposed field (name, description, gtin, etimClass, …) gets its own approve/reject
decision. attributes goes further: each attribute is decided on its own, so a reviewer can
accept your voltage and reject your torque in the same proposal. When a reviewer has approved some
fields but not decided the rest yet, the revision is PARTIALLY_APPLIED. Once every field is
decided, it becomes APPROVED if anything was applied, or REJECTED if nothing was.
Reviewers can correct your proposal
Before approving, a reviewer can rewrite the proposeddescription, or rename or change the value
of individual attributes. Verzla keeps your original proposal next to the correction. Each
corrected field group — the description, or the attributes as a whole — lowers the revision’s
displayed confidence by 10 points (floored at 0). This signals that the proposal needed human
help.
Corrections don’t affect your acceptance rate confidence bands:
those always use the confidence you sent. A corrected-then-approved proposal still counts as
accepted.
One open proposal per product wins
Open revisions for the same product (PENDING or PARTIALLY_APPLIED) are grouped. Reviewers
see the newest one first, with the others listed beside it. As soon as a reviewer approves any field
of one revision, Verzla automatically rejects the rest of the group and marks them as superseded
by the approved one. Superseded revisions count as rejected in your acceptance rate.
Response
You get one result per submitted item, in order. Thesku echoes your identity so you can correlate
even when an item is unmatched.
Result status
status
A pending revision was created (
revisionId) on product productId. It’s now in the merchant’s
review queue.status
No product matched the supplied identity — or the match was ambiguous. Nothing was created. Check
the SKU.
status
The item carried no whitelisted, non-empty enrichable fields, so there was nothing to propose.
string[]
Reserved for reporting fields that were dropped. Currently always empty.
Limits & errors
Batch large runs into submissions of up to 1000 items each. Use a distinct
externalSubmissionId
per batch so you can reconcile results against what you sent.