HTML allowed; sanitized server-side.
", "category_path": "Electronics/Phones/Smartphones", "category_id": "merchant-internal-cat-42", "url": "https://demoshop.test/p/iphone-15-pro?utm=findit", "images": [ { "url": "https://cdn.demoshop.test/iphone-1.webp", "alt": "Front" } ], "price": 1199.0, "currency": "EUR", "original_price": 1299.0, "availability": "in_stock", "stock": 15, "condition": "new", "delivery": { "cost": 4.99, "days_min": 1, "days_max": 3 }, "identifiers": { "gtin": "0194253433538", "mpn": "MTV03ZD/A", "brand": "Apple", "model": "iPhone 15 Pro" }, "attributes": { "color": "Titanium", "storage_gb": 256 } } ``` | Field | Required | Notes | |---|---|---| | `external_id` | yes | Unique per merchant. Used to dedup across runs. 1–200 chars. | | `title` | yes | 5–250 chars. | | `description` | optional | HTML allowed; sanitized. Allowed tags: `p, br, ul, ol, li, strong, em, a[href]`. | | `category_path` | recommended | `/`-separated. Mapped to our taxonomy. | | `category_id` | optional | Your internal id; helps when path is inconsistent. | | `url` | yes | Click-out URL. Must be `https://`. May contain tracking params. | | `images` | recommended | First image is primary. Up to 20. | | `price` | yes | Number > 0. Float OK. | | `currency` | optional | Defaults to envelope currency. | | `original_price` | optional | If present, must be `> price` for sale display. | | `availability` | optional | `in_stock` / `limited` / `preorder` / `oos`. | | `stock` | optional | Integer ≥ 0. | | `condition` | optional | `new` / `used` / `refurbished`. See §3.1 for used/refurbished items. | | `delivery.*` | optional | Cost (in `currency`) and SLA in days. | | `identifiers.*` | optional but powerful | See §5. | | `attributes` | depends on vertical | See §4. | ### 3.1 Used & refurbished items (products) We compare offers on one canonical listing page per product. Condition belongs to **your offer**, not to the product, so keep it out of the `title`: - **Do** set `condition` to `used` or `refurbished`. - **Do** send the cosmetic grade in `attributes.grade` (e.g. `A+`, `A`, `AB`, `B`, `BC`, `C`) and optionally battery health in `attributes.battery` (e.g. `"100"`). - **Don't** put "Refurbished", "Kasutatud", "Grade A", "A+" etc. in the `title`. The title should name the product exactly as a new unit would: `"Apple iPhone 15 Pro 256GB Titanium"`. ```json { "title": "Apple iPhone 15 Pro 256GB Titanium", "condition": "refurbished", "attributes": { "color": "Titanium", "storage_gb": 256, "grade": "A", "battery": "98" } } ``` Your condition and grade are displayed next to your shop name on the listing page; the listing title, H1 and URL stay condition-free. **Server-side normalization:** if condition or grade markers do appear in a product title, we strip them during import and move them to the offer (a title marker like "Refurbished" also upgrades a missing/`new` condition to `refurbished`). Bare grade letters (`A`, `B`, `C`, …) are only interpreted as grades when the item is declared `used`/`refurbished` or the title carries an explicit condition marker. Don't rely on this: clean titles match better across merchants. --- ## 4. Vertical extensions The `attributes` blob carries vertical-specific fields. JSON Schemas live at `static/vertical-schemas/{vertical}.schema.json`. | Vertical | Required attributes | |---|---| | `products` | none beyond common | | `apartments` | `transaction` (sale/rent), `property_type`, `area_m2`, `address` | | `vehicles` | `vehicle_type`, `make`, `model`, `year` | | `pets` | `species`, `transaction` (sale/adoption/rehome/supply), `location` | | `trips` | `trip_type`, `from`, `to`, `depart_at`, `nights` | | `tickets` | `event_name`, `event_date`, `venue` | | `jobs` | `location`, `employment_type` | | `services` | `service_type`, `location` | The table lists what a feed **must** carry. Each vertical accepts many more optional attributes; the authoritative list is the JSON Schema itself, which you can fetch and validate against: `/vertical-schemas/vehicles.schema.json`, and the same for every vertical above. --- ## 5. Identifiers and matching We dedup the same real-world thing across merchants so users see one comparison page with N offers. Provide as many identifiers as you can: For `products`: 1. `gtin`: strongest. EAN-13 / UPC-A / GTIN-14. We canonicalize to GTIN-14 and validate the check digit. 2. `(brand, mpn)`: strong. 3. Title + brand: heuristic, used only as fallback. Ambiguous matches are flagged for human review. For other verticals: - `vehicles`: `vin` (17-char ISO 3779) - `apartments`: `cadastre_number` - `tickets`: `event_id` If you can't supply any, your listings still surface, but they won't merge with other merchants' offers and you'll appear as a standalone listing. --- ## 6. Validation rules The validator enforces every rule below; full details: `src/lib/feed/validate.ts`. **Envelope** - `version` = `"1.0"`. - `merchant.slug` matches the slug we have on file. - `vertical` is in the supported enum. - `currency` is ISO 4217. - `language` is ISO 639-1. - `country` is ISO 3166-1 alpha-2. **Item** - `price > 0`. - `original_price > price` for sale display (warning, not error, if equal). - `url` and `images[*].url` start with `https://` (configurable: `FEED_ALLOW_HTTP=true` for dev). - `external_id` 1–200 chars; `title` 5–250 chars. - `description` ≤ 50 KB after sanitize. - `gtin` is 8/12/13/14 digits with valid GS1 check digit. Invalid GTINs are warnings: we ignore the GTIN for matching and fall back to other matching signals. - `attributes` validated against the vertical's JSON Schema. **Caps** - Compressed file ≤ 200 MB. - Uncompressed ≤ 1 GB. - Items per feed ≤ 500,000. Beyond → require pagination. **HTTP** - Connect timeout 30s, total 5min per page. - We honor `If-Modified-Since` and `ETag`. - `304 Not Modified` → no parsing, no item changes; just a `last_pulled_at` bump. - We accept `Content-Encoding: gzip, br, deflate`. --- ## 7. Authentication Pick one when registering your feed. Stored encrypted at rest (AES-256-GCM). | Mode | What we send | |---|---| | `none` | Nothing. Use an unguessable URL slug. | | `basic` | `Authorization: Basic