{"openapi":"3.1.0","info":{"title":"Clover Merchant Setup (BYOK) API","version":"0.1.0","description":"Clover Merchant Setup (BYOK) lets an AI assistant read your own Clover Merchant Setup data through the Clover Merchant Setup API with a key you supply (Clover merchant API token (North America production)). Read-only: 10 tools (get_merchant, get_merchant_settings, list_opening_hours, list_order_types, get_order_type, list_system_order_types, list_devices, get_device, list_tip_suggestions,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clover-merchant-config.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clover-merchant-config/docs"},"termsOfService":"https://connectorbay.com/byok-clover-merchant-config/terms"},"servers":[{"url":"https://byok-clover-merchant-config.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clover-merchant-config/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":"Get the Clover business profile: name and street address. Owner and staff details are left out. Use for \"Which Clover bu","description":"Get the Clover business profile: name and street address. Owner and staff details are left out. Use for \"Which Clover business does my token belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"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/get_merchant_settings":{"post":{"operationId":"get_merchant_settings","summary":"Get the merchant's register settings: currency, time zone, locale, tipping, VAT, stock tracking and order title options.","description":"Get the merchant's register settings: currency, time zone, locale, tipping, VAT, stock tracking and order title options. Banking and support fields are left out. Use for \"What are my Clover register settings, like time zone and tipping\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"title":"get_merchant_settingsArguments","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_opening_hours":{"post":{"operationId":"list_opening_hours","summary":"List the merchant's named sets of opening hours with the open and close times for each weekday. Use for \"What opening ho","description":"List the merchant's named sets of opening hours with the open and close times for each weekday. Use for \"What opening hours are configured in my Clover account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"title":"list_opening_hoursArguments","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_order_types":{"post":{"operationId":"list_order_types","summary":"List the order types (dine in, take out, delivery and custom ones) with fee, minimum and maximum order amounts, average ","description":"List the order types (dine in, take out, delivery and custom ones) with fee, minimum and maximum order amounts, average preparation time and availability hours. Use for \"What order types does my Clover register have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"},"expand":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: hours, attributes, categories.","title":"Expand"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Results per page (1 to 1000; Clover default 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"required":["merchant_id"],"title":"list_order_typesArguments","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_type":{"post":{"operationId":"get_order_type","summary":"Get one order type with fee, order amount limits, preparation time and availability hours. Use for \"Show Clover order ty","description":"Get one order type with fee, order amount limits, preparation time and availability hours. Use for \"Show Clover order type OT1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"},"order_type_id":{"description":"Clover order type ID (from list_order_types).","maxLength":30,"title":"Order Type Id","type":"string"},"expand":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: hours, attributes, categories.","title":"Expand"}},"required":["merchant_id","order_type_id"],"title":"get_order_typeArguments","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_system_order_types":{"post":{"operationId":"list_system_order_types","summary":"List Clover's built-in order types and whether each applies to quick service, full service or retail. Use for \"Which bui","description":"List Clover's built-in order types and whether each applies to quick service, full service or retail. Use for \"Which built-in order types does Clover offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"title":"list_system_order_typesArguments","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_devices":{"post":{"operationId":"list_devices","summary":"List the Clover devices provisioned to the merchant with name, model, product and offline-payment setting. Serial number","description":"List the Clover devices provisioned to the merchant with name, model, product and offline-payment setting. Serial numbers, IMEI and certificates are left out. Use for \"Which Clover devices are set up at my business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Results per page (1 to 1000; Clover default 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"required":["merchant_id"],"title":"list_devicesArguments","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_device":{"post":{"operationId":"get_device","summary":"Get one Clover device: name, model, product, order prefix and offline-payment setting. Use for \"Show Clover device DEV1\"","description":"Get one Clover device: name, model, product, order prefix and offline-payment setting. Use for \"Show Clover device DEV1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"},"device_id":{"description":"Clover device ID (from list_devices).","maxLength":40,"title":"Device Id","type":"string"}},"required":["merchant_id","device_id"],"title":"get_deviceArguments","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_tip_suggestions":{"post":{"operationId":"list_tip_suggestions","summary":"List the tip suggestions shown at checkout with name, percentage or flat amount and whether enabled. Use for \"What tip s","description":"List the tip suggestions shown at checkout with name, percentage or flat amount and whether enabled. Use for \"What tip suggestions are set up in Clover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Results per page (1 to 1000; Clover default 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0).","title":"Offset"}},"required":["merchant_id"],"title":"list_tip_suggestionsArguments","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_default_service_charge":{"post":{"operationId":"get_default_service_charge","summary":"Get the merchant's default service charge: name, percentage and whether it is applied automatically. Use for \"Does my Cl","description":"Get the merchant's default service charge: name, percentage and whether it is applied automatically. Use for \"Does my Clover account add a default service charge\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Clover merchant ID (13 characters, for example 'RCTSTAVI0TEST'), shown in the Clover dashboard URL and in the API token page.","maxLength":30,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"title":"get_default_service_chargeArguments","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}}}}