Feed Troubleshooting

Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.

Most feed problems come from incomplete snapshots, unstable IDs, inconsistent field types, or a mapping that no longer matches the source file.

Common mistakes

Sending only changed records instead of the full current snapshot.
Changing source IDs between exports.
Using a product type other than the exact canonical value product.
Sending one field as different data types in different records.
Putting catalog values in XML attributes. Attributes are ignored; use elements.

My changes are not appearing

Confirm the feed URL is reachable using the access method agreed during onboarding.
Confirm the source file contains the changed records.
Return an accurate ETag or Last-Modified header and update its value whenever the content changes.
Serve the feed with gzip compression. Conditional-update metadata and gzip are strongly recommended for timely, near-real-time synchronization.

See Serving your feed for polling and conditional request behavior.

Far fewer products are indexed

Confirm the feed configuration and mapping still match the source:

XML must use the configured repeating record element.
JSON must contain records at the configured array path.
CSV must use the configured delimiter and header row.
Each record must map to non-empty @id, @type, and @title fields.

IDs are rejected or analytics do not match

Product IDs must be type-prefixed, such as product/123.

Keep the source ID immutable.
Use the exact product type.
Ensure the source ID prefix matches the object type. The mapping does not repair a missing or mismatched prefix.
Ensure analytics events resolve to the same canonical product ID.
Do not rely on a URL as the identity unless that mapping was explicitly configured.

A large update is rejected

Check that the export completed successfully.
Check the record element, array path, and CSV delimiter.

Category references do not resolve

Canonical product category references must use typed IDs:

{
  "@category": ["category/cat-shoes"]
}

The referenced category is allowed to arrive later, so a temporarily dangling reference is not itself an ingest error. Check that:

the reference uses the category/ type prefix;
the source mapping produces the expected category ID;
existing path-based feeds use the configured delimiter and mapping.

Text is broken or garbled

Export feeds as UTF-8.
In XML, entity-encode special characters or wrap text in CDATA.
Do not entity-encode text inside CDATA.