{"openapi":"3.1.0","info":{"title":"Square (BYOK) API","version":"0.1.0","description":"Square (BYOK) lets an AI assistant read your own Square data through the Square API with a key you supply (access token (personal access token from your Square application, production)). Read-only: 10 tools (get_merchant, list_locations, get_location, search_orders, get_order, list_payments, get_payment, list_customers, list_catalog, get_inventory_counts). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-square.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-square/docs"},"termsOfService":"https://connectorbay.com/byok-square/terms"},"servers":[{"url":"https://byok-square.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-square/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_merchant":{"post":{"operationId":"get_merchant","summary":"Show the Square seller account behind the key: business name, country, currency, status and main location. Use for \"Whic","description":"Show the Square seller account behind the key: business name, country, currency, status and main location. Use for \"Which Square business is my access token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_merchantArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_locations":{"post":{"operationId":"list_locations","summary":"List the seller's Square locations with name, address, time zone, currency, status and type. Location IDs are needed by ","description":"List the seller's Square locations with name, address, time zone, currency, status and type. Location IDs are needed by the order and inventory tools. Use for \"What Square locations does my business have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_locationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_location":{"post":{"operationId":"get_location","summary":"Get one Square location's name, address, contact details, time zone, currency and status. Use for \"What are the details ","description":"Get one Square location's name, address, contact details, time zone, currency and status. Use for \"What are the details of my Square location L123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Square location ID, or 'main' for the seller's main location.","maxLength":200,"title":"Location Id","type":"string"}},"required":["location_id"],"title":"get_locationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_orders":{"post":{"operationId":"search_orders","summary":"List orders for one location, newest first or oldest first, with state, totals, customer and timestamps. Amounts are in ","description":"List orders for one location, newest first or oldest first, with state, totals, customer and timestamps. Amounts are in the smallest currency unit (cents for USD). Returns up to 1000 per page; pass the returned cursor for more. Use for \"What were the latest orders at my Square location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Square location ID to search (from list_locations).","maxLength":60,"title":"Location Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Orders per page (1 to 1000; provider default 500).","title":"Limit"},"sort_order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Order by creation time: DESC (newest first) or ASC (oldest first).","title":"Sort Order"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["location_id"],"title":"search_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one Square order with its state, line items, totals, tenders and timestamps. Amounts are in the smallest currency un","description":"Get one Square order with its state, line items, totals, tenders and timestamps. Amounts are in the smallest currency unit (cents for USD). Use for \"Show the line items of Square order abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Square order ID.","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payments":{"post":{"operationId":"list_payments","summary":"List Square payments (newest first by default) with amount, status, card brand details, receipt link and order. Amounts ","description":"List Square payments (newest first by default) with amount, status, card brand details, receipt link and order. Amounts are in the smallest currency unit (cents for USD). Up to 100 per page; pass the returned cursor for more. Use for \"Show my latest Square payments\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments created at or after this RFC 3339 time, for example 2026-09-01T00:00:00Z (provider default: one year ago).","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments created before this RFC 3339 time.","title":"End Time"},"sort_order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Order by creation time: DESC (newest first, default) or ASC.","title":"Sort Order"},"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID (from list_locations). Without it Square uses the seller's main location.","title":"Location Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Payments per page (1 to 100; provider default 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"title":"list_paymentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_payment":{"post":{"operationId":"get_payment","summary":"Get one Square payment with status, amounts, refunds total, source type, receipt number and link. Use for \"Show the deta","description":"Get one Square payment with status, amounts, refunds total, source type, receipt number and link. Use for \"Show the details of Square payment pay123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"description":"Square payment ID.","maxLength":200,"title":"Payment Id","type":"string"}},"required":["payment_id"],"title":"get_paymentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_customers":{"post":{"operationId":"list_customers","summary":"List customer profiles of the seller's Customer Directory with name, email, phone and creation date. Up to 100 per page;","description":"List customer profiles of the seller's Customer Directory with name, email, phone and creation date. Up to 100 per page; pass the returned cursor for more. Use for \"Who are my newest Square customers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort_field":{"anyOf":[{"enum":["DEFAULT","CREATED_AT"],"type":"string"},{"type":"null"}],"default":"CREATED_AT","description":"Sort by DEFAULT or CREATED_AT.","title":"Sort Field"},"sort_order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"ASC or DESC (provider default ASC).","title":"Sort Order"},"count":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the total number of customers.","title":"Count"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Customers per page (1 to 100; provider default 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"title":"list_customersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_catalog":{"post":{"operationId":"list_catalog","summary":"List Square catalog objects of chosen types (items, variations with SKU and price, categories, taxes, discounts). Prices","description":"List Square catalog objects of chosen types (items, variations with SKU and price, categories, taxes, discounts). Prices are in the smallest currency unit. Pass the returned cursor for more. Use for \"List the items in my Square catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"types":{"description":"Comma-separated catalog object types, for example 'ITEM', 'ITEM_VARIATION', 'CATEGORY', 'DISCOUNT' or 'TAX'.","maxLength":120,"title":"Types","type":"string"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["types"],"title":"list_catalogArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_inventory_counts":{"post":{"operationId":"get_inventory_counts","summary":"Get current inventory counts (quantity and state such as IN_STOCK) for catalog item variations at one location, newest c","description":"Get current inventory counts (quantity and state such as IN_STOCK) for catalog item variations at one location, newest calculation first. Up to 1000 per page. Use for \"How much stock do I have at my Square location\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Square location ID (from list_locations).","maxLength":60,"title":"Location Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Counts per page (1 to 1000).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor returned as 'cursor' by the previous call; leave empty for the first page.","title":"Cursor"}},"required":["location_id"],"title":"get_inventory_countsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}