{
  "openapi": "3.0.1",
  "info": {
    "title": "Flipp Flyer Deals Scraper — Weekly Flyers & Prices, CA + US",
    "description": "Weekly flyer deals from 2,500+ Canadian and US retailers by postal code or ZIP: search every flyer for a product, or pull every item in every flyer near you. Prices, sale text, unit prices ($/kg), multi-buys, discounts, categories, in-store and online deals, and week-over-week price changes.",
    "version": "0.1",
    "x-build-id": "CbtJo69RswXmbap40"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/yugenox~flipp-flyer-deals-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-yugenox-flipp-flyer-deals-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/yugenox~flipp-flyer-deals-scraper/runs": {
      "post": {
        "operationId": "runs-sync-yugenox-flipp-flyer-deals-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/yugenox~flipp-flyer-deals-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-yugenox-flipp-flyer-deals-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "mode": {
            "title": "📋 What to scrape",
            "enum": [
              "search",
              "flyers",
              "flyerIds"
            ],
            "type": "string",
            "description": "Search: find a product across every flyer, in-store sale and online deal near each postal code. Full flyers: every item in every flyer near each postal code, optionally narrowed by store, flyer category or keywords. Specific flyers: every item in the flyers you list.",
            "default": "search"
          },
          "postalCodes": {
            "title": "📍 Postal codes / ZIP codes",
            "type": "array",
            "description": "Full Canadian postal codes (e.g. M5V 2T6) or US ZIP codes (e.g. 10001). Deals are what's available near each one. Flyers shared by several codes are only read (and charged) once.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "🔍 Search terms",
            "type": "array",
            "description": "Products to look for, e.g. milk, chicken breast, tv. In Search mode each term is its own search. In Full-flyer mode they filter the flyer items (a row matches when every word of a term starts a word in the item name, brand or description).",
            "items": {
              "type": "string"
            }
          },
          "flyerIds": {
            "title": "🆔 Flyer ids or links",
            "type": "array",
            "description": "For 'Specific flyers' mode: flyer ids (e.g. 8148102) or flipp.com flyer links. Flyer ids are in the output of any run (flyerId).",
            "items": {
              "type": "string"
            }
          },
          "regionPresets": {
            "title": "🗺️ Region presets",
            "type": "array",
            "description": "Add one postal code per major city: 46 Canadian cities (every province and territory — about 1,200 distinct flyers) and/or 50 US metros (about 800 flyers). Combine with Full flyers mode for a near-national flyer dataset. Neighbouring cities share most flyers; they are deduplicated.",
            "items": {
              "type": "string",
              "enum": [
                "ca-major-cities",
                "us-major-cities"
              ],
              "enumTitles": [
                "🇨🇦 Canada — 46 major cities",
                "🇺🇸 USA — 50 major metros"
              ]
            }
          },
          "maxItems": {
            "title": "🔢 Max deals",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of deals across the whole run. Leave empty for no limit (a full flyer sweep of one big-city postal code is ~15,000–30,000 items)."
          },
          "merchants": {
            "title": "🏪 Stores",
            "type": "array",
            "description": "Only these retailers, by name (e.g. No Frills, Walmart, Shoppers Drug Mart, Canadian Tire, Target) or Flipp store id (merchantId in the output). Leave empty for all stores.",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "title": "🏷️ Categories",
            "type": "array",
            "description": "Only deals in these categories. Matches the flyer category (Groceries, Pharmacy, Home & Garden, Electronics, General Merchandise, Pets, Sporting Goods, Automotive, Fashion, Baby & Kids, Office, Specialty, Restaurants) and, in Search mode, the product category too (e.g. Beverages, Meat). Partial names work.",
            "items": {
              "type": "string"
            }
          },
          "itemTypes": {
            "title": "🧾 Deal types (Search mode)",
            "type": "array",
            "description": "Flyer: deals printed in weekly flyers. In-store: a chain's own sale price at the nearest branch (with store address, SKU and product link). Online: online-store deals (with SKU, rating and reviews). Full-flyer modes always return flyer deals.",
            "items": {
              "type": "string",
              "enum": [
                "flyer",
                "store",
                "online"
              ],
              "enumTitles": [
                "📰 Flyer deals",
                "🏬 In-store prices",
                "🛒 Online deals"
              ]
            },
            "default": [
              "flyer",
              "store"
            ]
          },
          "onlyValidNow": {
            "title": "📅 Only deals valid today",
            "type": "boolean",
            "description": "Skip deals from flyers that haven't started yet (next week's flyers are often published a day or two early) or have ended.",
            "default": false
          },
          "sortBy": {
            "title": "↕️ Sort (Search mode)",
            "enum": [
              "relevancy",
              "price_low_to_high",
              "price_high_to_low"
            ],
            "type": "string",
            "description": "Order of search results. Every row also gets a priceRank (1 = cheapest in that search; $/kg for weight-priced items).",
            "default": "relevancy"
          },
          "includeItemDetails": {
            "title": "➕ Item details",
            "type": "boolean",
            "description": "Add each flyer item's description (size, varieties), SKU, the retailer's product link, sale text, pre/post price text, in-store-only flag, disclaimer and ratings. In Full-flyer mode this is also what fills the sale text and unit (/lb, ea.) columns. Billed as a separate small add-on per enriched item.",
            "default": false
          },
          "trackChanges": {
            "title": "📈 Track week-over-week changes",
            "type": "boolean",
            "description": "Compare with the previous run of the same input: each row gets changeType (new / price_drop / price_up / unchanged) and previousPrice, and the CHANGES record lists deals that expired. Schedule the run weekly (flyers roll over mid-week) for a deal-alert feed.",
            "default": false
          },
          "completeCoverage": {
            "title": "🧩 Complete coverage (Search mode)",
            "type": "boolean",
            "description": "Flipp returns at most 200 results per search. When a search hits that cap, it is automatically re-run store by store so you get every matching deal (e.g. 197 → 700+ for \"chicken\" in Toronto). Turn off for a quick top-200 sample.",
            "default": true
          },
          "dedupeAcrossPostalCodes": {
            "title": "♻️ Deduplicate across postal codes",
            "type": "boolean",
            "description": "The same flyer usually covers many postal codes. On (default): each deal is returned once, tagged with the first postal code it was found for. Off: one row per deal per postal code.",
            "default": true
          },
          "language": {
            "title": "🗣️ Language (Canada)",
            "enum": [
              "en",
              "fr"
            ],
            "type": "string",
            "description": "French returns French item names and flyers where the retailer publishes them (Quebec and bilingual chains). US ZIP codes are always English.",
            "default": "en"
          },
          "maxItemsPerPostalCode": {
            "title": "🔢 Max deals per postal code",
            "minimum": 1,
            "type": "integer",
            "description": "Cap for each postal code. Leave empty for no per-postal-code limit."
          },
          "maxPostalCodes": {
            "title": "🔢 Max postal codes",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Safety cap on how many postal codes (including region presets) one run covers.",
            "default": 100
          },
          "maxConcurrency": {
            "title": "⚡ Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many requests run at once. The default is fast and gentle; higher is rarely needed.",
            "default": 8
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Apify datacenter proxy works well and is the default. Slow or blocked IPs are rotated automatically, with a residential fallback.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}