{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "iGraal Cashback Coupons API", "description": "European Cashback and Coupon API for iGraal France, Spain and Poland plus Shoop Germany. Search merchants, codes, cashback rates, featured offers, sponsored placements, in-store rewards, printable coupons, gift cards, affiliate networks and keyword insights across four markets. european cashback coupon promo code merchant data api", "x-category": "Reward", "x-long-description": "# 💶 iGraal & Shoop Cashback API\n\nAccess merchant, coupon, cashback and rewards data from iGraal in France, Spain and Poland and Shoop in Germany. Build deal discovery, cashback comparison, promotion monitoring and merchant research workflows across four European storefronts.\n\n| Feature | Details |\n| --- | --- |\n| **Last Updated** | **September 22, 2026** |\n| 🇪🇺 Market Coverage | France, Germany, Spain and Poland; Germany operates as Shoop |\n| 🏬 Merchant Directory | Search, category and website lookup, merchant profiles, logos and affiliate attribution |\n| 🎟️ Coupons & Deals | Market-wide and per-merchant feeds, active/expired status, code lookup and editorial top picks |\n| 💸 Cashback Terms | Current rates, previous rates, campaign tiers and conditions |\n| ⭐ Featured Promotions | Editorial offers, sponsored merchants and placement-specific promotional spots |\n| 🛒 In-Store Rewards | Participating retailers, grocery offers, categories and spotlight banners where available |\n| 🖨️ Printable Coupons | France-only grocery coupon offers and brand/category references |\n| 🎁 Gift Cards | Discounted card offers, denominations and redemption terms |\n| ⚡ API Type | Fast REST API via RapidAPI |\n\n## Overview\n\nThe iGraal & Shoop Cashback API serves four market-scoped storefronts through one set of endpoints. Discover a merchant by name or website, inspect its cashback and coupon offers, browse featured promotions, and explore in-store rewards, printable coupons and gift cards where those programmes operate. Market codes are `fr`, `de`, `es` and `pl`.\n\nThis API is for deal and coupon apps, loyalty products, affiliate publishers, offer monitoring, merchant research and internal data pipelines. The market directory is static; use `/merchants?market=fr&limit=1` and read `total` when you need a current merchant count for a market.\n\n## Key Features\n\n- Find merchants by text, website URL, category, quality, cashback or publication status.\n- Read merchant profiles and move between merchant, coupon and campaign IDs.\n- Browse coupon feeds or recheck individual codes by ID.\n- Compare live cashback rates, tiers and campaign conditions.\n- Inspect the platform's featured shortlist and placement-specific sponsored spots.\n- Browse in-store rewards, printable coupons and gift cards where supported.\n- Use a resumable merchant-catalogue cursor for bulk exports, up to 200 rows per request.\n- Read keyword, affiliate-campaign and scheduled cashback-event datasets on plans that include advanced intelligence.\n\n## Available Data\n\nMerchant names, websites, logos, categories and affiliate networks; coupons, codes, validity windows and tracking links; cashback rates, prior rates, tiers and conditions; editorial featured offers and sponsored placements; in-store and printable offers; discounted gift cards; merchant search keywords; campaign attribution and cashback event schedules. Some programmes are market-specific. An empty keyword or event list can mean either no coverage or an unknown merchant ID; use `/merchant-details` when that distinction matters.\n\n## Merchants\n\n### `/merchants`\n\nSearch and filter merchants in one market. Use `limit=1` and the `total` field for a live count; add `published=true` for storefront-visible merchants.\n\n### `/merchants-catalog`\n\nWalk the full merchant catalogue for bulk export. Each request returns at most 200 rows; follow `next_token` until `has_more` is false. Available on Mega, or within Basic's small trial quota.\n\n### `/merchant-details`\n\nRead one merchant profile by ID, including its offer context and affiliate attribution. Use it separately when another endpoint returns a dataset without an embedded merchant card.\n\n### `/merchant-autocomplete`\n\nTurn a partial merchant name into merchant IDs for search boxes and selection flows.\n\n### `/merchant-by-url`\n\nResolve a shop website or iGraal landing-page URL to matching merchants without extracting an ID yourself.\n\n## Cashback\n\n### `/cashback-rate`\n\nGet a merchant's live cashback rate and its campaign terms.\n\n### `/cashback-campaign`\n\nInspect the tiers and conditions of one cashback campaign by campaign ID.\n\n### `/affiliate-campaigns`\n\nRead affiliate-network attribution for campaign legacy IDs, including programme identity and tracking details. Mega includes this advanced dataset.\n\n### `/cashback-events`\n\nRead a merchant's scheduled campaign activations, stops and rate changes. This is a schedule, not an embedded merchant profile; an empty result is normal. Mega includes this advanced dataset.\n\n## Coupons\n\n### `/coupons`\n\nBrowse the market-wide coupon and deal feed with merchant, status and publication filters.\n\n### `/coupon-count`\n\nGet the match count for coupon filters without fetching a full coupon page.\n\n### `/merchant-coupons`\n\nRead one merchant's coupon archive, including active and expired offers. Fetch its profile from `/merchant-details` if needed.\n\n### `/top-coupons`\n\nGet editorially selected top coupons for up to 50 merchant IDs in one request. A missing coupon does not establish whether an ID is unknown or simply has no selected offer.\n\n### `/coupon-lookup`\n\nRecheck one coupon, or a batch of coupons, by ID to see its current record.\n\n### `/featured-offers`\n\nPage through the storefront's featured merchants and vouchers. The former `type` query filter is not offered; it required a slow whole-feed scan.\n\n## In-Store\n\n### `/instore-offers`\n\nBrowse eligible in-store cashback offers where the programme is available.\n\n### `/instore-retailers`\n\nList participating in-store retail chains.\n\n### `/instore-reference`\n\nGet in-store categories, brands and retailer reference data for discovery and filtering.\n\n### `/instore-spotlights`\n\nRead the in-store programme's current spotlight placements.\n\n## Printable Coupons\n\n### `/printable-offers`\n\nBrowse printable grocery coupon offers in France, with brand and category filters.\n\n### `/printable-reference`\n\nGet the printable-coupon brand and category vocabularies.\n\n## Gift Cards\n\n### `/gift-cards`\n\nBrowse discounted gift cards or look up the card available for a merchant, including discount and redemption details.\n\n## Intelligence\n\n### `/merchant-keywords`\n\nRead per-merchant search keywords, search position and monthly search volume. Mega includes this advanced dataset; an empty list may also mean an unknown merchant ID.\n\n### `/promotions`\n\nInspect editorial and sponsored spots in one required `placement` slot per request. The response shows where a promotion is featured, not just which offer exists.\n\n### `/affiliate-networks`\n\nResolve affiliate-network IDs to names for interpreting merchant and campaign data.\n\n## Reference\n\n### `/markets`\n\nGet the static four-market directory and programme-availability flags. It does not include live merchant totals.\n\n### `/categories`\n\nGet the merchant category tree and IDs used by category filters.\n\n### `/reference`\n\nGet accepted filter vocabularies and response-value definitions.\n\n## Health\n\nThe `/status` health check is available on every plan and is not attached to a pricing Feature.\n\n## Plan Access\n\nRapidAPI shows an enabled Feature with a green tick and a disabled Feature with a red cross. The exact eight Features to create and attach are below. `/status` is deliberately unattached and available on every plan. Attach every other endpoint to **exactly one** Feature; a plan's enabled Features determine its endpoint access. Configure these switches in RapidAPI—the table in this document describes them but does not enforce them.\n\n| RapidAPI Feature | Attached endpoints | Basic | Pro | Ultra | Mega |\n| --- | --- | :---: | :---: | :---: | :---: |\n| 🔎 Merchant Discovery Data | `/merchants`, `/merchant-details`, `/merchant-autocomplete`, `/merchant-by-url` | ✓ | ✓ | ✓ | ✓ |\n| 🎟️ Coupon Lookup Data | `/coupons`, `/coupon-count`, `/merchant-coupons`, `/coupon-lookup` | ✓ | ✓ | ✓ | ✓ |\n| 💸 Cashback Campaign Data | `/cashback-rate`, `/cashback-campaign` | ✓ | ✓ | ✓ | ✓ |\n| 🧭 Market Reference Data | `/markets`, `/categories`, `/reference`, `/affiliate-networks` | ✓ | ✓ | ✓ | ✓ |\n| ⭐ Featured Placement Data | `/top-coupons`, `/featured-offers`, `/promotions` | ✓ | ✗ | ✓ | ✓ |\n| 🛍️ Additional Rewards Data | `/instore-offers`, `/instore-retailers`, `/instore-reference`, `/instore-spotlights`, `/printable-offers`, `/printable-reference`, `/gift-cards` | ✓ | ✗ | ✓ | ✓ |\n| 📦 Bulk Merchant Export | `/merchants-catalog` | ✓ | ✗ | ✗ | ✓ |\n| 📊 Advanced Merchant Intelligence | `/affiliate-campaigns`, `/cashback-events`, `/merchant-keywords` | ✓ | ✗ | ✗ | ✓ |\n\nBasic is a **very small full-access trial**: its green ticks allow every endpoint until its trial quota is used. Pro provides sustained access to the core data, Ultra adds featured and additional rewards data, and Mega unlocks bulk export and advanced intelligence. Upgrading from Basic to Pro or Ultra can remove access to some trial-only endpoints; choose Mega for sustained access to all endpoints. Request quotas and prices are set on RapidAPI's pricing page, not by this OAS document.\n\n| Endpoint | Feature controlling access | Basic | Pro | Ultra | Mega |\n| --- | --- | :---: | :---: | :---: | :---: |\n| `/status` | Unattached — always available | ✓ | ✓ | ✓ | ✓ |\n| `/merchants` | 🔎 Merchant Discovery Data | ✓ | ✓ | ✓ | ✓ |\n| `/merchants-catalog` | 📦 Bulk Merchant Export | ✓ | ✗ | ✗ | ✓ |\n| `/merchant-details` | 🔎 Merchant Discovery Data | ✓ | ✓ | ✓ | ✓ |\n| `/merchant-autocomplete` | 🔎 Merchant Discovery Data | ✓ | ✓ | ✓ | ✓ |\n| `/merchant-by-url` | 🔎 Merchant Discovery Data | ✓ | ✓ | ✓ | ✓ |\n| `/cashback-rate` | 💸 Cashback Campaign Data | ✓ | ✓ | ✓ | ✓ |\n| `/cashback-campaign` | 💸 Cashback Campaign Data | ✓ | ✓ | ✓ | ✓ |\n| `/affiliate-campaigns` | 📊 Advanced Merchant Intelligence | ✓ | ✗ | ✗ | ✓ |\n| `/cashback-events` | 📊 Advanced Merchant Intelligence | ✓ | ✗ | ✗ | ✓ |\n| `/coupons` | 🎟️ Coupon Lookup Data | ✓ | ✓ | ✓ | ✓ |\n| `/coupon-count` | 🎟️ Coupon Lookup Data | ✓ | ✓ | ✓ | ✓ |\n| `/merchant-coupons` | 🎟️ Coupon Lookup Data | ✓ | ✓ | ✓ | ✓ |\n| `/top-coupons` | ⭐ Featured Placement Data | ✓ | ✗ | ✓ | ✓ |\n| `/coupon-lookup` | 🎟️ Coupon Lookup Data | ✓ | ✓ | ✓ | ✓ |\n| `/featured-offers` | ⭐ Featured Placement Data | ✓ | ✗ | ✓ | ✓ |\n| `/instore-offers` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/instore-retailers` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/instore-reference` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/instore-spotlights` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/printable-offers` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/printable-reference` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/gift-cards` | 🛍️ Additional Rewards Data | ✓ | ✗ | ✓ | ✓ |\n| `/merchant-keywords` | 📊 Advanced Merchant Intelligence | ✓ | ✗ | ✗ | ✓ |\n| `/promotions` | ⭐ Featured Placement Data | ✓ | ✗ | ✓ | ✓ |\n| `/affiliate-networks` | 🧭 Market Reference Data | ✓ | ✓ | ✓ | ✓ |\n| `/markets` | 🧭 Market Reference Data | ✓ | ✓ | ✓ | ✓ |\n| `/categories` | 🧭 Market Reference Data | ✓ | ✓ | ✓ | ✓ |\n| `/reference` | 🧭 Market Reference Data | ✓ | ✓ | ✓ | ✓ |\n\n## Common Use Cases\n\n- Build a four-market merchant and coupon directory.\n- Show current cashback offers and campaign terms next to merchant profiles.\n- Track featured placements, sponsored merchants and promotional themes.\n- Compare in-store, printable and gift-card rewards where available.\n- Export a merchant catalogue for internal analysis on Mega.\n- Research merchant keywords, campaign attribution and cashback schedules on Mega.\n\n## Built for Developers\n\nEvery endpoint is a `GET` request with query parameters. Start with `/markets`, `/categories` or merchant autocomplete to discover valid market and merchant IDs, then request only the datasets your workflow needs. The API is available through RapidAPI; no source-site scraping setup is needed in your application.\n\n## Why Use This API?\n\n- One integration spans iGraal France, Spain and Poland plus Shoop Germany.\n- Separate endpoints let you fetch merchant, coupon, cashback and promotion data as needed.\n- Both online and participating offline reward programmes are covered.\n- URL lookup and reference routes make IDs discoverable.\n- A small full-access Basic trial lets buyers test specialized endpoints before choosing a paid tier.\n\n## API Categories\n\n- Merchants\n- Cashback\n- Coupons\n- In-Store\n- Printable Coupons\n- Gift Cards\n- Intelligence\n- Reference\n- Health\n\n## Start Building\n\nChoose a market, find a merchant or coupon, and combine the cashback and reward endpoints your product needs. Start on Basic to test every route, then select Pro, Ultra or Mega for the endpoint access and request allowance that fit your production workflow.", "x-website": "https://fr.igraal.com/", "x-public": true, "x-thumbnail": "https://rapidapi-prod-apis.s3.amazonaws.com/43e4f0db-993e-4e57-b31d-b164bef1b7ea.png", "x-version-lifecycle": "active", "termsOfService": "The best unofficial iGraal and Shoop cashback and coupon data API" }, "tags": [ { "name": "Merchants", "description": "Merchants", "index": 0 }, { "name": "Cashback", "description": "Cashback", "index": 1 }, { "name": "Coupons", "description": "Coupons", "index": 2 }, { "name": "In-Store", "description": "In-Store", "index": 3 }, { "name": "Printable Coupons", "description": "Printable Coupons", "index": 4 }, { "name": "Gift Cards", "description": "Gift Cards", "index": 5 }, { "name": "Intelligence", "description": "Intelligence", "index": 6 }, { "name": "Reference", "description": "Reference", "index": 7 }, { "name": "Health", "description": "Health", "index": 8 } ], "components": { "schemas": { "CommonHealthCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "IgraalSuccessResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true }, "data": { "nullable": true } }, "required": [ "success" ] }, "IgraalErrorResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "An unexpected error occurred. Please try again." } }, "required": [ "success", "message" ] } }, "parameters": {} }, "paths": { "/status": { "get": { "tags": [ "Health" ], "operationId": "/status", "description": "Check whether the iGraal API is available.", "responses": { "200": { "description": "Health check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonHealthCheckResponse" } } } } } } }, "/merchants": { "get": { "tags": [ "Merchants" ], "operationId": "/merchants", "description": "Search and filter the merchant catalogue: free text, category, affiliate network, quality grade, cashback and publication status.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Free-text merchant-name search.** Optional.\n\nMatches on the merchant name, not the website — `nike` finds Nike, Nike By You and Nike Team\nSport, while `nike.com` finds nothing. To look a shop up by its domain use `website_url`\ninstead, which matches on the host.\n\n- `nike` — Nike and related merchant entries in France\n- `zalando` — the Zalando family (Zalando, Zalando Privé, Zalando Lounge, …)\n\nAn unmatched term returns an empty list with `total: 0`, not an error.", "example": "" }, "required": false, "description": "**Free-text merchant-name search.** Optional.\n\nMatches on the merchant name, not the website — `nike` finds Nike, Nike By You and Nike Team\nSport, while `nike.com` finds nothing. To look a shop up by its domain use `website_url`\ninstead, which matches on the host.\n\n- `nike` — Nike and related merchant entries in France\n- `zalando` — the Zalando family (Zalando, Zalando Privé, Zalando Lounge, …)\n\nAn unmatched term returns an empty list with `total: 0`, not an error.", "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "**Find merchants by the shop's own website.** Optional. The domain-to-merchant resolver.\n\nMatches on the host, so protocol, `www.`, trailing slash and path are all ignored and these\nare equivalent: `https://www.nike.com/`, `www.nike.com`, `nike.com`, `https://www.nike.com/fr/`.\nA bare brand fragment such as `zalando` can match more merchants than a complete host.\n\n- `https://www.nike.com` — Nike-related shops\n- `sosh.fr` — Sosh storefronts\n\nFor a one-call answer that also auto-detects the market from an iGraal landing URL, use\n`/merchant-by-url`.", "example": "" }, "required": false, "description": "**Find merchants by the shop's own website.** Optional. The domain-to-merchant resolver.\n\nMatches on the host, so protocol, `www.`, trailing slash and path are all ignored and these\nare equivalent: `https://www.nike.com/`, `www.nike.com`, `nike.com`, `https://www.nike.com/fr/`.\nA bare brand fragment such as `zalando` can match more merchants than a complete host.\n\n- `https://www.nike.com` — Nike-related shops\n- `sosh.fr` — Sosh storefronts\n\nFor a one-call answer that also auto-detects the market from an iGraal landing URL, use\n`/merchant-by-url`.", "name": "website_url", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to one or more category ids.** Optional.\n\nIds are the UUIDs returned by `/categories` — both top-level categories and subcategories work.\nSeveral ids are a union (OR): a merchant matching any of them is returned.\n\n- `031f9caf-03b3-4a8f-b52a-7a476abe70c4` — Fashion & Accessories\n- `75384eb3-272f-495f-bba8-d33158d1a106` — Electronics\n\nA top-level id also matches merchants tagged only with its SUBcategories, so filtering by\n\"Broadband & Phone Contracts\" returns the Broadband and Mobile Contracts merchants — but each\nreturned merchant's own `category_ids` lists the subcategory it carries, not the parent you\nfiltered on. That is expected, not a mismatch.\n\nAn id that does not exist yields `total: 0` rather than an error, so verify ids against\n`/categories` before trusting an empty result. Comma-separated.", "example": "" }, "required": false, "description": "**Restrict to one or more category ids.** Optional.\n\nIds are the UUIDs returned by `/categories` — both top-level categories and subcategories work.\nSeveral ids are a union (OR): a merchant matching any of them is returned.\n\n- `031f9caf-03b3-4a8f-b52a-7a476abe70c4` — Fashion & Accessories\n- `75384eb3-272f-495f-bba8-d33158d1a106` — Electronics\n\nA top-level id also matches merchants tagged only with its SUBcategories, so filtering by\n\"Broadband & Phone Contracts\" returns the Broadband and Mobile Contracts merchants — but each\nreturned merchant's own `category_ids` lists the subcategory it carries, not the parent you\nfiltered on. That is expected, not a mismatch.\n\nAn id that does not exist yields `total: 0` rather than an error, so verify ids against\n`/categories` before trusting an empty result. Comma-separated.", "name": "category_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to merchants running on given affiliate networks.** Optional.\n\nIds come from `/affiliate-networks` and are also echoed on every merchant as\n`affiliate.network_id`. Several ids are a union (OR).\n\n- `fr_21` — Impact Radius (France)\n- `fr_25` — Awin (France)\n- `fr_13` — WebGains (France)\n- `fr_2` — Kwanko (France)\n- `fr_8` — No Affiliate Network: merchants with no network behind them. Exclude this id\n when you want monetised merchants.\n\nThis is the filter to use for network-level competitive analysis: \"which merchants does this\nnetwork monetise in this market\". Comma-separated.", "example": "" }, "required": false, "description": "**Restrict to merchants running on given affiliate networks.** Optional.\n\nIds come from `/affiliate-networks` and are also echoed on every merchant as\n`affiliate.network_id`. Several ids are a union (OR).\n\n- `fr_21` — Impact Radius (France)\n- `fr_25` — Awin (France)\n- `fr_13` — WebGains (France)\n- `fr_2` — Kwanko (France)\n- `fr_8` — No Affiliate Network: merchants with no network behind them. Exclude this id\n when you want monetised merchants.\n\nThis is the filter to use for network-level competitive analysis: \"which merchants does this\nnetwork monetise in this market\". Comma-separated.", "name": "affiliate_network_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Fetch specific merchants by id, in one call.** Optional.\n\nA batch lookup — pass up to a page-worth of merchant ids and get their full cards back\ntogether, instead of one `/merchant-details` call each.\n\n- `fr_806` — Nike alone\n- `fr_806,fr_97` — Nike and adidas\n\nIds are market-scoped; one from another market is simply not matched. Comma-separated.", "example": "" }, "required": false, "description": "**Fetch specific merchants by id, in one call.** Optional.\n\nA batch lookup — pass up to a page-worth of merchant ids and get their full cards back\ntogether, instead of one `/merchant-details` call each.\n\n- `fr_806` — Nike alone\n- `fr_806,fr_97` — Nike and adidas\n\nIds are market-scoped; one from another market is simply not matched. Comma-separated.", "name": "merchant_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to merchants at given quality grades.** Optional. Numeric positions, not letters.\n\nThe platform grades every merchant, and the grade drives its own ranking. Several positions are\na union (OR). Full table at `/reference` (`merchant_qualities`):\n\n- `1` AAA · `2` AA+ · `3` AA · `4` A+ · `5` A · `6` B · `7` C · `8` D · `9` E · `10` F\n- `11` Not indexed in all domains · `12` Pending · `13` Rejected\n\nFor example, `1,2` selects the two highest grades.\n\nEvery value must be a number — a non-numeric token is rejected with a `400` naming it, rather\nthan dropped (which would silently return the unfiltered catalogue). Comma-separated.", "example": "" }, "required": false, "description": "**Restrict to merchants at given quality grades.** Optional. Numeric positions, not letters.\n\nThe platform grades every merchant, and the grade drives its own ranking. Several positions are\na union (OR). Full table at `/reference` (`merchant_qualities`):\n\n- `1` AAA · `2` AA+ · `3` AA · `4` A+ · `5` A · `6` B · `7` C · `8` D · `9` E · `10` F\n- `11` Not indexed in all domains · `12` Pending · `13` Rejected\n\nFor example, `1,2` selects the two highest grades.\n\nEvery value must be a number — a non-numeric token is rejected with a `400` naming it, rather\nthan dropped (which would silently return the unfiltered catalogue). Comma-separated.", "name": "quality_positions", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only merchants with a live cashback campaign.** Optional — unset returns every merchant.\n\nUse this to narrow a merchant catalogue to shops offering cashback.\n\n- `true` — merchants carrying a campaign right now\n- unset — no filtering on cashback\n\n**`false` is rejected with a 400, deliberately.** There is no inverse filter: the catalogue\nindex narrows on `true` only, and a `false` would quietly return the whole catalogue under a\nname that reads like the opposite. To count merchants without a campaign, subtract the\n`has_cashback=true` total from the unfiltered total.\n\nOne caveat worth knowing: a merchant can pass this filter and still have no campaign that\nresolves on `/cashback-rate`. The flag is a catalogue property and the campaign is a separate\nrecord, so the two can disagree for a day.", "example": "" }, "required": false, "description": "**Only merchants with a live cashback campaign.** Optional — unset returns every merchant.\n\nUse this to narrow a merchant catalogue to shops offering cashback.\n\n- `true` — merchants carrying a campaign right now\n- unset — no filtering on cashback\n\n**`false` is rejected with a 400, deliberately.** There is no inverse filter: the catalogue\nindex narrows on `true` only, and a `false` would quietly return the whole catalogue under a\nname that reads like the opposite. To count merchants without a campaign, subtract the\n`has_cashback=true` total from the unfiltered total.\n\nOne caveat worth knowing: a merchant can pass this filter and still have no campaign that\nresolves on `/cashback-rate`. The flag is a catalogue property and the campaign is a separate\nrecord, so the two can disagree for a day.", "name": "has_cashback", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only merchants published on the public site.** Optional — unset returns both.\n\nUnpublished rows are real records — merchants not yet live, retired, or held back —\nso set `published=true` before quoting a merchant count or rendering a directory.\n\n- `true` — live on the storefront\n- `false` — present in the catalogue but not shown\n\nAlso accepts `1`/`yes` and `0`/`no`. Any other value is a `400` — this filter is never quietly\ndropped, because an ignored filter and an unfiltered call look identical in the response.", "example": "" }, "required": false, "description": "**Only merchants published on the public site.** Optional — unset returns both.\n\nUnpublished rows are real records — merchants not yet live, retired, or held back —\nso set `published=true` before quoting a merchant count or rendering a directory.\n\n- `true` — live on the storefront\n- `false` — present in the catalogue but not shown\n\nAlso accepts `1`/`yes` and `0`/`no`. Any other value is a `400` — this filter is never quietly\ndropped, because an ignored filter and an unfiltered call look identical in the response.", "name": "published", "in": "query" }, { "schema": { "type": "string", "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own ranking (quality grade, campaign richness, recency)\n- `name` — alphabetical by merchant name; pair with `order`\n\nThese are the only two orderings the merchant index honours. Ordering by rate, coupon count\nor update date is not offered because the index ignores those keys and would silently hand\nback the default ranking under a different name.", "enum": [ "relevance", "name" ], "default": "relevance", "example": "relevance" }, "required": false, "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own ranking (quality grade, campaign richness, recency)\n- `name` — alphabetical by merchant name; pair with `order`\n\nThese are the only two orderings the merchant index honours. Ordering by rate, coupon count\nor update date is not offered because the index ignores those keys and would silently hand\nback the default ranking under a different name.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" }, "required": false, "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "name": "order", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "default": 20, "example": 20 }, "required": false, "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "Merchants matching the filters, with logos, landing pages, affiliate-network attribution and quality grade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 5, "page": 1, "limit": 20, "total_pages": 1, "merchants": [ { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchants-catalog": { "get": { "tags": [ "Merchants" ], "operationId": "/merchants-catalog", "description": "Walk the entire merchant catalogue with a resumable cursor — the bulk-export path.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page of the catalogue walk.** Optional — default and maximum `200`.\n\nThis is a keyset walk, not offset pagination, so a larger page is simply fewer round trips —\nthere is no `page` number to combine it with. It is also the only way to read a whole catalogue:\n`/merchants` serves at most the first 10,000 results for any filter, this endpoint has no such\nceiling.\n\nEx: `200` (maximum) for a bulk export; a small value like `20` for\nincremental polling.\nContinue with `next_token` until `has_more` is false.", "minimum": 1, "maximum": 200, "default": 200, "example": 200 }, "required": false, "description": "**Rows per page of the catalogue walk.** Optional — default and maximum `200`.\n\nThis is a keyset walk, not offset pagination, so a larger page is simply fewer round trips —\nthere is no `page` number to combine it with. It is also the only way to read a whole catalogue:\n`/merchants` serves at most the first 10,000 results for any filter, this endpoint has no such\nceiling.\n\nEx: `200` (maximum) for a bulk export; a small value like `20` for\nincremental polling.\nContinue with `next_token` until `has_more` is false.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Keyset cursor to resume the walk.** Optional — omit to start from the first merchant in the\ncatalogue.\n\nPass back, unchanged, the `next_token` from the previous response. The usual pattern is \"call\nonce with no token, then keep passing back what you got until you stop\". The token is opaque —\nit is not a merchant id and nothing in your code should try to build, parse or edit one.\n\n`has_more: false` (equivalently, a `null` `next_token` in the response) means there is no next\npage — the walk has reached the end of the catalogue.\n\n**A token this endpoint did not issue is refused with a `400`, on purpose.** The cursor carries\nthe market it belongs to and a checksum, so a stale, edited, hand-made or wrong-market token is\nrejected with a message saying which of those it was. That matters more here than it looks: the\nunderlying position is a sorted merchant id, so a made-up but plausible token would otherwise\nresume in the MIDDLE of the catalogue and silently skip every merchant before it — a bulk export\nthat quietly loses rows with nothing in the response to reveal it. Resuming is therefore either\nexactly right or a clean error, never a silent short read.", "example": "" }, "required": false, "description": "**Keyset cursor to resume the walk.** Optional — omit to start from the first merchant in the\ncatalogue.\n\nPass back, unchanged, the `next_token` from the previous response. The usual pattern is \"call\nonce with no token, then keep passing back what you got until you stop\". The token is opaque —\nit is not a merchant id and nothing in your code should try to build, parse or edit one.\n\n`has_more: false` (equivalently, a `null` `next_token` in the response) means there is no next\npage — the walk has reached the end of the catalogue.\n\n**A token this endpoint did not issue is refused with a `400`, on purpose.** The cursor carries\nthe market it belongs to and a checksum, so a stale, edited, hand-made or wrong-market token is\nrejected with a message saying which of those it was. That matters more here than it looks: the\nunderlying position is a sorted merchant id, so a made-up but plausible token would otherwise\nresume in the MIDDLE of the catalogue and silently skip every merchant before it — a bulk export\nthat quietly loses rows with nothing in the response to reveal it. Resuming is therefore either\nexactly right or a clean error, never a silent short read.", "name": "next_token", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "A keyset-paginated walk of the FULL merchant catalogue for one market, including merchants that\nare not published on the public storefront. Use `next_token` to page through it; call `/merchants`\nwith `published=true` instead if only live merchants are wanted.\n\nOne difference from `/merchants` worth planning around: rows from this walk carry no\n`landing_page` — the bulk path does not populate it, for any merchant in any market. If you need\nthe storefront page URL, take it from `/merchants` or `/merchant-details`. Every other field on\nthe merchant card, logos and affiliate attribution included, is identical.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "limit": 200, "returned": 200, "next_token": "djE6ZnI6MDA5Y2JmYWItNTk4YS00NWIyLTk1ZmYtNTg1OTUzYTQ5Y2U4OjFsMHEweWY", "has_more": true, "merchants": [ { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchant-details": { "get": { "tags": [ "Merchants" ], "operationId": "/merchant-details", "description": "Everything about one merchant: cashback, gift card, recent coupons, logos and affiliate attribution.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "example": "fr_97" }, "required": true, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "integer", "description": "**How many recent coupons to embed in the response.** Optional — default `100`, maximum `500`.\n\nThis trims the `recent_coupons` list nested in this response — it is NOT the merchant's full\ncoupon archive. Set `0` to fetch the merchant card without any coupons at all (fastest call).\n\n- `0` — merchant card only, no coupons\n- `100` (default) — a generous recent slice for most storefronts\n- `500` (maximum) — the largest slice this endpoint will embed\n\nThis is a recent slice. Call `/merchant-coupons` for the complete, paginated archive.", "default": 100, "example": 100 }, "required": false, "description": "**How many recent coupons to embed in the response.** Optional — default `100`, maximum `500`.\n\nThis trims the `recent_coupons` list nested in this response — it is NOT the merchant's full\ncoupon archive. Set `0` to fetch the merchant card without any coupons at all (fastest call).\n\n- `0` — merchant card only, no coupons\n- `100` (default) — a generous recent slice for most storefronts\n- `500` (maximum) — the largest slice this endpoint will embed\n\nThis is a recent slice. Call `/merchant-coupons` for the complete, paginated archive.", "name": "coupon_limit", "in": "query" } ], "responses": { "200": { "description": "The full merchant card — logo, landing page, affiliate attribution, quality grade, live\ncashback rate and gift card — plus a recent slice of its coupons. `recent_coupons` is a\nRECENT SLICE, not the archive; call `/merchant-coupons` for the complete, paginated history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z", "cashback": { "campaign_id": "019fa8e5-0473-77b6-b8e1-d322e042e7b8", "rate": { "value": 4, "type": "PERCENTAGE", "display": "4% par achat sur tous les autres produits", "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "starts_at": "2026-07-28T22:00:00Z", "ends_at": "2026-08-31T21:59:59.999Z" }, "previous_rate": { "value": 2, "type": "PERCENTAGE", "starts_at": "2026-08-31T22:00:00Z", "ends_at": "2036-07-28T21:59:59.999Z" }, "combinable_with_coupons": true, "tiers": [ { "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "type": "DEFAULT", "status": "ACTIVE", "display_text": "4% par achat sur tous les autres produits", "member_rate": { "value": 4, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 7, "type": "PERCENTAGE" } }, { "offer_id": "019fa8eb-4d8d-707e-92a9-3d311e6048af", "type": "ADVANCED", "status": "ACTIVE", "display_text": "2.5% par achat sur tous les produits de la série X7", "member_rate": { "value": 2.5, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 5, "type": "PERCENTAGE" } } ], "conditions": [ { "id": "019fa8e7-b15e-7077-9107-6bc7177372d9", "text": "Attention, pas de cashback sur les achats effectués sur l'application du marchand.", "status": "ACTIVE" } ] }, "cashback_unavailable_reason": null, "gift_card": null, "recent_coupons": [ { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": null } ], "recent_coupons_returned": 1, "recent_coupons_note": "A recent slice only. Use /merchant-coupons for the full, paginated coupon archive." } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchant-autocomplete": { "get": { "tags": [ "Merchants" ], "operationId": "/merchant-autocomplete", "description": "Type-ahead merchant lookup — turn what a shopper types into a merchant id.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**What the shopper is typing, right now.** Required. A partial merchant name, as short as one\nor two letters.\n\nThis is prefix/typeahead search, not the full-text search on `/merchants` — it is built to be\ncalled on every keystroke of a search box and to answer fast with just enough to render a\ndropdown. Use it to turn free text a user types into a concrete merchant `id` before calling\nanything else.\n\n- `nik` — matches Nike, Nike By You, Nike Team Sport\n- `ada` — matches adidas\n\nA term matching nothing returns `count: 0` and an empty `merchants` array, never an error.", "example": "nik" }, "required": true, "description": "**What the shopper is typing, right now.** Required. A partial merchant name, as short as one\nor two letters.\n\nThis is prefix/typeahead search, not the full-text search on `/merchants` — it is built to be\ncalled on every keystroke of a search box and to answer fast with just enough to render a\ndropdown. Use it to turn free text a user types into a concrete merchant `id` before calling\nanything else.\n\n- `nik` — matches Nike, Nike By You, Nike Team Sport\n- `ada` — matches adidas\n\nA term matching nothing returns `count: 0` and an empty `merchants` array, never an error.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum suggestions to return.** Optional — default `10`, maximum `50`.\n\nKeep this small for a live dropdown (`5`-`10`); raise it only for a one-shot bulk lookup where\nyou want every plausible match for a fuzzy fragment.\n\nEx: `10` (default), `5` for a compact dropdown, `50` (maximum).", "default": 10, "example": 10 }, "required": false, "description": "**Maximum suggestions to return.** Optional — default `10`, maximum `50`.\n\nKeep this small for a live dropdown (`5`-`10`); raise it only for a one-shot bulk lookup where\nyou want every plausible match for a fuzzy fragment.\n\nEx: `10` (default), `5` for a compact dropdown, `50` (maximum).", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Fast prefix/typeahead merchant search — the quick way to turn what a shopper types into a merchant id, for a live search box.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "term": "nik", "count": 1, "merchants": [ { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchant-by-url": { "get": { "tags": [ "Merchants" ], "operationId": "/merchant-by-url", "description": "Resolve a shop's own website or an iGraal landing page to the matching merchants, in one call.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "**A URL to resolve to a merchant.** Required. The URL front door — paste in either side of a\ncashback link and get the merchant(s) back in one call.\n\nTwo shapes are accepted and auto-detected from the host:\n\n- **A shop's own website**, e.g. `https://www.nike.com` — matched against the merchant index by\n host, exactly like the `website_url` filter on `/merchants`.\n- **An iGraal or Shoop landing page**, e.g.\n `https://fr.igraal.com/codes-promo/nike/code-promotionnel` or `https://de.igraal.com/gutschein/hbada`\n — the market is read straight off the host (`fr.igraal.com` → `fr`, `de.igraal.com` → `de`),\n so `market` is never consulted for these.\n\nA bare domain without a scheme (`nike.com`) works too. A string that does not parse as a URL at\nall returns a `400`.", "example": "https://www.nike.com" }, "required": true, "description": "**A URL to resolve to a merchant.** Required. The URL front door — paste in either side of a\ncashback link and get the merchant(s) back in one call.\n\nTwo shapes are accepted and auto-detected from the host:\n\n- **A shop's own website**, e.g. `https://www.nike.com` — matched against the merchant index by\n host, exactly like the `website_url` filter on `/merchants`.\n- **An iGraal or Shoop landing page**, e.g.\n `https://fr.igraal.com/codes-promo/nike/code-promotionnel` or `https://de.igraal.com/gutschein/hbada`\n — the market is read straight off the host (`fr.igraal.com` → `fr`, `de.igraal.com` → `de`),\n so `market` is never consulted for these.\n\nA bare domain without a scheme (`nike.com`) works too. A string that does not parse as a URL at\nall returns a `400`.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**Market to search in, for a shop website URL only.** Optional — defaults to `fr`.\n\nOnly consulted when `url` is an external shop website (`https://www.nike.com`) — an iGraal or\nShoop landing page (`https://fr.igraal.com/codes-promo/nike/code-promotionnel`) carries its own\nmarket in the host and this value is silently ignored for those.\n\nEx: `de` to look up `https://www.nike.com` inside the Shoop Germany catalogue instead of iGraal\nFrance.", "default": "fr", "example": "fr" }, "required": false, "description": "**Market to search in, for a shop website URL only.** Optional — defaults to `fr`.\n\nOnly consulted when `url` is an external shop website (`https://www.nike.com`) — an iGraal or\nShoop landing page (`https://fr.igraal.com/codes-promo/nike/code-promotionnel`) carries its own\nmarket in the host and this value is silently ignored for those.\n\nEx: `de` to look up `https://www.nike.com` inside the Shoop Germany catalogue instead of iGraal\nFrance.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "Resolves a pasted URL to its merchant(s). Accepts BOTH a shop's own website\n(`https://www.nike.com`) and an iGraal/Shoop landing page\n(`https://fr.igraal.com/codes-promo/nike/code-promotionnel`), auto-detecting the market from an\niGraal host. The response shape differs by `resolved_as`: an `igraal_landing_page` match also\ncarries `slug` and `exact_landing_page_match`; a `merchant_website` match carries `host` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "input_url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "resolved_as": "igraal_landing_page", "market": "fr", "slug": "nike", "match_count": 1, "exact_landing_page_match": true, "merchants": [ { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/cashback-rate": { "get": { "tags": [ "Cashback" ], "operationId": "/cashback-rate", "description": "A merchant's live cashback rate, its previous rate, every tier and the campaign conditions.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "example": "fr_97" }, "required": true, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "name": "merchant_id", "in": "query" } ], "responses": { "200": { "description": "The flagship endpoint: a merchant's live cashback rate. Leads on `cashback.rate` (the current numeric value and its display text) alongside `cashback.previous_rate` (what it was before the last change, useful for a \"rate just dropped/rose\" alert), then `cashback.tiers` — every active tier on the campaign with its own `display_text`, and separately `cashback.tiers[].member_rate` (what the shopper earns) versus `cashback.tiers[].network_rate` (what the affiliate network pays the platform for the same action — never shown to the shopper, useful for margin analysis). `cashback.conditions` lists the fine print (exclusions, minimum basket, app vs web). A merchant with no live campaign right now has no rate to give and answers 404 with `cashback_unavailable_reason` set on a related lookup — this is the normal state for the long tail of the catalogue, not an error to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "merchant": { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" }, "cashback": { "campaign_id": "019fa8e5-0473-77b6-b8e1-d322e042e7b8", "rate": { "value": 4, "type": "PERCENTAGE", "display": "4% par achat sur tous les autres produits", "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "starts_at": "2026-07-28T22:00:00Z", "ends_at": "2026-08-31T21:59:59.999Z" }, "previous_rate": { "value": 2, "type": "PERCENTAGE", "starts_at": "2026-08-31T22:00:00Z", "ends_at": "2036-07-28T21:59:59.999Z" }, "combinable_with_coupons": true, "tiers": [ { "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "type": "DEFAULT", "status": "ACTIVE", "display_text": "4% par achat sur tous les autres produits", "member_rate": { "value": 4, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 7, "type": "PERCENTAGE" } }, { "offer_id": "019fa8eb-4d8d-707e-92a9-3d311e6048af", "type": "ADVANCED", "status": "ACTIVE", "display_text": "2.5% par achat sur tous les produits de la série X7", "member_rate": { "value": 2.5, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 5, "type": "PERCENTAGE" } } ], "conditions": [ { "id": "019fa8e7-b15e-7077-9107-6bc7177372d9", "text": "Attention, pas de cashback sur les achats effectués sur l'application du marchand.", "status": "ACTIVE" } ] }, "cashback_unavailable_reason": null } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/cashback-campaign": { "get": { "tags": [ "Cashback" ], "operationId": "/cashback-campaign", "description": "Every tier and condition on one cashback campaign, by campaign id.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "**Cashback campaign id.** Required. The id of the whole campaign a merchant is currently running,\nas opposed to a single tier inside it.\n\nGet one from `cashback.campaign_id` on `/cashback-rate`, or from `/merchant-details`. This endpoint\nthen returns EVERY tier on that campaign — including tiers that are not surfaced on the merchant\ncard because they are narrower (a specific product line, a specific action type) than the headline\nrate shown there.\n\nEx: `019fa8e5-0473-77b6-b8e1-d322e042e7b8` — the current Nike (France) campaign.\n\nAn id that does not exist, or belongs to a campaign that has since been fully retired, returns 404.", "example": "019fa8e5-0473-77b6-b8e1-d322e042e7b8" }, "required": true, "description": "**Cashback campaign id.** Required. The id of the whole campaign a merchant is currently running,\nas opposed to a single tier inside it.\n\nGet one from `cashback.campaign_id` on `/cashback-rate`, or from `/merchant-details`. This endpoint\nthen returns EVERY tier on that campaign — including tiers that are not surfaced on the merchant\ncard because they are narrower (a specific product line, a specific action type) than the headline\nrate shown there.\n\nEx: `019fa8e5-0473-77b6-b8e1-d322e042e7b8` — the current Nike (France) campaign.\n\nAn id that does not exist, or belongs to a campaign that has since been fully retired, returns 404.", "name": "campaign_id", "in": "query" } ], "responses": { "200": { "description": "The full tier and condition set for one cashback campaign — every rate tier the campaign runs (not just the one headlined on the merchant card) plus the fine-print conditions attached to it. Use this after `/cashback-rate` or `/merchant-details` hand you a `campaign_id`, when you need the complete rate structure rather than just the current best rate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "campaign_id": "019fa8e5-0473-77b6-b8e1-d322e042e7b8", "tiers": [ { "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "type": "DEFAULT", "status": "ACTIVE", "display_text": "4% par achat sur tous les autres produits", "member_rate": { "value": 4, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 7, "type": "PERCENTAGE" } }, { "offer_id": "019fa8eb-4d8d-707e-92a9-3d311e6048af", "type": "ADVANCED", "status": "ACTIVE", "display_text": "2.5% par achat sur tous les produits de la série X7", "member_rate": { "value": 2.5, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 5, "type": "PERCENTAGE" } } ], "conditions": [ { "id": "019fa8e7-b15e-7077-9107-6bc7177372d9", "text": "Attention, pas de cashback sur les achats effectués sur l'application du marchand.", "status": "ACTIVE" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/affiliate-campaigns": { "get": { "tags": [ "Cashback" ], "operationId": "/affiliate-campaigns", "description": "Affiliate-network attribution per campaign: network, program id and tracking link.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Look up affiliate campaigns by their own CAMPAIGN legacy id.** Required — at least one id.\n\n**The one trap here:** this filters on `campaign_legacy_id` — the legacy id of the CAMPAIGN itself —\nNOT on `merchant_legacy_id`, the merchant's own legacy id from `/merchants`. The two id spaces are\ndistinct and only coincidentally close in range. Example: `762` returns a campaign with\n`campaign_legacy_id: 762` whose `merchant_legacy_id` is `662` — a different number on the same row.\nBoth ids are always returned on each campaign so the difference is visible rather than silently\nwrong.\n\nA merchant's `legacy_id` (from `/merchants`) is a reasonable starting guess when you have nothing\nelse, but expect it to sometimes miss — resolve the real value from a campaign you already have\n(via `/cashback-rate` → `/cashback-campaign`) whenever precision matters.\n\nSeveral ids are a union (OR): `762,861` returns campaigns for either.\n\nEvery value must be a number; a non-numeric token is a `400` naming it rather than a silently\ndropped id. Comma-separated.", "example": "762" }, "required": true, "description": "**Look up affiliate campaigns by their own CAMPAIGN legacy id.** Required — at least one id.\n\n**The one trap here:** this filters on `campaign_legacy_id` — the legacy id of the CAMPAIGN itself —\nNOT on `merchant_legacy_id`, the merchant's own legacy id from `/merchants`. The two id spaces are\ndistinct and only coincidentally close in range. Example: `762` returns a campaign with\n`campaign_legacy_id: 762` whose `merchant_legacy_id` is `662` — a different number on the same row.\nBoth ids are always returned on each campaign so the difference is visible rather than silently\nwrong.\n\nA merchant's `legacy_id` (from `/merchants`) is a reasonable starting guess when you have nothing\nelse, but expect it to sometimes miss — resolve the real value from a campaign you already have\n(via `/cashback-rate` → `/cashback-campaign`) whenever precision matters.\n\nSeveral ids are a union (OR): `762,861` returns campaigns for either.\n\nEvery value must be a number; a non-numeric token is a `400` naming it rather than a silently\ndropped id. Comma-separated.", "name": "legacy_ids", "in": "query" } ], "responses": { "200": { "description": "Affiliate-network attribution for cashback campaigns, looked up by CAMPAIGN legacy id (not the merchant's legacy id — see `legacy_ids` for the distinction, with `campaign_legacy_id` and `merchant_legacy_id` both echoed on every row). Each campaign carries its `network_id`, `network_name`, `network_program_id` and `tracking_url` — the exact attribution the network itself needs to reconcile a sale. `offers` lists the matching rate tiers alongside the campaigns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "requested_legacy_ids": [ 762 ], "campaign_count": 1, "campaigns": [ { "campaign_id": "019fa8e5-0473-77b6-b8e1-d322e042e7b8", "campaign_legacy_id": 762, "merchant_id": "fr_806", "merchant_legacy_id": 662, "network_id": "fr_2", "network_name": "Kwanko", "network_name_source": "table", "network_program_id": "16328", "tracking_url": "https://www.awin1.com/cread.php?awinmid=16328&awinaffid=268651", "tracking_type": "DEEPLINK", "shares_action_details": true, "combinable_with_coupons": true, "last_modified_at": "2026-06-22T09:24:36.467Z" } ], "offers": [ { "offer_id": "019fa8ea-283b-777f-8d3a-6edc579e3012", "type": "DEFAULT", "status": "ACTIVE", "display_text": "4% par achat sur tous les autres produits", "member_rate": { "value": 4, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 7, "type": "PERCENTAGE" } }, { "offer_id": "019fa8eb-4d8d-707e-92a9-3d311e6048af", "type": "ADVANCED", "status": "ACTIVE", "display_text": "2.5% par achat sur tous les produits de la série X7", "member_rate": { "value": 2.5, "type": "PERCENTAGE", "vat_percent": 20 }, "network_rate": { "value": 5, "type": "PERCENTAGE" } } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/cashback-events": { "get": { "tags": [ "Cashback" ], "operationId": "/cashback-events", "description": "The platform's own schedule of cashback-campaign events for one merchant — activations, stops and rate changes, past and upcoming.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "example": "fr_97" }, "required": true, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict the schedule to one kind of event.** Optional — unset returns every event on the\ncalendar, past and future alike.\n\n- `ACTIVATED` — a cashback campaign goes live for this merchant\n- `REACTIVATED` — a campaign that had been stopped resumes\n- `STOPPED` — a campaign ends and the merchant drops out of cashback\n- `MAX_CASHBACK_CHANGED` — the headline rate moves while the campaign stays live\n\nEx: `MAX_CASHBACK_CHANGED` isolates the rate-move calendar — the rows that answer \"is this\nmerchant's rate about to change, and to what?\" — while `STOPPED` gives you the drop-out\nwatchlist. Matching is case-insensitive, and a value outside the list is rejected with a `400`\nnaming the field rather than silently ignored.", "enum": [ "ACTIVATED", "REACTIVATED", "STOPPED", "MAX_CASHBACK_CHANGED" ], "example": "" }, "required": false, "description": "**Restrict the schedule to one kind of event.** Optional — unset returns every event on the\ncalendar, past and future alike.\n\n- `ACTIVATED` — a cashback campaign goes live for this merchant\n- `REACTIVATED` — a campaign that had been stopped resumes\n- `STOPPED` — a campaign ends and the merchant drops out of cashback\n- `MAX_CASHBACK_CHANGED` — the headline rate moves while the campaign stays live\n\nEx: `MAX_CASHBACK_CHANGED` isolates the rate-move calendar — the rows that answer \"is this\nmerchant's rate about to change, and to what?\" — while `STOPPED` gives you the drop-out\nwatchlist. Matching is case-insensitive, and a value outside the list is rejected with a `400`\nnaming the field rather than silently ignored.", "name": "event_type", "in": "query" }, { "schema": { "type": "boolean", "description": "**Keep only events dated in the future.** Optional — unset returns the whole calendar, past\nevents included.\n\nSet `true` to turn this endpoint into a pure forward-looking rate calendar: what is scheduled to\nhappen to this merchant from right now onwards, and nothing that has already been applied. Leave\nit unset when you want the full picture — the past rows are what let you chart how a rate has\nmoved over the life of a campaign.\n\n- `true` — only events whose `scheduled_at` is later than the moment of the call\n- `false` — the full schedule (same as leaving it unset)\n\nAlso accepts `1`/`yes` and `0`/`no`. Any other value is a `400`, never a quietly dropped filter,\nbecause an ignored filter and an unfiltered call are indistinguishable in the response.", "example": "" }, "required": false, "description": "**Keep only events dated in the future.** Optional — unset returns the whole calendar, past\nevents included.\n\nSet `true` to turn this endpoint into a pure forward-looking rate calendar: what is scheduled to\nhappen to this merchant from right now onwards, and nothing that has already been applied. Leave\nit unset when you want the full picture — the past rows are what let you chart how a rate has\nmoved over the life of a campaign.\n\n- `true` — only events whose `scheduled_at` is later than the moment of the call\n- `false` — the full schedule (same as leaving it unset)\n\nAlso accepts `1`/`yes` and `0`/`no`. Any other value is a `400`, never a quietly dropped filter,\nbecause an ignored filter and an unfiltered call are indistinguishable in the response.", "name": "upcoming_only", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "**The cashback rate calendar for one merchant** — the platform's own published schedule of\ncampaign events, past and future, in one call. This is the endpoint that lets you see a rate\nchange *before* it lands rather than discovering it after the fact, and no comparable service\nin this space publishes it at all.\n\nEvents come back sorted oldest to newest by `scheduled_at`, so the tail of the list is the\nforward calendar. Each row carries the event itself (`event_type`, `status`, `scheduled_at`)\nand the campaign it belongs to (`campaign_id`, `campaign_starts_at`, `campaign_ends_at`,\n`network_id`, `commission_type`, `combinable_with_coupons`).\n\nAn empty schedule may mean either a merchant with no events or an unknown id.\nUse `/merchant-details` separately when that distinction matters.\n\n`event_type` is one of `ACTIVATED` (a campaign goes live), `REACTIVATED` (a stopped campaign\nresumes), `STOPPED` (a campaign ends) or `MAX_CASHBACK_CHANGED` (the headline rate moves). On a\n`MAX_CASHBACK_CHANGED` row, `rate` is the rate the change moves **to**, and `previous_rate` is\nthe rate it moved **from** whenever the platform records one — so a single row is a complete\nbefore/after of a rate move. Both are `null` on rows where no rate is attached.\n\n`status` tells you whether the row has taken effect: `PUBLISHED` means it has happened and been\napplied, `PENDING` means it is scheduled and has not been applied yet, and `CANCELLED` means it\nwas superseded before it took effect — a `CANCELLED` row never happened, so exclude it when\nreconstructing a rate history.\n\n**Coverage is partial, and an empty list is a normal `200`, not a fault.** Many\nmerchants have no scheduled events. Do not retry an empty result.\n\nThe example below shows one representative event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "merchant_id": "fr_97", "event_type": null, "upcoming_only": false, "count": 60, "events": [ { "id": "f7a95091-83c3-4616-97b6-911e71cd352a", "campaign_id": "01995247-02a6-72eb-9568-2ed04a7611af", "event_type": "MAX_CASHBACK_CHANGED", "status": "PUBLISHED", "scheduled_at": "2026-06-22T21:59:59.999Z", "created_at": "2026-06-15T09:31:46.906Z", "updated_at": "2026-06-22T22:00:04.118Z", "merchant_id": "fr_97", "network_id": "fr_25", "commission_type": "REGEX", "campaign_starts_at": "2026-06-15T09:31:46.906Z", "campaign_ends_at": "2026-07-31T21:59:59.999Z", "combinable_with_coupons": true, "rate": { "value": 3, "type": "PERCENTAGE", "offer_id": "019eca9f-7287-71b3-91ff-07afcbe7d266" }, "previous_rate": null } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/coupons": { "get": { "tags": [ "Coupons" ], "operationId": "/coupons", "description": "Market-wide coupon and deal feed, filterable by merchant, status and publication state.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Merchant id.** Optional — omit to search coupons across every merchant in the market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nGet one from `/merchants`, `/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`.\nAn id from a different market simply matches nothing — ids are market-scoped.", "example": "" }, "required": false, "description": "**Merchant id.** Optional — omit to search coupons across every merchant in the market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nGet one from `/merchants`, `/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`.\nAn id from a different market simply matches nothing — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict by lifecycle state.** Optional — unset returns both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`; the platform never deletes an expired coupon, so this is a genuine\n historical archive, not a rolling window that quietly drops old rows\n\nCombine with `merchant_id` to pull one shop's complete active-vs-expired history, or use it alone\nto narrow a market-wide total that would otherwise hit the 10,000-row count cap.", "enum": [ "active", "expired" ], "example": "" }, "required": false, "description": "**Restrict by lifecycle state.** Optional — unset returns both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`; the platform never deletes an expired coupon, so this is a genuine\n historical archive, not a rolling window that quietly drops old rows\n\nCombine with `merchant_id` to pull one shop's complete active-vs-expired history, or use it alone\nto narrow a market-wide total that would otherwise hit the 10,000-row count cap.", "name": "status", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only coupons published on the public site.** Optional — unset returns both.\n\nA coupon can exist in the index before or after its public run — an unpublished row is a real record,\nnot noise, so leave this unset when auditing the full archive and set it `true` before rendering a\nlive coupon list to end users.\n\n- `true` — live on the storefront right now\n- `false` — present in the index but not shown publicly", "example": "" }, "required": false, "description": "**Only coupons published on the public site.** Optional — unset returns both.\n\nA coupon can exist in the index before or after its public run — an unpublished row is a real record,\nnot noise, so leave this unset when auditing the full archive and set it `true` before rendering a\nlive coupon list to end users.\n\n- `true` — live on the storefront right now\n- `false` — present in the index but not shown publicly", "name": "published", "in": "query" }, { "schema": { "type": "string", "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own default ranking; there is no separate relevance score behind\n it, so this really means \"no explicit reorder applied\"\n- `end_time` — soonest/latest to expire first (pair with `order`)\n- `title` — alphabetical by coupon title (pair with `order`)\n\nOnly `end_time` and `title` genuinely reorder the result set — those are the two keys the coupon\nindex honours. Asking for anything else silently falls back to the default ranking.", "enum": [ "relevance", "end_time", "title" ], "default": "relevance", "example": "relevance" }, "required": false, "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own default ranking; there is no separate relevance score behind\n it, so this really means \"no explicit reorder applied\"\n- `end_time` — soonest/latest to expire first (pair with `order`)\n- `title` — alphabetical by coupon title (pair with `order`)\n\nOnly `end_time` and `title` genuinely reorder the result set — those are the two keys the coupon\nindex honours. Asking for anything else silently falls back to the default ranking.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" }, "required": false, "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "name": "order", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "default": 20, "example": 20 }, "required": false, "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "Coupons matching the filters — codes, deals and in-store offers, each with its merchant, timing window, `code_type`, affiliate tracking link and `last_used_at` (when a shopper last actually redeemed it — the freshness signal that separates a live code from a stale one). `total_is_capped: true` means the index stopped counting at its 10,000-row result window and the true total is higher than what is shown — narrow with `merchant_id` or `status` to get an exact count instead. `sort` only genuinely reorders on `end_time` or `title`; `relevance` is the default ranking, not an independent sort key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 5, "total_is_capped": false, "page": 1, "limit": 20, "total_pages": 1, "coupons": [ { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": { "id": "fr_806", "name": "Nike", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "active_coupon_count": 9 } } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/coupon-count": { "get": { "tags": [ "Coupons" ], "operationId": "/coupon-count", "description": "Exact coupon match count for a set of filters, with no result payload.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Merchant id.** Optional — omit to count coupons across every merchant in the market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nGet one from `/merchants`, `/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`.\nAn id from a different market simply matches nothing — ids are market-scoped.", "example": "" }, "required": false, "description": "**Merchant id.** Optional — omit to count coupons across every merchant in the market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nGet one from `/merchants`, `/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`.\nAn id from a different market simply matches nothing — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict by lifecycle state.** Optional — unset counts both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`; the platform never deletes an expired coupon, so this is a genuine\n historical archive, not a rolling window that quietly drops old rows\n\nThe cheapest way to check whether a market-wide count is hitting the 10,000-row cap: narrow with\nthis filter (or `merchant_id`) and watch `total_is_capped` flip to `false`.", "enum": [ "active", "expired" ], "example": "" }, "required": false, "description": "**Restrict by lifecycle state.** Optional — unset counts both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`; the platform never deletes an expired coupon, so this is a genuine\n historical archive, not a rolling window that quietly drops old rows\n\nThe cheapest way to check whether a market-wide count is hitting the 10,000-row cap: narrow with\nthis filter (or `merchant_id`) and watch `total_is_capped` flip to `false`.", "name": "status", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only count coupons published on the public site.** Optional — unset counts both.\n\nA coupon can exist in the index before or after its public run — an unpublished row is a real record,\nnot noise, so leave this unset for an audit count and set it `true` for a count that matches what\nshoppers actually see on the storefront.\n\n- `true` — live on the storefront right now\n- `false` — present in the index but not shown publicly", "example": "" }, "required": false, "description": "**Only count coupons published on the public site.** Optional — unset counts both.\n\nA coupon can exist in the index before or after its public run — an unpublished row is a real record,\nnot noise, so leave this unset for an audit count and set it `true` for a count that matches what\nshoppers actually see on the storefront.\n\n- `true` — live on the storefront right now\n- `false` — present in the index but not shown publicly", "name": "published", "in": "query" } ], "responses": { "200": { "description": "A count-only lookup for the same filters `/coupons` accepts, without paying for the row payload. `total_is_capped: true` means the index stopped counting at its 10,000-row result window and the true total is higher — narrow with `merchant_id` or `status` until it flips to `false` to get an exact figure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 5, "total_is_capped": false } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchant-coupons": { "get": { "tags": [ "Coupons" ], "operationId": "/merchant-coupons", "description": "One merchant's full coupon archive — live codes and the expired back catalogue.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "example": "fr_806" }, "required": true, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict by lifecycle state.** Optional — unset returns both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`, kept forever in the archive\n\nThis is a genuine historical archive, while the storefront shows only the active subset.", "enum": [ "active", "expired" ], "example": "" }, "required": false, "description": "**Restrict by lifecycle state.** Optional — unset returns both live and historical coupons.\n\n- `active` — has not passed its `ends_at` and is currently redeemable\n- `expired` — past `ends_at`, kept forever in the archive\n\nThis is a genuine historical archive, while the storefront shows only the active subset.", "name": "status", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only coupons published on the public site.** Optional — unset returns both.\n\nA coupon can exist in the archive before or after its public run — an unpublished row is a real\nrecord, not noise, so leave this unset for a full audit and set it `true` to match what shoppers\nactually see on the storefront.\n\n- `true` — live on the storefront right now\n- `false` — present in the archive but not shown publicly", "example": "" }, "required": false, "description": "**Only coupons published on the public site.** Optional — unset returns both.\n\nA coupon can exist in the archive before or after its public run — an unpublished row is a real\nrecord, not noise, so leave this unset for a full audit and set it `true` to match what shoppers\nactually see on the storefront.\n\n- `true` — live on the storefront right now\n- `false` — present in the archive but not shown publicly", "name": "published", "in": "query" }, { "schema": { "type": "string", "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own default ranking; there is no separate relevance score behind\n it, so this really means \"no explicit reorder applied\"\n- `end_time` — soonest/latest to expire first (pair with `order`)\n- `title` — alphabetical by coupon title (pair with `order`)\n\nOnly `end_time` and `title` genuinely reorder the result set — those are the two keys the coupon\nindex honours.", "enum": [ "relevance", "end_time", "title" ], "default": "relevance", "example": "relevance" }, "required": false, "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the platform's own default ranking; there is no separate relevance score behind\n it, so this really means \"no explicit reorder applied\"\n- `end_time` — soonest/latest to expire first (pair with `order`)\n- `title` — alphabetical by coupon title (pair with `order`)\n\nOnly `end_time` and `title` genuinely reorder the result set — those are the two keys the coupon\nindex honours.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" }, "required": false, "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "name": "order", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "default": 20, "example": 20 }, "required": false, "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "One merchant's complete coupon archive — every code, deal and in-store offer it has ever run, not just what is live today. Pass `status=expired` for the historical record, which is published nowhere else because the storefront only ever renders the active handful. Every row carries `last_used_at` — when a shopper last actually redeemed it, which separates a live code from a stale one. Use `/merchant-details` when you also need the merchant card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 2315, "total_is_capped": false, "page": 1, "limit": 20, "total_pages": 116, "coupons": [ { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": { "id": "fr_806", "name": "Nike", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "active_coupon_count": 9 } } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/top-coupons": { "get": { "tags": [ "Coupons" ], "operationId": "/top-coupons", "description": "The editorially-selected best coupon for each of several merchants, in one call.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Merchants to fetch the platform's top coupon for, in one call.** Required — 1 to 50 ids.\n\nThis is a batch lookup: pass every merchant id you care about and get back one editorially-selected\nbest coupon per merchant, together, instead of paging `/merchant-coupons` once per shop and picking\nthe best row yourself. `coupons` is the platform's own curated pick — the same one it would surface\nas the headline offer on that merchant's own landing page — not simply the highest discount or the\nnewest row.\n\n- `fr_806` — Nike alone\n- `fr_806,fr_97` — Nike and adidas, one call\n\nA merchant with no live coupon is simply omitted from the response rather than erroring the whole\nbatch. Ids are market-scoped — one from another market matches nothing. An empty result cannot\ndistinguish an unknown id from a merchant with no selected coupon; use `/merchant-details` if needed. Comma-separated.", "example": "fr_806,fr_97" }, "required": true, "description": "**Merchants to fetch the platform's top coupon for, in one call.** Required — 1 to 50 ids.\n\nThis is a batch lookup: pass every merchant id you care about and get back one editorially-selected\nbest coupon per merchant, together, instead of paging `/merchant-coupons` once per shop and picking\nthe best row yourself. `coupons` is the platform's own curated pick — the same one it would surface\nas the headline offer on that merchant's own landing page — not simply the highest discount or the\nnewest row.\n\n- `fr_806` — Nike alone\n- `fr_806,fr_97` — Nike and adidas, one call\n\nA merchant with no live coupon is simply omitted from the response rather than erroring the whole\nbatch. Ids are market-scoped — one from another market matches nothing. An empty result cannot\ndistinguish an unknown id from a merchant with no selected coupon; use `/merchant-details` if needed. Comma-separated.", "name": "merchant_ids", "in": "query" } ], "responses": { "200": { "description": "The platform's own editorially-selected best coupon for each merchant, batched across many merchants in a single call — the same curated pick that heads each merchant landing page, not simply the highest discount or the newest row. Send at most 50 ids. `requested_merchant_ids` echoes the ids asked for; a missing coupon can mean either an unknown id or a merchant with no editorially selected top coupon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "requested_merchant_ids": [ "fr_806", "fr_97" ], "count": 2, "coupons": [ { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": { "id": "fr_806", "name": "Nike", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "active_coupon_count": 9 } } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/coupon-lookup": { "get": { "tags": [ "Coupons" ], "operationId": "/coupon-lookup", "description": "Re-read one coupon (or a batch) by id — the \"is this code still live?\" call.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Coupon ids to re-read, in one call.** Required — at least one id.\n\nThis is the direct-lookup door to a coupon you already hold. Everywhere else in the API the\ncoupon feed is reached through its filters — by merchant, by category, by expiry window — so a\nstored id could be listed but never fetched back on its own. Pass it here and you get that exact\nrow again, in full.\n\nThe point is re-validation. A coupon saved yesterday may already be dead, and the returned row\nanswers that outright: `is_expired` and `ends_at` say whether the offer has run out,\n`is_published` says whether it is still shown to shoppers, and `last_used_at` records the most\nrecent time a shopper actually redeemed it — the strongest freshness signal available, since a\ncode that worked minutes ago is far likelier to still work than one untouched for months.\n\n- `021bd00a-7591-4e01-b6a7-e75f76088032` — one coupon (a live France code)\n- `,,` — a whole saved wallet re-checked in a single call\n\nEvery coupon-returning endpoint echoes these ids as `id`, so collect them from `/coupons`,\n`/merchant-coupons` or `/top-coupons` and store them alongside whatever you show your users.\n\nRe-checking a saved wallet is a batch job, and a batch of ids is a single billable call instead of\none per coupon. Within a batch, an id that no longer resolves is simply left out of `coupons`,\nso compare `count` against `requested_coupon_ids` to see which of your saved codes have dropped\nout of the catalogue. A single id that does not resolve returns a 404 instead.\n\nIds are market-scoped: an id belonging to another national storefront is not found, so send the\n`market` the coupon was originally read from. Comma-separated.", "example": "021bd00a-7591-4e01-b6a7-e75f76088032" }, "required": true, "description": "**Coupon ids to re-read, in one call.** Required — at least one id.\n\nThis is the direct-lookup door to a coupon you already hold. Everywhere else in the API the\ncoupon feed is reached through its filters — by merchant, by category, by expiry window — so a\nstored id could be listed but never fetched back on its own. Pass it here and you get that exact\nrow again, in full.\n\nThe point is re-validation. A coupon saved yesterday may already be dead, and the returned row\nanswers that outright: `is_expired` and `ends_at` say whether the offer has run out,\n`is_published` says whether it is still shown to shoppers, and `last_used_at` records the most\nrecent time a shopper actually redeemed it — the strongest freshness signal available, since a\ncode that worked minutes ago is far likelier to still work than one untouched for months.\n\n- `021bd00a-7591-4e01-b6a7-e75f76088032` — one coupon (a live France code)\n- `,,` — a whole saved wallet re-checked in a single call\n\nEvery coupon-returning endpoint echoes these ids as `id`, so collect them from `/coupons`,\n`/merchant-coupons` or `/top-coupons` and store them alongside whatever you show your users.\n\nRe-checking a saved wallet is a batch job, and a batch of ids is a single billable call instead of\none per coupon. Within a batch, an id that no longer resolves is simply left out of `coupons`,\nso compare `count` against `requested_coupon_ids` to see which of your saved codes have dropped\nout of the catalogue. A single id that does not resolve returns a 404 instead.\n\nIds are market-scoped: an id belonging to another national storefront is not found, so send the\n`market` the coupon was originally read from. Comma-separated.", "name": "coupon_ids", "in": "query" } ], "responses": { "200": { "description": "The full coupon rows for the ids you asked for — the same shape the coupon feed returns, fetched directly by id rather than by filter. Use `is_expired`, `ends_at`, `is_published` and `last_used_at` to decide whether a stored code is still worth showing. `requested_coupon_ids` echoes what was asked for, so in a batch you can see which ids came back and which have dropped out of the catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "requested_coupon_ids": [ "021bd00a-7591-4e01-b6a7-e75f76088032" ], "count": 1, "coupons": [ { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": { "id": "fr_806", "name": "Nike", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "active_coupon_count": 9 } } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/featured-offers": { "get": { "tags": [ "Coupons" ], "operationId": "/featured-offers", "description": "The storefront's own featured-offer shortlist: promoted merchants and promoted coupons, counted and paginated.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict the shortlist to one or more category ids.** Optional — unset returns every featured\noffer in the market.\n\nIds are the UUIDs published by `/categories`. Several ids are a union (OR): an offer matching any\none of them is returned.\n\n**Use the subcategory ids, not the top-level ones.** A top-level category id returns `0` rows on\nthis index — the editorial shortlist is tagged at the finer level, so the broad heading matches\nnothing even when its children match plenty. Walk `/categories`, take the child ids underneath the\nheading you care about, and pass those. An id that matches nothing yields an empty `offers` array\nrather than an error, so an empty result is the signal to check the id level before assuming the\nmarket has no offers in that theme. Comma-separated.", "example": "" }, "required": false, "description": "**Restrict the shortlist to one or more category ids.** Optional — unset returns every featured\noffer in the market.\n\nIds are the UUIDs published by `/categories`. Several ids are a union (OR): an offer matching any\none of them is returned.\n\n**Use the subcategory ids, not the top-level ones.** A top-level category id returns `0` rows on\nthis index — the editorial shortlist is tagged at the finer level, so the broad heading matches\nnothing even when its children match plenty. Walk `/categories`, take the child ids underneath the\nheading you care about, and pass those. An id that matches nothing yields an empty `offers` array\nrather than an error, so an empty result is the signal to check the id level before assuming the\nmarket has no offers in that theme. Comma-separated.", "name": "category_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the storefront's own editorial ranking, i.e. the order a visitor would see the\n shortlist in. There is no separate relevance score behind it, so this really means \"no explicit\n reorder applied\"\n- `end_time` — by the attached offer's expiry, soonest or latest first (pair with `order`)\n- `title` — alphabetical by the attached offer's title (pair with `order`)\n\n**Sorting does more than reorder here — it changes which offer each merchant is represented by.**\nThe index holds one row per featured merchant and the platform picks the offer to attach under the\nordering you asked for, so a merchant shown as a `CASHBACK` row under `relevance` can come back as\na `VOUCHER` row carrying a real coupon under `title`. The merchant set stays the same; the row\n`type` and the attached `coupon` do not. That is why the `type` split moves with `sort`.\nAnything outside the list\nabove is rejected rather than silently falling back, so a typo can never hand you the default\nranking under another name.", "enum": [ "relevance", "end_time", "title" ], "default": "relevance", "example": "relevance" }, "required": false, "description": "**Result ordering.** Optional — default `relevance`.\n\n- `relevance` — the storefront's own editorial ranking, i.e. the order a visitor would see the\n shortlist in. There is no separate relevance score behind it, so this really means \"no explicit\n reorder applied\"\n- `end_time` — by the attached offer's expiry, soonest or latest first (pair with `order`)\n- `title` — alphabetical by the attached offer's title (pair with `order`)\n\n**Sorting does more than reorder here — it changes which offer each merchant is represented by.**\nThe index holds one row per featured merchant and the platform picks the offer to attach under the\nordering you asked for, so a merchant shown as a `CASHBACK` row under `relevance` can come back as\na `VOUCHER` row carrying a real coupon under `title`. The merchant set stays the same; the row\n`type` and the attached `coupon` do not. That is why the `type` split moves with `sort`.\nAnything outside the list\nabove is rejected rather than silently falling back, so a typo can never hand you the default\nranking under another name.", "name": "sort", "in": "query" }, { "schema": { "type": "string", "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" }, "required": false, "description": "**Sort direction.** Optional — default `asc`.\n\n- `asc` — ascending (A→Z, soonest expiry first)\n- `desc` — descending (Z→A, latest expiry first)\n\nIgnored when `sort` is `relevance`.", "name": "order", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "default": 20, "example": 20 }, "required": false, "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "The storefront's editorial shortlist of featured offers for one market — the merchants and codes the site itself is promoting, in its own ranking. Every row carries a `type` and a full merchant card: `CASHBACK` rows are featured shops with no coupon at all (`coupon` is `null`), while `VOUCHER` rows pair a featured coupon with its merchant. This is a different set from `/coupons` (every coupon in the market, whose count saturates at 10,000) and from `/promotions` (which slot a given spot renders), and it is the only one of the three that surfaces promoted merchants carrying no coupon. Paging is bounded by a 10,000-result window — `page * limit` must not exceed it, and `max_reachable_page` on every response states the last page your chosen `limit` can reach. The CASHBACK/VOUCHER split moves with `sort`, because the shortlist picks which of a merchant's offers to attach under the ordering you asked for. Treat the paginated walk, not `total`, as the authority when an exact figure matters, since the index count can exceed the rows available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 3150, "page": 1, "limit": 20, "total_pages": 158, "max_reachable_page": 158, "count": 2, "offers": [ { "type": "CASHBACK", "merchant": { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" }, "coupon": null }, { "type": "VOUCHER", "merchant": { "id": "fr_806", "market": "fr", "country": "fr", "name": "Nike", "website": "https://www.nike.com/", "logo": { "url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "url_180": "https://fr.igraal.com/images/180x/images/n/Nike_3.jpg", "url_64": "https://fr.igraal.com/images/64x/images/n/Nike_3.jpg", "path": "/images/n/Nike_3.jpg", "background_color": "#FFFFFF" }, "landing_page": { "path": "codes-promo/nike/code-promotionnel", "url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "title": "Nike", "page_type": "Rlp" }, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "network_name_source": "table", "tracking_url": "https://www.nike.com/fr/" }, "quality": { "position": 5, "grade": "A" }, "category_ids": [ "761e33c9-bf29-4a16-ae53-d71cb6027567" ], "active_coupon_count": 9, "coupons_added": { "today": 0, "this_week": 1, "this_month": 6 }, "legacy_id": "762", "is_published": true, "updated_at": "2026-06-22T09:24:36.467Z" }, "coupon": { "id": "021bd00a-7591-4e01-b6a7-e75f76088032", "merchant_id": "fr_806", "market": "fr", "country": "fr", "title": "-25% sur une sélection d'articles via ce code promo Nike", "code": "BTS26", "has_code": true, "code_type": "shared", "caption": { "primary": "25%", "secondary": "remise" }, "type": { "id": 0, "name": "Code" }, "source": { "id": 2, "name": "Self Sourced" }, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-24T23:59:59.999Z", "last_used_at": "2026-08-22T23:53:09.071Z", "usage_count": 587, "performance": { "kpi": 4.25723, "rank_cpd": 3.84472, "rank_ec": 0 }, "is_expired": false, "is_published": true, "is_editors_pick": false, "combinable_with_cashback": true, "affiliate": { "network_id": "fr_8", "network_name": "No Affiliate Network", "url": "https://www.nike.com/fr/w/basketball-vetements-3glsmz6ymx6" }, "merchant": { "id": "fr_806", "name": "Nike", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "active_coupon_count": 9 } } } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/instore-offers": { "get": { "tags": [ "In-Store" ], "operationId": "/instore-offers", "description": "Supermarket cashback offers with live redemption counters (France and Poland).", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `30`, maximum `200`.\n\nThe whole in-store catalogue for a market comfortably fits under the maximum — France runs\n~117 live offers, Poland ~56 — so `per_page=200` returns the entire live programme in one\nbillable call instead of paging through it.\n\nEx: `30` (default), `100`, `200` (maximum, whole catalogue in one call).", "default": 30, "example": 30 }, "required": false, "description": "**Results per page.** Optional — default `30`, maximum `200`.\n\nThe whole in-store catalogue for a market comfortably fits under the maximum — France runs\n~117 live offers, Poland ~56 — so `per_page=200` returns the entire live programme in one\nbillable call instead of paging through it.\n\nEx: `30` (default), `100`, `200` (maximum, whole catalogue in one call).", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to one in-store category.** Optional — unset returns every category.\n\nIds come from `/instore-reference` (`categories[].id`) and are market-specific, so look them up\nthere rather than guessing.\n\n- `19` — \"Frais\" (fresh) in France, ~6 offers\n- `32` — \"Epicerie\" (groceries) in France\n\nAn id that does not exist in this market comes back as an empty list rather than an error — a\nfilter that silently returns nothing is worth checking against `/instore-reference` before\nassuming the category is empty.", "example": "" }, "required": false, "description": "**Restrict to one in-store category.** Optional — unset returns every category.\n\nIds come from `/instore-reference` (`categories[].id`) and are market-specific, so look them up\nthere rather than guessing.\n\n- `19` — \"Frais\" (fresh) in France, ~6 offers\n- `32` — \"Epicerie\" (groceries) in France\n\nAn id that does not exist in this market comes back as an empty list rather than an error — a\nfilter that silently returns nothing is worth checking against `/instore-reference` before\nassuming the category is empty.", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "In-store cashback offers redeemable at supermarket checkouts, with live redemption counters\n(`quota.total` / `quota.used` / `quota.remaining`) on every offer. The programme runs in\nFrance (~117 live offers) and Poland (~56); Germany and Spain return an empty list with\n`programme_available: false`. Offers are chain-wide rather than per-branch, so there is no\nper-chain filter here — call `/instore-reference` or `/instore-retailers` to see which\nchains currently accept them.\n\nAn offer can also carry a `quiz` or a `video` — an engagement task worth EXTRA cashback on top\nof the headline discount, in `extra_cashback`. These are common in France (71 of 117 offers\ncarry a quiz) and rare in Poland, and nothing else on the offer reveals them, so an offer with\none is worth more than its `discount` alone suggests. Both are `null` when the offer has no\nsuch task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "page": 1, "limit": 30, "count": 1, "programme_available": true, "message": null, "offers": [ { "id": 108666, "reference": "MCQ-COQENBOX-01", "title": "Maître CoQ - Gamme CoQenBox", "subtitle": "Sur tout achat en magasin", "brand_id": 8004, "image_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/maitrecoq.png", "discount": { "type": 0, "value": "1", "level": "1" }, "expires_at": "2026-12-31T22:59:59.999Z", "is_new": false, "requires_no_barcode": true, "quota": { "total": 1000000, "used": 8914, "remaining": 991086 }, "quiz": { "id": 3029, "title": null, "extra_cashback": 0.2, "bonus": null, "image_url": null }, "video": null } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/instore-retailers": { "get": { "tags": [ "In-Store" ], "operationId": "/instore-retailers", "description": "Supermarket chains that accept in-store cashback offers.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "The plain list of supermarket chains currently on the in-store cashback programme for one\nmarket — no offers, just the chain names and logos. France runs 10 chains (LECLERC, CARREFOUR,\nINTERMARCHÉ, Coopérative U, AUCHAN, LIDL, MONOPRIX, FRANPRIX and others); Poland runs 13.\nUse `/instore-offers` for the live offers themselves, or `/instore-reference` if a category\nand brand code table is also needed in the same call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "count": 10, "message": null, "retailers": [ { "id": 42, "name": "CARREFOUR", "reference": 12, "logo_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/carrefour-logo.png", "card_image_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/carrefour-card.png" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/instore-reference": { "get": { "tags": [ "In-Store" ], "operationId": "/instore-reference", "description": "In-store categories, product brands and chains — three code tables in one call.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "Three in-store code tables in one billable call: `categories` (id, name and a short tag —\nFrance carries `19` Frais/FRESH, `32` Epicerie/GROCERIES, `25` Boissons/DRINKS, `31` \"Hygiène,\nBeauté\"/HEALTH&BEAUTY, `42` Bébé/BABY, `43` \"Vins & Alcools\"/ALCOHOL, `20` Animaux/PETS and\nmore), `brands` (id and name — Actimel, Alpro, Barilla, Bonne Maman and the rest of the\nprogramme roster), and `retailers` (the same chain list `/instore-retailers` returns). The\n`categories[].id` values are exactly what `/instore-offers?category_id=` accepts — fetch this\nendpoint first, then filter offers by the id it returns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "categories": [ { "id": "19", "name": "Frais", "tag": "FRESH" }, { "id": "32", "name": "Epicerie", "tag": "GROCERIES" }, { "id": "25", "name": "Boissons", "tag": "DRINKS" }, { "id": "31", "name": "Hygiène, Beauté", "tag": "HEALTH&BEAUTY" }, { "id": "42", "name": "Bébé", "tag": "BABY" }, { "id": "43", "name": "Vins & Alcools", "tag": "ALCOHOL" }, { "id": "20", "name": "Animaux", "tag": "PETS" } ], "brands": [ { "id": "1004", "name": "Actimel" }, { "id": "1011", "name": "Alpro" }, { "id": "1023", "name": "Barilla" }, { "id": "1037", "name": "Bonne Maman" } ], "retailers": [ { "id": 42, "name": "CARREFOUR", "reference": 12, "logo_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/carrefour-logo.png", "card_image_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/carrefour-card.png" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/instore-spotlights": { "get": { "tags": [ "In-Store" ], "operationId": "/instore-spotlights", "description": "Merchandised banner slots currently running on the in-store programme.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "The merchandised banner slots currently running on the in-store cashback programme for one\nmarket — the promotional placements a shopper sees above the offer list, not the offers\nthemselves. Web and mobile placements are merged into a single list and told apart by\n`surface` (`web` or `mobile`); `precedence` is the display order within a surface, and\n`destination_offer_id` links a banner back to the specific `/instore-offers` row it promotes\nwhen it promotes one in particular.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "count": 1, "spotlights": [ { "id": "4471", "surface": "web", "name": "Maître CoQ - Bandeau accueil", "image_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto/https://static.igraal.com/instore/spotlights/maitrecoq-banner.png", "brand_id": "8004", "category_id": "19", "precedence": 3, "starts_at": "2026-08-01T22:00:00Z", "ends_at": "2026-08-31T21:59:59.999Z", "destination_url": "https://fr.igraal.com/en-magasin/maitrecoq", "tracking_suffix": "utm_source=instore_spotlight", "alt_text": "Maître CoQ - Gamme CoQenBox en magasin", "destination_offer_id": 108666 } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/printable-offers": { "get": { "tags": [ "Printable Coupons" ], "operationId": "/printable-offers", "description": "Printable grocery coupons, filterable by brand and category (France).", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `30`, maximum `200`.\n\nThe printable-coupon programme is small — France runs ~23 live offers — so `per_page=200`\nreturns every live coupon in one billable call instead of paging through the list.\n\nEx: `30` (default), `100`, `200` (maximum, whole catalogue in one call).", "default": 30, "example": 30 }, "required": false, "description": "**Results per page.** Optional — default `30`, maximum `200`.\n\nThe printable-coupon programme is small — France runs ~23 live offers — so `per_page=200`\nreturns every live coupon in one billable call instead of paging through the list.\n\nEx: `30` (default), `100`, `200` (maximum, whole catalogue in one call).", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to one printable-coupon brand.** Optional — unset returns every brand.\n\nIds come from `/printable-reference` (`brands[].id`) and are market-specific — fetch that\nendpoint first rather than guessing an id.\n\n- `180` — Barilla (France, 1 live coupon)\n- `287` — Andros (France, 1 live coupon)\n\nThe printable programme is small and rotates, so a brand's id is only meaningful while it has a\nlive coupon — re-read `/printable-reference` rather than caching an id across weeks. An id that\ndoes not exist in this market returns an empty list rather than an error.", "example": "" }, "required": false, "description": "**Restrict to one printable-coupon brand.** Optional — unset returns every brand.\n\nIds come from `/printable-reference` (`brands[].id`) and are market-specific — fetch that\nendpoint first rather than guessing an id.\n\n- `180` — Barilla (France, 1 live coupon)\n- `287` — Andros (France, 1 live coupon)\n\nThe printable programme is small and rotates, so a brand's id is only meaningful while it has a\nlive coupon — re-read `/printable-reference` rather than caching an id across weeks. An id that\ndoes not exist in this market returns an empty list rather than an error.", "name": "brand_id", "in": "query" }, { "schema": { "type": "string", "description": "**Restrict to one printable-coupon category.** Optional — unset returns every category.\n\nIds come from `/printable-reference` (`categories[].id`) and are market-specific — fetch that\nendpoint first rather than guessing an id.\n\n- `47` — \"Crèmerie\" (dairy) — 5 live coupons in France\n- `32` — \"Epicerie\" (groceries) — 5\n- `25` — \"Boissons\" (drinks) — 4\n\nNote these are NOT the same id space as `/instore-offers` — the in-store categories are a\ndifferent tree, so an id that works there can return nothing here.\n\nCombine with `brand_id` to narrow to one brand within one category; an id that does not exist\nreturns an empty list rather than an error.", "example": "" }, "required": false, "description": "**Restrict to one printable-coupon category.** Optional — unset returns every category.\n\nIds come from `/printable-reference` (`categories[].id`) and are market-specific — fetch that\nendpoint first rather than guessing an id.\n\n- `47` — \"Crèmerie\" (dairy) — 5 live coupons in France\n- `32` — \"Epicerie\" (groceries) — 5\n- `25` — \"Boissons\" (drinks) — 4\n\nNote these are NOT the same id space as `/instore-offers` — the in-store categories are a\ndifferent tree, so an id that works there can return nothing here.\n\nCombine with `brand_id` to narrow to one brand within one category; an id that does not exist\nreturns an empty list rather than an error.", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "Printable, at-home coupons — the shopper prints the voucher and redeems it in store rather\nthan scanning a code at checkout. This is a France-only programme (~23 live offers); the\nother three markets return an empty list with `programme_available: false`. Filter by\n`brand_id` and/or `category_id` — both id sets come from `/printable-reference`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "page": 1, "limit": 30, "count": 1, "programme_available": true, "message": null, "offers": [ { "id": "105915", "reference": "103738_1_P", "title": "Barilla - Al Bronzo", "subtitle": "Sur l'achat d'un produit Barilla Al Bronzo 500g au choix dans la gamme.", "discount_value": "0.3", "image_url": "https://res.cloudinary.com/couponnetwork/image/fetch/f_auto,q_auto,w_400/https://res.cloudinary.com/couponnetwork/image/upload/w_400,h_400/v1764860405/dam_assets/53806FAF3BAB059D95DDC6D40E70D7E9.jpg", "is_best": false, "brand_id": "180", "is_alcohol": false, "starts_at": "2025-12-10", "ends_at": "2027-10-20", "expired_at": null, "is_new": false, "required_units": 1, "display_order": null, "category_ids": [ 32 ] } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/printable-reference": { "get": { "tags": [ "Printable Coupons" ], "operationId": "/printable-reference", "description": "Printable-coupon categories and product brands.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "The two code tables that drive `/printable-offers` filtering, in one billable call:\n`categories` (id, name and a short tag) and `brands` (id and name — Actimel, Alpro, Barilla,\nBonne Maman and the rest of the printable-coupon roster). Fetch this endpoint first, then\npass the ids it returns as `/printable-offers?brand_id=` and `?category_id=`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "categories": [ { "id": "19", "name": "Frais", "tag": "FRESH" }, { "id": "32", "name": "Epicerie", "tag": "GROCERIES" }, { "id": "25", "name": "Boissons", "tag": "DRINKS" } ], "brands": [ { "id": "1004", "name": "Actimel" }, { "id": "1011", "name": "Alpro" }, { "id": "1023", "name": "Barilla" }, { "id": "1037", "name": "Bonne Maman" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/gift-cards": { "get": { "tags": [ "Gift Cards" ], "operationId": "/gift-cards", "description": "Discounted gift cards with their cashback percentage, denominations and redemption terms.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "description": "**Fetch one merchant's gift card directly.** Optional — omit to browse the whole catalogue\ninstead.\n\nTwo id shapes are valid — a UUID for merchants added through the current system, and a short\n`_` code for older ones (`fr_806` — Nike).\n\nPassing this fetches that merchant's single card in one call, so the response always carries\n`total: 1`, `page: 1` and `total_pages: 1` no matter what `page`/`limit` you send (`limit` is\nechoed back unchanged). The envelope keys are identical either way — the endpoint never returns\ntwo different shapes. A merchant with no gift card on this market returns a 404 rather than an\nempty list. Leave it unset and use `query` instead to search the catalogue by merchant name.", "example": "" }, "required": false, "description": "**Fetch one merchant's gift card directly.** Optional — omit to browse the whole catalogue\ninstead.\n\nTwo id shapes are valid — a UUID for merchants added through the current system, and a short\n`_` code for older ones (`fr_806` — Nike).\n\nPassing this fetches that merchant's single card in one call, so the response always carries\n`total: 1`, `page: 1` and `total_pages: 1` no matter what `page`/`limit` you send (`limit` is\nechoed back unchanged). The envelope keys are identical either way — the endpoint never returns\ntwo different shapes. A merchant with no gift card on this market returns a 404 rather than an\nempty list. Leave it unset and use `query` instead to search the catalogue by merchant name.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Free-text filter by merchant name.** Optional — unset returns the full catalogue.\n\nMatches on the merchant name embedded in the card, case-insensitively and on substrings — `ikea`\nfinds every IKEA-branded card in the market.\n\nIgnored when `merchant_id` is also set, since that parameter already pins the result to one\nmerchant. An unmatched term returns an empty list with `total: 0`, not an error.", "example": "" }, "required": false, "description": "**Free-text filter by merchant name.** Optional — unset returns the full catalogue.\n\nMatches on the merchant name embedded in the card, case-insensitively and on substrings — `ikea`\nfinds every IKEA-branded card in the market.\n\nIgnored when `merchant_id` is also set, since that parameter already pins the result to one\nmerchant. An unmatched term returns an empty list with `total: 0`, not an error.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "default": 1, "example": 1 }, "required": false, "description": "**Page number, 1-indexed.** Optional — default `1`.\n\nCombine with `limit` to walk a result set: page 2 at `limit=20` returns results 21-40. The\nresponse echoes `page`, `limit`, `total` and `total_pages`, so you know when to stop.\n\nEx: `1` (first page), `2`, `10`. Range `1`-`5000`. Paging is 1-based — there is no page zero.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "default": 20, "example": 20 }, "required": false, "description": "**Results per page.** Optional — default `20`, maximum `200`.\n\nLarger pages are one billable call each, so a bulk export is cheapest at `limit=200`. Use\n`limit=1` when you only want the `total` for a set of filters.\n\nEx: `20` (default), `50`, `200` (maximum).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "Gift cards on sale through the cashback platform, catalogue size by market: France ~155,\nGermany ~62, Spain ~27, Poland ~22. Each card carries `cashback_percent` (what the buyer\nearns on the purchase), `face_values.fixed[]` (the denominations on sale, each with a live\n`quantity_available`) or `face_values.custom` (a min/max range for a free-amount card),\n`redeemable_online` / `redeemable_in_store`, `combinable_with_cashback`, a `redeem_url` and\nthe full `conditions` text. Pass `merchant_id` to fetch one merchant's card directly (404\nif that merchant has none), or `query` to filter the catalogue by merchant name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "total": 155, "page": 1, "limit": 20, "total_pages": 8, "gift_cards": [ { "id": "288", "merchant_id": "fr_806", "merchant_name": "nike", "cashback_percent": 4.5, "company_cashback_percent": 8, "provider": { "id": 3, "name": "CashStar", "merchant_id": "nike-fr", "merchant_name": "nike" }, "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "uses_merchant_logo": true, "redeem_url": "https://fr.igraal.com/gift-cards/redirect?merchantName=nike", "is_active": true, "combinable_with_cashback": false, "redeemable_online": true, "redeemable_in_store": true, "expires_at": null, "expiration_conditions": "Valable 3 ans à compter de la date d'achat.", "conditions": "Carte cadeau utilisable en ligne et en magasin, non remboursable et non échangeable contre des espèces.", "face_values": { "fixed": [ { "gift_card_id": "288", "face_value": 25, "value": "25", "quantity_available": 4200, "expires_at": null }, { "gift_card_id": "288", "face_value": 50, "value": "50", "quantity_available": 3100, "expires_at": null } ], "custom": null } } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/merchant-keywords": { "get": { "tags": [ "Intelligence" ], "operationId": "/merchant-keywords", "description": "Per-merchant search keywords with live SERP position and monthly search volume.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "example": "fr_806" }, "required": true, "description": "**Merchant id.** Required. The stable identifier of a shop inside one market.\n\nTwo shapes exist and both are valid — a UUID for merchants added through the current system, and\na short `_` code for older ones:\n\n- `fr_806` — Nike (France)\n- `fr_97` — adidas (France)\n- `75a637fc-d3a4-4224-898c-9a3d12e465f3` — Hbada (France)\n\nEvery merchant-returning endpoint echoes one as `id`. Get one from `/merchants`,\n`/merchant-autocomplete`, or by passing a shop URL to `/merchant-by-url`. An id from a different\nmarket returns a 404 — ids are market-scoped.", "name": "merchant_id", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "**The SEO keyword set behind one merchant** — every search term the platform tracks for a shop,\neach with its live SERP `position` and monthly Google `search_volume`. This is the dataset an SEO\nor share-of-search tool would charge for, folded into a merchant lookup at no extra cost.\n\nUse `position` and `search_volume` together to compare the search terms associated with a\nmerchant. Both values can change as the search results and monthly volume change.\n\n`is_tracked` marks the keywords the platform actively monitors position for, as opposed to ones\nsurfaced only historically. A merchant with no keyword coverage returns an empty `keywords` list\nand `count: 0` — that is a normal answer, not an error, and simply means this shop is not part of\nthe tracked keyword programme yet.\n\nAn unknown merchant id also yields `count: 0`. Check the merchant separately with\n`/merchant-details` when you need to distinguish an unknown id from no keyword coverage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "merchant_id": "fr_806", "count": 5, "total_search_volume": 76830, "keywords": [ { "keyword": "Code promo Nike", "position": 1, "search_volume": 74000, "is_tracked": true, "country": "fr", "merchant_id": "fr_806" }, { "keyword": "Code Nike", "position": 2, "search_volume": 1900, "is_tracked": true, "country": "fr", "merchant_id": "fr_806" }, { "keyword": "Code réduction Nike", "position": 3, "search_volume": 590, "is_tracked": true, "country": "fr", "merchant_id": "fr_806" }, { "keyword": "Bon de réduction Nike", "position": 4, "search_volume": 260, "is_tracked": false, "country": "fr", "merchant_id": "fr_806" }, { "keyword": "Coupon Nike", "position": 5, "search_volume": 70, "is_tracked": false, "country": "fr", "merchant_id": "fr_806" } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/promotions": { "get": { "tags": [ "Intelligence" ], "operationId": "/promotions", "description": "Editorial and sponsored placements currently running, by slot — including paid merchant promotion.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" }, { "schema": { "type": "string", "enum": [ "STICKY_BANNER", "STAGE_BANNER", "PROMOTION_GRID", "OFFER_CARDS_UNLOGGED", "OFFER_CARDS_LOGGED", "SELECTION_OF_THE_DAY", "SPONSORED_MERCHANT", "PROMOTIONAL_SIDEBAR", "CASHBACK_BOOST", "CAMPAIGN_HIGHLIGHT", "MARKETING_THEME", "MARKETING_CARD", "PROMOTION_BANNER", "OFFER_GRID" ], "description": "**Select one placement slot.** Required — each request reads one complete slot.\n\nEach value is a distinct spot on the storefront's home page or merchant pages:\n\n- `STICKY_BANNER` — banner pinned while scrolling\n- `STAGE_BANNER` — rotating hero banner\n- `PROMOTION_GRID` — home-page promo tiles\n- `OFFER_CARDS_UNLOGGED` and `OFFER_CARDS_LOGGED` — visitor/member offer cards\n- `SELECTION_OF_THE_DAY` — daily curated pick\n- `SPONSORED_MERCHANT` — paid merchant placement\n- `PROMOTIONAL_SIDEBAR` — sidebar rail\n- `CASHBACK_BOOST` — temporary cashback-rate increases\n- `CAMPAIGN_HIGHLIGHT` — seasonal or brand campaign\n- `MARKETING_THEME` and `MARKETING_CARD` — themed collection/card\n- `PROMOTION_BANNER` — secondary banner\n- `OFFER_GRID` — individual-offer grid\n\n`SPONSORED_MERCHANT` is the one placement\nwhere `is_sponsored: true` on the response row means the brand is paying for the spot — it is the\nonly view into which merchants are buying promotion, and on which days, since spots rotate daily.\n\nAn unrecognised value is rejected with a `400` listing every accepted placement, rather than silently\nreturning nothing.", "example": "STAGE_BANNER" }, "required": true, "description": "**Select one placement slot.** Required — each request reads one complete slot.\n\nEach value is a distinct spot on the storefront's home page or merchant pages:\n\n- `STICKY_BANNER` — banner pinned while scrolling\n- `STAGE_BANNER` — rotating hero banner\n- `PROMOTION_GRID` — home-page promo tiles\n- `OFFER_CARDS_UNLOGGED` and `OFFER_CARDS_LOGGED` — visitor/member offer cards\n- `SELECTION_OF_THE_DAY` — daily curated pick\n- `SPONSORED_MERCHANT` — paid merchant placement\n- `PROMOTIONAL_SIDEBAR` — sidebar rail\n- `CASHBACK_BOOST` — temporary cashback-rate increases\n- `CAMPAIGN_HIGHLIGHT` — seasonal or brand campaign\n- `MARKETING_THEME` and `MARKETING_CARD` — themed collection/card\n- `PROMOTION_BANNER` — secondary banner\n- `OFFER_GRID` — individual-offer grid\n\n`SPONSORED_MERCHANT` is the one placement\nwhere `is_sponsored: true` on the response row means the brand is paying for the spot — it is the\nonly view into which merchants are buying promotion, and on which days, since spots rotate daily.\n\nAn unrecognised value is rejected with a `400` listing every accepted placement, rather than silently\nreturning nothing.", "name": "placement", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only spots currently live.** Optional — default `true`.\n\nPlacements are scheduled: a spot has a `starts_at`/`ends_at` window and this flag filters on\nit. Pass `false` to also see spots that are scheduled but not yet live, or that already\nended, which is useful for auditing a promotion calendar rather than rendering the live page.\n\n- `true` (default) — only what a visitor would see right now\n- `false` — every spot in the window, live or not\n\nBe aware that `false` is a far heavier query — a single slot can hold hundreds of scheduled spots\n(France `STICKY_BANNER`: 256 against 1 live). The busiest slots sometimes exceed the storefront's\nown time budget; retry or use `active_only=true`.", "example": "" }, "required": false, "description": "**Only spots currently live.** Optional — default `true`.\n\nPlacements are scheduled: a spot has a `starts_at`/`ends_at` window and this flag filters on\nit. Pass `false` to also see spots that are scheduled but not yet live, or that already\nended, which is useful for auditing a promotion calendar rather than rendering the live page.\n\n- `true` (default) — only what a visitor would see right now\n- `false` — every spot in the window, live or not\n\nBe aware that `false` is a far heavier query — a single slot can hold hundreds of scheduled spots\n(France `STICKY_BANNER`: 256 against 1 live). The busiest slots sometimes exceed the storefront's\nown time budget; retry or use `active_only=true`.", "name": "active_only", "in": "query" }, { "schema": { "type": "integer", "description": "**Maximum spots to return.** Optional — default `50`, maximum `200`.\n\nThe response always echoes the true `total` count of matching spots even when `limit` cuts the\n`promotions` array short, so a caller can tell a slot was truncated rather than genuinely empty.\n\nEx: `50` (default), `200` (maximum).", "default": 50, "example": 50 }, "required": false, "description": "**Maximum spots to return.** Optional — default `50`, maximum `200`.\n\nThe response always echoes the true `total` count of matching spots even when `limit` cuts the\n`promotions` array short, so a caller can tell a slot was truncated rather than genuinely empty.\n\nEx: `50` (default), `200` (maximum).", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "**The live promotional widgets** — every banner, sidebar spot, grid tile and sponsored card the\nstorefront is currently placing, by slot. This is the merchandising layer sitting on top of the\ncatalogue: it tells you not just what offers exist, but which ones the platform is actively\nfeaturing, where, and — for `SPONSORED_MERCHANT` — which brand paid for the spot.\n\n`target_category` is the category a spot points at, and its ids are the same ones `/categories`\npublishes and `category_ids` filters on — so a spot can be taken straight to the merchants in\nits theme. It is one of the fields a `SPONSORED_MERCHANT` row carries, since those rows\nhave no `title`, `description`, `image` or `link`; use their merchant card instead.\nThe separate `category` key is a merchandising label that is currently null on every spot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "placement": "SPONSORED_MERCHANT", "active_only": true, "total": 34, "limit": 50, "promotions": [ { "id": "019fb1a2-6e3d-7c11-9a4f-3d8e5c2b1f90", "placement": "SPONSORED_MERCHANT", "parent_placement": null, "title": "Nike — Cashback boosté ce week-end", "description": "Jusqu'à 8% de cashback sur toute la boutique", "is_sponsored": true, "display_order": 1, "group": 0, "promotion_type": "MERCHANT", "page_position": "home", "source": "commercial", "starts_at": "2026-08-22T22:00:00Z", "ends_at": "2026-08-24T21:59:59.999Z", "created_at": "2026-08-20T10:12:03.000Z", "updated_at": "2026-08-21T08:00:00.000Z", "link_url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "image": { "url": "https://fr.igraal.com/images/images/n/nike-sponsored.jpg", "alt": "Nike" }, "category": null, "target_category": { "id": "ab1d8821-0ef9-4fa3-8b67-d846c344f3fd", "name": "Travel", "key": "travel", "parent_id": null, "page_path": null, "page_url": null, "created_at": "2025-08-05T10:48:55.360Z", "updated_at": "2025-08-05T10:48:55.360Z" }, "merchant": { "id": "fr_806", "name": "Nike", "website": "https://www.nike.com/", "logo_url": "https://fr.igraal.com/images/images/n/Nike_3.jpg", "logo_background_color": "#FFFFFF", "landing_page_url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "quality_grade": "A", "active_coupon_count": 9 }, "target_merchant": null, "merchant_landing_page_url": "https://fr.igraal.com/codes-promo/nike/code-promotionnel", "offer": { "type": "CASHBACK", "coupon": null, "cashback": { "campaign_id": "019fa8e5-0473-77b6-b8e1-d322e042e7b8", "rate": { "value": 8, "type": "PERCENTAGE" }, "previous_rate": { "value": 4, "type": "PERCENTAGE" } } }, "tags": null } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/affiliate-networks": { "get": { "tags": [ "Intelligence" ], "operationId": "/affiliate-networks", "description": "The affiliate-network directory that resolves every network id to a network name.", "parameters": [ { "schema": { "type": "string", "description": "**Restrict the directory to one market.** Optional — unset returns all 558 networks across\nevery market.\n\nOne of `fr`, `de`, `es`, `pl` — the same market codes used everywhere else on this API. The\ndirectory is not evenly split: France carries 227 networks, Germany 220, Spain 92 and Poland\njust 19, roughly tracking each market's merchant catalogue size.\n\nEx: `fr` (227 networks), `pl` (19 networks).", "example": "" }, "required": false, "description": "**Restrict the directory to one market.** Optional — unset returns all 558 networks across\nevery market.\n\nOne of `fr`, `de`, `es`, `pl` — the same market codes used everywhere else on this API. The\ndirectory is not evenly split: France carries 227 networks, Germany 220, Spain 92 and Poland\njust 19, roughly tracking each market's merchant catalogue size.\n\nEx: `fr` (227 networks), `pl` (19 networks).", "name": "country", "in": "query" }, { "schema": { "type": "string", "description": "**Free-text search on the network name.** Optional. Case-insensitive substring match.\n\nUse it to resolve a name you already know to its id, or to check whether a given network is\ncovered at all before trusting a merchant's `affiliate.network_name`.\n\n- `awin` — Awin (and any network whose name contains \"awin\")\n- `tradedoubler` — TradeDoubler\n\nAn unmatched term returns an empty list, not an error.", "example": "" }, "required": false, "description": "**Free-text search on the network name.** Optional. Case-insensitive substring match.\n\nUse it to resolve a name you already know to its id, or to check whether a given network is\ncovered at all before trusting a merchant's `affiliate.network_name`.\n\n- `awin` — Awin (and any network whose name contains \"awin\")\n- `tradedoubler` — TradeDoubler\n\nAn unmatched term returns an empty list, not an error.", "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "enum": [ "json", "csv" ], "default": "json", "example": "json" }, "required": false, "description": "**Response serialisation.** Optional — default `json`.\n\n- `json` — the standard `{success, data}` envelope.\n- `csv` — one row per result, `text/csv`, nested objects flattened into dotted columns\n (`logo.url`, `cashback.rate.value`). Ready to open in a spreadsheet or load into a feed\n pipeline; the pagination metadata is omitted because a CSV has no envelope.\n\nEx: `json`, `csv`.", "name": "format", "in": "query" } ], "responses": { "200": { "description": "**The affiliate-network directory** — 558 networks across the four markets (France 227, Germany\n220, Spain 92, Poland 19) — that resolves the `affiliate.network_id` every merchant and coupon\ncarries into a real network name: Awin, Impact Radius, WebGains, Effiliation, TradeDoubler, CJ,\nAffilae, Admitad, NetAffiliation and more.\n\nNot every live id has an entry here — a small share of ids in production are not in the\ndirectory. Those merchants still get a usable `affiliate.network_name`, derived instead from\nthe host of their tracking link; the merchant object's `affiliate.network_name_source` tells\nyou which route produced the name — `table` (resolved from this directory) or `tracking_host`\n(derived from the link itself).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "count": 4, "networks": [ { "id": "fr_25", "name": "Awin", "country": "fr" }, { "id": "fr_21", "name": "Impact Radius", "country": "fr" }, { "id": "fr_13", "name": "WebGains", "country": "fr" }, { "id": "fr_5", "name": "Effiliation", "country": "fr" } ] } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/markets": { "get": { "tags": [ "Reference" ], "operationId": "/markets", "description": "Static directory of the four storefronts and the programmes each one runs.", "responses": { "200": { "description": "**The discovery endpoint — call this first.** The four national storefronts this API reads,\neach with the details you need to pick the right one and to interpret it correctly: the\n`market` code every other endpoint takes, the `brand` shown to shoppers (Germany runs under\n`Shoop`, not `iGraal`), the `locale`, the `page_prefix` its landing-page URLs are built from,\nand `max_sales_tax_percent`, the VAT ceiling used when a cashback rate is computed net of tax.\n\nThis is a static directory with no live totals. For current merchant counts, call\n`/merchants?limit=1` for each market and apply `published=true` or `has_cashback=true`\nwhen those subsets are needed.\n\n`has_instore_programme` and `has_printable_coupons` mark two features that are not universal:\nin-store cashback exists in France and Poland, and printable paper coupons only in France.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "count": 4, "markets": [ { "market": "fr", "id_client": "a444a51901d85f3d9eb84ada70cef7f3", "country": "fr", "brand": "iGraal", "label": "iGraal France", "site": "https://fr.igraal.com", "image_cdn": "https://fr.igraal.com/images", "locale": "fr-FR", "page_prefix": "codes-promo", "max_sales_tax_percent": 20, "has_instore_programme": true, "has_printable_coupons": true }, { "market": "de", "id_client": "c235ee8b371f4e8b8e392330ea359875", "country": "de", "brand": "Shoop", "label": "Shoop Germany", "site": "https://de.igraal.com", "image_cdn": "https://de.igraal.com/images", "locale": "de-DE", "page_prefix": "gutschein", "max_sales_tax_percent": 19, "has_instore_programme": false, "has_printable_coupons": false }, { "market": "es", "id_client": "ff880fb8a999463b9a7c952eeac263ca", "country": "es", "brand": "iGraal", "label": "iGraal Spain", "site": "https://es.igraal.com", "image_cdn": "https://es.igraal.com/images", "locale": "es-ES", "page_prefix": "codigos-promocionales", "max_sales_tax_percent": 21, "has_instore_programme": false, "has_printable_coupons": false }, { "market": "pl", "id_client": "f9f4557825c74791ac01dc5c72ef7aef", "country": "pl", "brand": "iGraal", "label": "iGraal Poland", "site": "https://igraal.pl", "image_cdn": "https://igraal.pl/images", "locale": "pl-PL", "page_prefix": "wszystkie-sklepy", "max_sales_tax_percent": 23, "has_instore_programme": true, "has_printable_coupons": false } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/categories": { "get": { "tags": [ "Reference" ], "operationId": "/categories", "description": "The merchant category tree, with the ids the category filter takes.", "parameters": [ { "schema": { "type": "string", "minLength": 2, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "example": "fr" }, "required": true, "description": "**Which national storefront to read.** Required.\n\nOne catalogue per country, each with its own merchants, cashback rates, coupons and category tree.\nThe market is chosen by this parameter alone — never by where the request comes from — so every\nmarket is reachable from anywhere.\n\n- `fr` — iGraal France\n- `de` — Shoop Germany\n- `pl` — iGraal Poland\n- `es` — iGraal Spain\n\nLong forms and the German brand name are accepted too: `france`, `germany`, `shoop`, `poland`,\n`spain`. Call `/markets` for the live per-market merchant census.", "name": "market", "in": "query" } ], "responses": { "200": { "description": "**The market's full category tree**, two levels deep: 17 top-level categories per market —\namong them Broadband & Phone Contracts, Car & Motorcycle, Culture & Leisure, Electronics,\nFamily & Kids, Fashion & Accessories, Finance & Insurance, Gaming, Garden & Do It Yourself,\nGroceries and Health & Beauty — each carrying its own `subcategories` array.\n\nThe `id` on any node is exactly what `/merchants?category_ids=` accepts, so\nthis is the endpoint to walk before building a category filter or a browse menu — pass a\ntop-level id to scope broadly, or a subcategory id to narrow to one shelf.\n\nCategory **names are in English in every market** — the same taxonomy is reused across France,\nGermany, Spain and Poland — while `page_path`/`page_url` are the market's own localised landing\npage (`mode-accessoires` in France, `gutschein/...` in Germany), so a name and its URL slug will\nnot visually match outside the French market.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "market": "fr", "count": 17, "categories": [ { "id": "031f9caf-03b3-4a8f-b52a-7a476abe70c4", "name": "Fashion & Accessories", "key": "fashion-accessories", "parent_id": null, "page_path": "mode-accessoires", "page_url": "https://fr.igraal.com/mode-accessoires", "created_at": "2023-01-11T09:00:00.000Z", "updated_at": "2026-05-02T14:30:00.000Z", "subcategories": [ { "id": "9c1e2a4b-7f3d-4e6a-8b1c-2d5f6a7b8c9d", "name": "Women's Fashion", "key": "womens-fashion", "parent_id": "031f9caf-03b3-4a8f-b52a-7a476abe70c4", "page_path": "mode-accessoires/mode-femme", "page_url": "https://fr.igraal.com/mode-accessoires/mode-femme", "created_at": "2023-01-11T09:00:00.000Z", "updated_at": "2026-05-02T14:30:00.000Z", "subcategories": [] } ] }, { "id": "75384eb3-272f-495f-bba8-d33158d1a106", "name": "Electronics", "key": "electronics", "parent_id": null, "page_path": "high-tech", "page_url": "https://fr.igraal.com/high-tech", "created_at": "2023-01-11T09:00:00.000Z", "updated_at": "2026-04-18T11:05:00.000Z", "subcategories": [] } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } }, "/reference": { "get": { "tags": [ "Reference" ], "operationId": "/reference", "description": "Every accepted filter value and response vocabulary in one call.", "responses": { "200": { "description": "**Every accepted value, in one call.** The lookup table for every enum and filter vocabulary\nused across this API, so a client can validate or render a value locally instead of hard-coding\nit or guessing:\n\n- `coupon_types` / `coupon_sources` / `merchant_qualities` — the live, resolved id → name\n tables behind `type.id`, `source.id` and `quality.position` on merchant and coupon rows\n- `cashback_rate_types` — the three shapes a cashback `rate.type` can take, each with a plain\n description of what the number means\n- `coupon_statuses` — the two lifecycle values `/coupons` accepts for its status filter\n- `merchant_sorts` / `coupon_sorts` — the accepted `sort` values for `/merchants` and\n `/coupons` respectively\n- `placements` — every value `/promotions?placement=` accepts\n- `markets` — the same market registry as `/markets`, without the live merchant census\n- `static_coupon_types` / `static_coupon_sources` / `static_merchant_qualities` — fallback\n copies of the first three tables, always populated even on a call that skips the live table\n lookup, so the vocabulary is never empty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalSuccessResponseSchema" }, "example": { "success": true, "data": { "coupon_types": [ { "id": 0, "name": "Code" }, { "id": 5, "name": "Unique Code" }, { "id": 8, "name": "Deal" } ], "coupon_sources": [ { "id": 2, "name": "Self Sourced" }, { "id": 4, "name": "Network Feed" } ], "merchant_qualities": [ { "id": 1, "name": "AAA" }, { "id": 5, "name": "A" }, { "id": 10, "name": "F" } ], "cashback_rate_types": [ { "value": "PERCENTAGE", "description": "A percentage of the order value." }, { "value": "FIXED", "description": "A fixed cash amount per qualifying action." }, { "value": "COEFFICIENT", "description": "A share of the commission the platform itself earns on the sale." } ], "coupon_statuses": [ { "value": "active", "description": "Currently redeemable." }, { "value": "expired", "description": "Past its end date — the historical archive." } ], "merchant_sorts": [ { "value": "relevance", "description": "Platform default ranking." }, { "value": "name", "description": "Alphabetical by merchant name." } ], "coupon_sorts": [ { "value": "relevance", "description": "Platform default ranking." }, { "value": "end_time", "description": "By expiry date." }, { "value": "title", "description": "Alphabetical by coupon title." } ], "placements": [ { "value": "PROMOTION_GRID" }, { "value": "PROMOTIONAL_SIDEBAR" }, { "value": "SPONSORED_MERCHANT" } ], "markets": [ { "market": "fr", "id_client": "a444a51901d85f3d9eb84ada70cef7f3", "country": "fr", "brand": "iGraal", "label": "iGraal France", "site": "https://fr.igraal.com", "image_cdn": "https://fr.igraal.com/images", "locale": "fr-FR", "page_prefix": "codes-promo", "max_sales_tax_percent": 20 } ], "static_coupon_types": [ { "id": 0, "name": "Code" }, { "id": 5, "name": "Unique Code" } ], "static_coupon_sources": [ { "id": 2, "name": "Self Sourced" } ], "static_merchant_qualities": [ { "id": 1, "name": "AAA" }, { "id": 5, "name": "A" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } }, "503": { "description": "Service busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IgraalErrorResponseSchema" } } } } } } } }, "servers": [ { "url": "https://rapid-api-tools-worker.pictureperfect.workers.dev/happy-endpoint/api/tools/igraal-api", "description": "Base URL" } ] }