Primary navigation
API Dashboard

Best practices

Operational guidance for high-quality integrations.

Content quality

Write factual descriptions

  • Use concise, factual copy that helps users understand products.
  • Plain text and bullet-style text are both acceptable.

Use optional fields intentionally

  • Optional attributes like material can improve answer quality but are not required for ingestion.
  • If an optional field requires brittle transforms, omit it until data quality is stable.

Keep URL values valid and encoded

  • Ensure url and seller_url values are RFC 1738-compliant.
  • Encode spaces and unsafe characters (for example, use %20 for spaces).

Seller and policy

Keep attribution and policy links consistent

  • Set seller_name to the seller users should see in listing context.
  • seller_url can match your primary product or merchant URL if no separate seller page exists.
  • Use a durable, public URL in return_policy.

Set eligibility flags intentionally

  • For initial rollout phases, a common baseline is is_eligible_search=true and is_eligible_checkout=false until checkout readiness is confirmed.

Keep shipping values spec-compliant

  • Format shipping exactly as defined in the Product Feed Spec.
  • Start with one nationally valid shipping value at launch, then expand to regional/service granularity later.

Variants

Model variants at row level

  • Use a unique item_id for each variant row.
  • Reuse one group_id across related variants.
  • Set listing_has_variations=true for variant listings and listing_has_variations=false for non-variant listings.
  • Provide variant_dict values that reflect user-facing option dimensions (up to three dimensions).
  • Include key variant attributes as explicit columns in addition to variant_dict whenever possible.
  • Keep url, title, description, and image_url variant-specific for each variant row.

Delivery and onboarding

Operate as a snapshot pipeline

  • Publish full snapshots on a predictable cadence (at least daily).
  • Intraday price and availability changes are not currently supported; include those updates in your next scheduled snapshot.

Use push-based delivery and stable filenames

  • Push feeds through supported channels.
  • Reuse the same file path/name each publish and overwrite in place.
  • If multiple brand feeds share one location, use clear brand-prefixed names.

Validate in phases

  • Start with a small sample (around 100 items).
  • Include all required fields in every sample row.
  • Run QA on the first full snapshot.
  • Move to steady-state automation once validation is clean.