{"openapi":"3.1.0","info":{"title":"Square Settlements (BYOK) API","version":"0.1.0","description":"Square Settlements (BYOK) lets an AI assistant read your own Square Settlements data through the Square Settlements API with a key you supply (production access token (personal access token from your Square application)). Read-only: 8 tools (list_payouts, get_payout, list_payout_entries, list_disputes, get_dispute, list_refunds, list_cash_drawer_shifts, get_cash_drawer_shift). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-square-settlements.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-square-settlements/docs"},"termsOfService":"https://connectorbay.com/byok-square-settlements/terms"},"servers":[{"url":"https://byok-square-settlements.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-square-settlements/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/list_payouts":{"post":{"operationId":"list_payouts","summary":"List Square payouts with status, amount, fees, type and arrival date. The bank or card destination is not returned. Amou","description":"List Square payouts with status, amount, fees, type and arrival date. The bank or card destination is not returned. Amounts are in the smallest currency unit (cents for USD). Up to 100 per page; pass the returned cursor for more. Use for \"What payouts has Square sent me recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID (from the locations list); without it Square uses the seller's main location.","title":"Location Id"},"status":{"anyOf":[{"enum":["SENT","FAILED","PAID"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts with this status.","title":"Status"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts created at or after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts 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) or ASC.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Payouts per page (1 to 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_payoutsArguments","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_payout":{"post":{"operationId":"get_payout","summary":"Get one Square payout by id with status, amount, fees, type and arrival date. The destination account is not returned. U","description":"Get one Square payout by id with status, amount, fees, type and arrival date. The destination account is not returned. Use for \"How much was Square payout po_8a3c1f and when did it arrive\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payout_id":{"description":"Square payout ID, for example po_8a3c1f.","maxLength":200,"title":"Payout Id","type":"string"}},"required":["payout_id"],"title":"get_payoutArguments","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_payout_entries":{"post":{"operationId":"list_payout_entries","summary":"List the ledger lines that make up one payout (charges, refunds, fees, adjustments) with gross, fee and net amounts and ","description":"List the ledger lines that make up one payout (charges, refunds, fees, adjustments) with gross, fee and net amounts and the related payment ids. Up to 100 per page. Use for \"Which charges and fees were included in Square payout po_8a3c1f\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payout_id":{"description":"Square payout ID, for example po_8a3c1f.","maxLength":200,"title":"Payout Id","type":"string"},"sort_order":{"anyOf":[{"enum":["DESC","ASC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Order by effective time: DESC or ASC.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Entries per page (1 to 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"}},"required":["payout_id"],"title":"list_payout_entriesArguments","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_disputes":{"post":{"operationId":"list_disputes","summary":"List card disputes (chargebacks and inquiries) with state, reason, amount, card brand, evidence due date and the dispute","description":"List card disputes (chargebacks and inquiries) with state, reason, amount, card brand, evidence due date and the disputed payment id. Use for \"Do I have any open Square disputes that need evidence\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID (from the locations list); without it Square uses the seller's main location.","title":"Location Id"},"states":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only disputes in this state, for example EVIDENCE_REQUIRED, PROCESSING, WON or LOST.","title":"States"},"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_disputesArguments","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_dispute":{"post":{"operationId":"get_dispute","summary":"Get one Square dispute by id with state, reason, amount, card brand, due date and the disputed payment id. Use for \"What","description":"Get one Square dispute by id with state, reason, amount, card brand, due date and the disputed payment id. Use for \"What is the status of Square dispute dsp_41b7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dispute_id":{"description":"Square dispute ID, for example dsp_41b7.","maxLength":200,"title":"Dispute Id","type":"string"}},"required":["dispute_id"],"title":"get_disputeArguments","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_refunds":{"post":{"operationId":"list_refunds","summary":"List payment refunds with status, amount, processing fees, the original payment and order ids and time. Up to 100 per pa","description":"List payment refunds with status, amount, processing fees, the original payment and order ids and time. Up to 100 per page. Use for \"Which Square payments were refunded this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Square location ID (from the locations list); without it Square uses the seller's main location.","title":"Location Id"},"status":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds with this status, for example COMPLETED, PENDING, REJECTED or FAILED.","title":"Status"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds created at or after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds 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) or ASC.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Refunds per page (1 to 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_refundsArguments","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_cash_drawer_shifts":{"post":{"operationId":"list_cash_drawer_shifts","summary":"List cash drawer shifts of one location with opening, expected and closing cash totals and open and close times. Staff i","description":"List cash drawer shifts of one location with opening, expected and closing cash totals and open and close times. Staff ids are not returned. Up to 1000 per page. Use for \"How did the cash drawer at my main Square location close out this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Square location ID to query.","maxLength":60,"title":"Location Id","type":"string"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only shifts opened created at or after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only shifts opened 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) or ASC.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Shifts 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":"list_cash_drawer_shiftsArguments","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_cash_drawer_shift":{"post":{"operationId":"get_cash_drawer_shift","summary":"Get one cash drawer shift with its opening, cash payment, refund, paid-in, paid-out, expected and closing totals. Staff ","description":"Get one cash drawer shift with its opening, cash payment, refund, paid-in, paid-out, expected and closing totals. Staff ids are not returned. Use for \"What were the cash totals for drawer shift shift_5d1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shift_id":{"description":"Cash drawer shift ID, for example shift_5d1.","maxLength":200,"title":"Shift Id","type":"string"},"location_id":{"description":"Square location the shift belongs to.","maxLength":60,"title":"Location Id","type":"string"}},"required":["shift_id","location_id"],"title":"get_cash_drawer_shiftArguments","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}}}}