# Square Online Menu Scraper (`automation-lab/square-online-menu-scraper`) Actor 🍽️ Export public Square Online menus with exact prices, categories, locations, images, availability, variations, SKUs, and modifier choices. - **URL**: https://apify.com/automation-lab/square-online-menu-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Square Online Menu Scraper Extract structured restaurant menus from public Square Online sites. Square Online Menu Scraper turns `*.square.site` ordering pages into clean records containing menu items, categories, exact prices, images, locations, availability, variations, SKUs, and modifiers. It reads Square's public catalog data directly, so you get source-native IDs and price subunits instead of OCR guesses or brittle page text. ### What does Square Online Menu Scraper do? Give the Actor one or more public Square Online merchant URLs. It discovers the merchant's current catalog configuration, finds every public store location, paginates the menu, and saves one product-location record per dataset row. Use it to: - 🍽️ export complete Square restaurant menus; - 💵 monitor prices and sale state; - 🚫 track sold-out or unavailable products; - 🔄 migrate catalogs into another ordering system; - 🧩 capture variation and modifier choices; - 📊 build restaurant and food-tech datasets. ### Why use a source-specific Square menu scraper? General menu scrapers must handle arbitrary HTML, PDFs, and images. That flexibility often means OCR, AI interpretation, missing identifiers, or uncertain prices. This Actor focuses on Square Online's public structured catalog. The result includes exact product IDs, location IDs, integer price subunits, SKU variations, inventory flags, and modifier choices that are useful in production workflows. ### Who is it for? #### Restaurant-data vendors Collect normalized menu snapshots for analytics, enrichment, and delivery applications. #### Catalog migration teams Map source product IDs, categories, variations, and modifiers into a new POS or storefront. #### Food-tech developers Feed structured Square menu records into search, recommendation, ordering, or comparison products. #### Market researchers Compare product mix, categories, prices, and availability across public merchants. #### Price and availability monitors Schedule repeat runs and compare stable IDs and timestamps between snapshots. ### What data can you extract? | Field group | Examples | | --- | --- | | Merchant | name, merchant ID, site URL, currency | | Location | location ID, display name, address | | Product | product ID, name, description, type, URL | | Categories | category IDs and category names | | Prices | low/high numeric, formatted, and subunit values | | Availability | sold out, fulfillable, inventory enabled, total | | Media | primary image and all image URLs | | Variations | SKU ID, name, SKU, exact price, sold-out state | | Modifiers | groups, min/max selections, choices, add-on prices | | Freshness | Square update timestamp and scrape timestamp | ### Input The main input is `startUrls`. Each URL must be a public Square Online host ending in `.square.site`. ```json { "startUrls": [ { "url": "https://alpha-coffee-107652.square.site/" } ], "maxItems": 10, "includeDetails": true, "includeUnavailable": true } ```` #### Input fields | Field | Type | Default | Description | | --- | --- | --- | --- | | `startUrls` | array | required | Public Square Online merchant URLs | | `maxItems` | integer | `10` | Combined result limit across sites and locations | | `includeDetails` | boolean | `true` | Fetch variations, SKUs, and modifiers | | `includeUnavailable` | boolean | `true` | Keep sold-out and unavailable products | | `locationIds` | string array | all | Restrict extraction to known Square locations | ### How to scrape a Square Online menu 1. Open the public Square Online ordering site. 2. Copy its `https://...square.site/` URL. 3. Add the URL under **Square Online merchant URLs**. 4. Keep `maxItems` small for your first run. 5. Enable details when you need sizes or modifier choices. 6. Click **Start**. 7. Export the dataset as JSON, CSV, Excel, XML, or another supported format. ### Scrape one Square location Merchants may expose more than one public pickup location. To target one location, pass its Square location ID: ```json { "startUrls": [ { "url": "https://alpha-coffee-107652.square.site/" } ], "locationIds": ["L7C77T70MZ0Y8"], "maxItems": 100 } ``` The Actor fails clearly when none of the requested IDs exists on the site. ### Output example ```json { "merchantName": "Alpha Coffee", "merchantId": "MLJG3BW9G97XD", "merchantUrl": "https://alpha-coffee-107652.square.site/", "currency": "USD", "locationId": "L7C77T70MZ0Y8", "locationName": "Alpha Coffee Cafe", "productId": "2MIV2LR5OPDTJC5RKLSZWBG3", "productName": "Dirty Chai Frappe", "categoryNames": ["Frappes"], "priceLow": 6.75, "priceHigh": 7.75, "priceLowSubunits": 675, "priceHighSubunits": 775, "soldOut": false, "onSale": true, "variations": [], "modifiers": [], "productUrl": "https://alpha-coffee-107652.square.site/product/...", "scrapedAt": "2026-07-16T00:00:00.000Z" } ``` Optional properties are omitted when Square does not expose them. Arrays are always present, which makes downstream processing predictable. ### Variations, SKUs, and modifiers Set `includeDetails` to `true` to request product detail and SKU routes. Variations can include: - variation or SKU ID; - display name such as size; - merchant SKU when present; - numeric, formatted, and subunit prices; - sold-out and inventory state. Modifier groups include visible choices, add-on prices, selection limits, defaults, and sold-out state where Square exposes them. Set details to `false` for faster lightweight item and price snapshots. ### Price and availability monitoring Use Apify Schedules to run the Actor hourly, daily, or weekly. Keep `includeUnavailable` enabled so disappeared availability is visible as data rather than silently filtered. Recommended comparison keys are: - `merchantId`; - `locationId`; - `productId`; - variation `id`; - modifier choice `id`. Compare price subunits rather than formatted strings when calculating changes. ### How much does it cost to scrape Square Online menus? The Actor uses pay-per-event pricing. A small one-time start event covers initialization, and each saved menu item is charged as an item event. Account tiers receive decreasing per-item rates. Your exact maximum charge is visible in Apify Console before and during the run. Use `maxItems` to set a deterministic extraction ceiling. Because the Actor uses public HTTP catalog routes rather than a full browser or OCR pipeline, runs are designed to remain lightweight. ### API usage with JavaScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/square-online-menu-scraper').call({ startUrls: [{ url: 'https://alpha-coffee-107652.square.site/' }], maxItems: 50, includeDetails: true, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/square-online-menu-scraper').call(run_input={ 'startUrls': [{'url': 'https://alpha-coffee-107652.square.site/'}], 'maxItems': 50, 'includeDetails': True, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` ### API usage with cURL ```bash curl -X POST \ 'https://api.apify.com/v2/acts/automation-lab~square-online-menu-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "startUrls": [{"url": "https://alpha-coffee-107652.square.site/"}], "maxItems": 50, "includeDetails": true }' ``` Fetch results from the run's default dataset after it succeeds. ### MCP integration Use the Actor through Apify's MCP server from Claude Code, Claude Desktop, Cursor, or VS Code. #### Claude Code setup ```bash claude mcp add --transport http apify 'https://mcp.apify.com/?tools=automation-lab/square-online-menu-scraper' ``` #### Claude Desktop and Cursor setup Add this configuration under `mcpServers` in Claude Desktop or Cursor and provide your Apify token through the client authentication flow: ```json { "mcpServers": { "apify-square-menu": { "type": "http", "url": "https://mcp.apify.com/?tools=automation-lab/square-online-menu-scraper" } } } ``` #### VS Code setup Add the same HTTP MCP URL through **MCP: Add Server**, name it `apify-square-menu`, and authenticate with your Apify account. Example prompts: - “Scrape the first 50 items from this Square Online restaurant menu.” - “Return sold-out products and all variation prices for this Square site.” - “Extract this merchant's modifier choices for catalog migration.” ### Integrations #### Google Sheets and Excel Export scheduled snapshots for analysts and operations teams. #### Webhooks Trigger an ETL job when a menu run succeeds. #### Make and Zapier Send new or changed products into no-code workflows. #### Cloud storage and databases Use dataset APIs to load records into BigQuery, Snowflake, PostgreSQL, or an object store. #### AI assistants Connect through MCP and ask for category, price, or availability summaries grounded in current public catalog data. ### Tips for reliable runs - Use the merchant's public home or order-online URL. - Keep the hostname ending in `.square.site`. - Start with `maxItems: 10` to inspect the shape. - Disable details when only names, categories, and price ranges are needed. - Use location IDs to prevent intentional duplicate products across branches. - Store product and location IDs for stable comparisons. - Schedule complete snapshots at a cadence appropriate for the merchant. ### Limitations The Actor supports public `*.square.site` merchant sites. It does not log into Square Dashboard, access private seller data, place orders, or use a seller's official OAuth catalog. A merchant can remove products, disable ordering, restrict a location, or unpublish a site at any time. Square may change its public frontend or catalog API. The Actor discovers live merchant identifiers and cache versions to reduce dependence on hard-coded values, but upstream changes can still require maintenance. Category names come from the public site bootstrap; unknown category IDs remain available in `categoryIds`. ### Troubleshooting #### “Unsupported host” Provide the public Square Online URL, not a Square Dashboard, checkout, social, or custom-domain URL. #### “Bootstrap state was not found” Confirm the page opens publicly and is a current Square Online site. Try the merchant homepage instead of a deep checkout link. #### No matching locations Remove `locationIds` to list data from every public location, or verify the IDs from an earlier run. #### Fewer items than expected Increase `maxItems`, enable unavailable products, and check whether the merchant has multiple locations. #### Run fails after a Square site change Inspect the run log and report the public URL through the Actor's issue form so the extraction route can be updated. ### Is scraping Square Online legal? This Actor extracts information already exposed on public merchant pages and anonymous catalog endpoints. Scraping legality depends on your jurisdiction, purpose, data type, and contractual obligations. Do not use the Actor to collect private information, bypass access controls, overload a site, or violate applicable laws and terms. You are responsible for your input URLs, retention policy, and downstream use. When in doubt, consult qualified legal counsel. ### FAQ #### Does it require a Square login or API key? No. It reads the public menu surface visible to ordinary visitors. #### Does it use OCR or AI to guess prices? No. Prices and IDs come from Square's structured public catalog response. #### Can it scrape several merchants in one run? Yes. Add several Square Online URLs and set a combined `maxItems` limit. #### Can it return sold-out products? Yes. `includeUnavailable` defaults to true. #### Can it return modifiers and size variations? Yes. Keep `includeDetails` enabled. #### Why can the same product appear more than once? Rows are product-location records. The same product may intentionally be offered at several merchant locations. #### Can it scrape custom domains powered by Square? The current product contract accepts `*.square.site` URLs so scope is explicit and validation fails closed. ### Related scrapers Combine this Actor with other Automation Lab actors when you need a broader restaurant-data workflow: - [Grubhub Restaurant Menus Scraper](https://apify.com/automation-lab/grubhub-restaurant-menus-scraper) for Grubhub-specific restaurant and menu data. - [Google Maps Scraper](https://apify.com/automation-lab/google-maps-scraper) for restaurant discovery and business profiles. Use this Actor when your source of truth is a public Square Online merchant catalog. ### Support If a valid public Square Online site stops working, open an issue from the Actor page. Include: - the public merchant URL; - whether the page opens in a normal browser; - the expected product or location; - a run ID when available. Do not include private Square credentials or customer data. ### Start extracting Square menus Add a public `*.square.site` URL, keep the first run small, and inspect the structured dataset. Then scale the result limit, target locations, schedule snapshots, or connect the Actor to your existing data pipeline. # Actor input Schema ## `startUrls` (type: `array`): Public Square Online home or ordering page URLs. ## `maxItems` (type: `integer`): Maximum number of product records across all URLs and locations. ## `includeDetails` (type: `boolean`): Fetch product detail endpoints to include sizes, SKUs, prices, and modifier choices. ## `includeUnavailable` (type: `boolean`): Keep unavailable products in the dataset for monitoring and catalog migration. ## `locationIds` (type: `array`): Optional location IDs such as L7C77T70MZ0Y8. Leave empty to scrape every public location. ## Actor input object example ```json { "startUrls": [ { "url": "https://alpha-coffee-107652.square.site/" } ], "maxItems": 10, "includeDetails": true, "includeUnavailable": true } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://alpha-coffee-107652.square.site/" } ], "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/square-online-menu-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://alpha-coffee-107652.square.site/" }], "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/square-online-menu-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ { "url": "https://alpha-coffee-107652.square.site/" } ], "maxItems": 10 }' | apify call automation-lab/square-online-menu-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/square-online-menu-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Square Online Menu Scraper", "description": "🍽️ Export public Square Online menus with exact prices, categories, locations, images, availability, variations, SKUs, and modifier choices.", "version": "0.1", "x-build-id": "8Ohx7yZI9ZTqzVTZx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~square-online-menu-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-square-online-menu-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/automation-lab~square-online-menu-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-square-online-menu-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/automation-lab~square-online-menu-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-square-online-menu-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", "required": [ "startUrls" ], "properties": { "startUrls": { "title": "Square Online merchant URLs", "type": "array", "description": "Public Square Online home or ordering page URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxItems": { "title": "Maximum menu items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of product records across all URLs and locations.", "default": 10 }, "includeDetails": { "title": "Include variations and modifiers", "type": "boolean", "description": "Fetch product detail endpoints to include sizes, SKUs, prices, and modifier choices.", "default": true }, "includeUnavailable": { "title": "Include sold-out and unavailable items", "type": "boolean", "description": "Keep unavailable products in the dataset for monitoring and catalog migration.", "default": true }, "locationIds": { "title": "Only these Square location IDs", "type": "array", "description": "Optional location IDs such as L7C77T70MZ0Y8. Leave empty to scrape every public location.", "items": { "type": "string" } } } }, "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 } } }, "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 } } } } } } } } } } ```