{"openapi":"3.1.0","info":{"title":"Clover Inventory (BYOK) API","version":"0.1.0","description":"Clover Inventory (BYOK) lets an AI assistant read your own Clover Inventory data through the Clover Inventory API with a key you supply (Clover merchant API token (North America production)). Read-only: 10 tools (list_items, get_item, list_categories, list_modifier_groups, list_tax_rates, list_discounts, list_item_groups, list_tags, list_service_charges, list_item_attributes). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clover-inventory.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clover-inventory/docs"},"termsOfService":"https://connectorbay.com/byok-clover-inventory/terms"},"servers":[{"url":"https://byok-clover-inventory.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clover-inventory/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_items":{"post":{"operationId":"list_items","summary":"List inventory items with name, SKU, code, price, cost, price type, availability and stock count. Amounts are integers i","description":"List inventory items with name, SKU, code, price, cost, price type, availability and stock count. Amounts are integers in the smallest currency unit. Up to 1000 per page; use offset to page. Use for \"What items are on my Clover menu\".","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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"expand":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: tags, categories, taxRates, modifierGroups, itemStock, options.","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_itemsArguments","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_item":{"post":{"operationId":"get_item","summary":"Get one inventory item with price, cost, SKU, visibility and, when expanded, its categories, tax rates, modifier groups,","description":"Get one inventory item with price, cost, SKU, visibility and, when expanded, its categories, tax rates, modifier groups, tags and stock. Use for \"Show Clover item ABC123 with its categories and tax rates\".","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"},"item_id":{"description":"Clover item ID (from list_items).","maxLength":30,"title":"Item Id","type":"string"},"expand":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: tags, categories, taxRates, modifierGroups, itemStock, options.","title":"Expand"}},"required":["merchant_id","item_id"],"title":"get_itemArguments","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_categories":{"post":{"operationId":"list_categories","summary":"List item categories (how items are grouped on the register) with name, sort order and colour. Use for \"What categories ","description":"List item categories (how items are grouped on the register) with name, sort order and colour. Use for \"What categories does my Clover menu 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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"expand":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Set to 'items' to include the item IDs in each category.","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_categoriesArguments","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_modifier_groups":{"post":{"operationId":"list_modifier_groups","summary":"List modifier groups (for example sizes or extras) with the minimum and maximum picks and, when expanded, the modifiers ","description":"List modifier groups (for example sizes or extras) with the minimum and maximum picks and, when expanded, the modifiers with their prices. Use for \"What modifier groups are set up in my Clover menu\".","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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"expand":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: modifiers, items.","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_modifier_groupsArguments","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_tax_rates":{"post":{"operationId":"list_tax_rates","summary":"List the tax rates of the merchant with name, rate, flat tax amount and whether it is the default. Use for \"What tax rat","description":"List the tax rates of the merchant with name, rate, flat tax amount and whether it is the default. Use for \"What tax rates 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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"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_tax_ratesArguments","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_discounts":{"post":{"operationId":"list_discounts","summary":"List the preset discounts the merchant can apply, with name and either a percentage or an amount. Use for \"What discount","description":"List the preset discounts the merchant can apply, with name and either a percentage or an amount. Use for \"What discounts 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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"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_discountsArguments","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_item_groups":{"post":{"operationId":"list_item_groups","summary":"List item groups (items with variants such as sizes or colours) with their name. Use for \"Which Clover item groups with ","description":"List item groups (items with variants such as sizes or colours) with their name. Use for \"Which Clover item groups with variants do I 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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"expand":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: items, attributes.","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_item_groupsArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List item tags (labels used for grouping and reporting) with name and whether they show in reports. Use for \"What item t","description":"List item tags (labels used for grouping and reporting) with name and whether they show in reports. Use for \"What item tags exist in my Clover inventory\".","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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"expand":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated extra data to include: items, printers.","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_tagsArguments","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_service_charges":{"post":{"operationId":"list_service_charges","summary":"List the configured service charges (order fees) with name and percentage or amount. Use for \"What service charges does ","description":"List the configured service charges (order fees) with name and percentage or amount. Use for \"What service charges does my Clover account 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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"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_service_chargesArguments","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_item_attributes":{"post":{"operationId":"list_item_attributes","summary":"List item attributes (such as Size) that define item group variants, with their options. Use for \"Which variant attribut","description":"List item attributes (such as Size) that define item group variants, with their options. Use for \"Which variant attributes are defined in my Clover inventory\".","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"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Clover filter expression such as 'name=Latte' or 'modifiedTime>=1767225600000'; allowed fields are listed in the endpoint docs.","title":"Filter"},"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_item_attributesArguments","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}}}}