SAYLOR Normalize product titles, identifiers, categories, prices, quantities, image URLs, descriptions, and marketplace-specific requirements without inventing inventory facts.
The result you're building
A marketplace-ready product feed whose IDs, titles, categories, condition, price, quantity, images, descriptions, and policy fields come from authoritative inventory, validate per channel, reconcile counts/totals, and produce explicit rejects instead of invented facts.
Use this guide when
- Preparing CSV/API feeds for Google, eBay, Meta, Mercari, or another marketplace.
- Normalizing several inventory exports into one channel contract.
Do not use it as a substitute for
- Do not invent GTIN/brand/condition/quantity/price or copy identifiers from similar products.
- Do not publish items whose image/license, ownership, condition, or prohibited-item status is unresolved.
Before you change anything
- Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
- Immutable inventory exports and authoritative source fields.
- Marketplace feed specification/version/account/locale/currency.
- Category/attribute mapping and prohibited/restricted-item policy.
- Image URLs/rights, fulfillment, returns, tax/shipping, and update cadence.
Understand the system before fixing it
A feed is a contract, not a spreadsheet
Column names, types, enums, identifiers, update semantics and account settings define acceptance.
Identifiers must be truthful
SKU is seller identity; GTIN/MPN/brand describe product identity. Missing is not permission to fabricate.
Channel acceptance is not listing quality
A syntactically accepted item can be suppressed for image, policy, mismatch, or landing-page inconsistency.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Row rejected | Schema | Field-level channel error and source mapping | Correct type/enum/required source or reject item. |
| Accepted but suppressed | Policy/quality | Diagnostics and landing page/image | Resolve mismatch/prohibited/quality issue. |
| Duplicate item | Identity | SKU/channel ID/variant key | Use stable unique ID and deliberate variant grouping. |
| Oversold/wrong price | Freshness/source | Compare feed timestamp/source/channel state | Fix authoritative sync and update frequency; pause listing. |
Step-by-step procedure
Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.
Step 01 — Pin channel contract and source truth
Why: Marketplace fields and policies change.
Do: Record channel/feed version/account/locale/currency; map each target field to authoritative inventory source and null/reject rule.
Read the result: No field comes from guess or display formatting.
Next: Separate channel transforms from master data.
Step 02 — Normalize identifiers and variants
Why: Numeric coercion and unstable IDs break updates.
Do: Keep SKU/GTIN/MPN as strings, preserve leading zeros, validate check digits/format only when applicable, define parent/variant keys and uniqueness.
Read the result: Duplicate/conflicting identity rejects.
Next: Never generate real-world product codes.
Step 03 — Clean listing content
Why: Titles/descriptions must be useful and policy-safe.
Do: Build concise factual title from brand/product/model/key attributes, normalize condition/category/attributes, remove markup/claims prohibited by channel, preserve original source.
Read the result: No keyword stuffing or unsupported superlatives.
Next: Flag human-review condition uncertainty.
Step 04 — Validate commercial fields
Why: Price/quantity/shipping errors cause direct harm.
Do: Parse decimal/currency, quantity integer, availability, fulfillment/returns/tax/shipping required fields and cross-field rules.
Read the result: Blank/negative/stale/contradictory values reject or pause.
Next: Use one observed-at timestamp.
Step 05 — Validate images and URLs
Why: Broken/unauthorized images suppress listings.
Do: Check HTTPS/status/content type/size/rights/no placeholders and landing URL consistency; avoid expiring/private URLs.
Read the result: Every image belongs to exact item/variant.
Next: Record hash/source.
Step 06 — Reconcile submission and diagnostics
Why: File creation is not marketplace success.
Do: Balance source/accepted/rejected counts, submit test/small batch, collect per-item diagnostics, verify visible listings/price/quantity, then scale and monitor drift.
Read the result: No source row disappears; suppressed is distinct from active.
Next: Keep rollback feed/channel IDs.
Worked example
Evidence collected
- Upload job status says success with item-level warnings.
- 60 lack required category attributes; 20 image URLs return 403 to marketplace crawler.
- Feed process counted accepted transport rows as active listings.
- Inventory reserves were not reduced, but dashboard was misleading.
Decision: Transport acceptance is not active listing state; diagnostics and external image access are missing gates.
Actions taken
- Added accepted/active/suppressed/rejected states and item diagnostics.
- Mapped authoritative attributes or rejected unresolved items.
- Moved images to stable authorized public URLs and verified crawler access.
Why this example matters: The useful result is publishable active inventory plus an honest reject queue.
Verify, recover, and hand off
Completion tests
- A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
- Every field maps to authoritative source/version.
- IDs/variants are stable, unique, and preserve formatting.
- Price/quantity/condition/category/images validate.
- Source disposition reconciles to active/suppressed/rejected.
- Visible sample listings match feed and landing page.
- Updates/rollback prevent oversell and stale facts.
Rollback or safe recovery
- Pause/expire affected channel items or restore prior accepted feed version.
- Keep master inventory untouched; revert only channel transform.
- Correct counts before republishing to avoid duplicate IDs.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Spreadsheet strips zeros | Identifier coerced numeric. | Import/store as text and validate raw CSV. |
| GTIN rejected | Wrong format/check digit/product identity. | Verify authoritative code or leave absent per channel; never invent. |
| Images work in browser only | Hotlink/auth/user-agent/expiry restriction. | Use stable authorized accessible host. |
| Quantity drifts | Multiple sources/update lag. | Define inventory authority, observed time and atomic/reservation policy. |
Reusable handoff record
- Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
- Channel spec/account/locale/version.
- Master-to-channel field/category mapping.
- Clean feed and reject file with lineage.
- Submission/item diagnostic and visible-sample results.
- State reconciliation, update and rollback policy.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| context | object | Versioned environment, target, and requested outcome. |
| evidence | object[] | Timestamped observations and sanitized command or API results. |
| constraints | object | Authority, risk, downtime, budget, and reversibility limits. |
| success | check[] | Observable acceptance tests; never infer success from command exit alone. |
Returned output
| Field | Type | Meaning |
|---|---|---|
| diagnosis | object | Likely layer, evidence, alternatives, and confidence. |
| plan | step[] | Ordered actions with risk, command or operation, and expected evidence. |
| verification | check[] | Pass/fail checks that prove the requested outcome. |
| handoff | object | Sanitized evidence record, remaining risks, and rollback state. |
Agent refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.
Official reference starting points