SAYLOR The result you are building
Finished Result:
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.
Stop Before Proceeding:
Stop publish when price/quantity/identity/condition is missing or contradictory, products violate channel policy, or feed updates can oversell inventory without reconciliation.
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
Start with the row that most closely matches the evidence. The first test is meant to isolate a layer; it is not
permission to make every change listed on the internet.
Evidence Likely layer First decisive check What the result means
Row rejected Schema Field-level channel error and Correct type/enum/required source or reject
source mapping item.
Accepted but Policy/quality Diagnostics and landing Resolve mismatch/prohibited/quality issue.
suppressed page/image
Duplicate item Identity SKU/channel ID/variant key Use stable unique ID and deliberate variant
grouping.
Oversold/wrong price Freshness/sour Compare feed Fix authoritative sync and update frequency;
ce timestamp/source/channel pause listing.
stateStep-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.
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.
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.
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.
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.
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.
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
Starting Problem:
A CSV upload accepts 500 rows but 80 products are not visible.
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.
Proof Of Completion:
Counts reconcile across states; sample listings show correct price/quantity/images; unresolved items remain rejects with reasons.
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 Verify authoritative code or leave absent per identity. channel; never invent.
Images work in browser only Hotlink/auth/user-agent/expiry Use stable authorized accessible host. restriction.
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
- https://support.google.com/merchants/answer/7052112
- https://developers.google.com/search/docs/specialty/ecommerce/share-your-product-data-with-google