Submitting Proposals

When your model has produced enrichments, submit them as a batch of proposals. Each proposal becomes a pending revision on the matched product — it never edits live data. A merchant reviewer then accepts or rejects it. The key lever you control here is confidence: a 0–100 score per item that tells reviewers how sure you are. High-confidence proposals can be triaged and accepted fast; low-confidence ones get a closer look. Sending honest confidence is the single biggest thing you can do to raise your acceptance rate.

Endpoint

POST /api/enrichment/products/submissions
Content-Type: application/json

Requires the catalog:submit scope. A submission carries an optional externalSubmissionId (your own idempotency/correlation handle) and a list of items.

{
  "externalSubmissionId": "batch-2026-06-22-001",
  "items": [
    {
      "sku": "ABC-123",
      "confidence": 92,
      "name": "Acme 18V Cordless Impact Driver",
      "description": "A compact 18V brushless impact driver delivering 180 Nm of torque...",
      "attributes": [
        {
          "attribute": "Voltage",
          "detail": "18",
          "option": { "optionId": 880, "unit": "V", "priority": 1, "dataType": "NUMBER", "showOnWebsite": true }
        },
        {
          "attribute": "Torque",
          "detail": "180",
          "option": { "optionId": 884, "unit": "Nm", "priority": 2, "dataType": "NUMBER", "showOnWebsite": true }
        }
      ]
    },
    {
      "sku": "XYZ-900",
      "confidence": 47,
      "description": "Provisional description — low signal from source data."
    }
  ]
}

curl https://api.verzla.com/api/enrichment/products/submissions \
  -H "X-Api-Client-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d @submission.json

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

Proposed product name. Enrichable.

string

Proposed URL slug. Enrichable.

string

Proposed long-form description. Enrichable.

array

Proposed structured attributes. Align each to a template option via option.optionId — see Attribute templates. Each attribute is { "attribute": string, "detail": string, "option": { ... } | null }.

array

Proposed document references (array of strings). Enrichable.

Only the enrichable fields above are honored. Include at least one non-empty enrichable field per item — an item with nothing to propose is rejected as REJECTED_FIELDS.

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.

Calibrate honestly. Inflating confidence gets low-quality proposals accepted once, then erodes reviewer trust and your acceptance rate. Well-calibrated confidence is what lets a merchant clear a big batch fast — which is exactly what makes your integration valuable.

Response

You get one result per submitted item, in order. The sku echoes your identity so you can correlate even when an item is unmatched.

[
  {
    "sku": "ABC-123",
    "productId": 90210,
    "revisionId": 55123,
    "status": "CREATED",
    "ignoredFields": []
  },
  {
    "sku": "XYZ-900",
    "productId": 90455,
    "revisionId": 55124,
    "status": "CREATED",
    "ignoredFields": ["gtin"]
  }
]

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[]

Fields you sent that were dropped because they aren’t enrichable or were empty. A useful signal that your payload includes data the API won’t act on.

Limits & errors

Condition	Response
More than 1000 items	`400 Bad Request` — “Submission exceeds the maximum of 1000 items”
Empty or missing `items`	`400 Bad Request` — “Submission must contain at least one item”
Missing `catalog:submit` scope	`403 Forbidden`

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.

Getting Started

Authentication

The Enrichment Workflow

Endpoint

Submission item fields

Confidence: help reviewers triage

Response

Result status

Limits & errors

​Endpoint

​Submission item fields

​Confidence: help reviewers triage

​Response

​Result status

​Limits & errors

Endpoint

Submission item fields

Confidence: help reviewers triage

Response

Result status

Limits & errors