{"openapi":"3.1.0","info":{"title":"Loyverse (BYOK) API","version":"0.1.0","description":"Loyverse (BYOK) lets an AI assistant read your own Loyverse data through the Loyverse API with a key you supply (personal access token). Read-only: 12 tools (get_merchant, list_stores, list_items, list_variants, list_categories, list_inventory, list_receipts, get_receipt, list_shifts, list_employees, list_customers, list_payment_types). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-loyverse.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-loyverse/docs"},"termsOfService":"https://connectorbay.com/byok-loyverse/terms"},"servers":[{"url":"https://byok-loyverse.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-loyverse/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 Loyverse merchant account: business name, country, currency and creation date. Use for \"Which Loyverse business","description":"Show the Loyverse merchant account: business name, country, currency and creation date. Use for \"Which Loyverse business does my token belong 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_stores":{"post":{"operationId":"list_stores","summary":"List the stores (locations) of the account with address, phone and creation date. Use for \"What stores does my Loyverse ","description":"List the stores (locations) of the account with address, phone and creation date. Use for \"What stores does my Loyverse account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated store ids to return; empty for all.","title":"Store Ids"},"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"}},"title":"list_storesArguments","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_items":{"post":{"operationId":"list_items","summary":"List catalog items with category, tracking flags, image and their variants (SKU, barcode, price, per-store availability)","description":"List catalog items with category, tracking flags, image and their variants (SKU, barcode, price, per-store availability). Page with the cursor. Use for \"Which items are in my Loyverse catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"updated_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated at or after this UTC time, ISO 8601, for example 2026-01-01T00:00:00.000Z.","title":"Updated At Min"},"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"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/list_variants":{"post":{"operationId":"list_variants","summary":"List item variants with SKU, barcode, cost and default price; filter by SKU or item ids. Use for \"Find the Loyverse vari","description":"List item variants with SKU, barcode, cost and default price; filter by SKU or item ids. Use for \"Find the Loyverse variant with SKU 10001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sku":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact SKU to look for.","title":"Sku"},"items_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated item ids whose variants to return.","title":"Items Ids"},"updated_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated at or after this UTC time, ISO 8601, for example 2026-01-01T00:00:00.000Z.","title":"Updated At Min"},"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_variantsArguments","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 with their colour and creation date. Use for \"What item categories do I have in Loyverse\".","description":"List item categories with their colour and creation date. Use for \"What item categories do I have in Loyverse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"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_inventory":{"post":{"operationId":"list_inventory","summary":"List stock levels (in_stock) per item variant and store, optionally for chosen stores or variants. Use for \"How much sto","description":"List stock levels (in_stock) per item variant and store, optionally for chosen stores or variants. Use for \"How much stock do I have per store in Loyverse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated store ids to filter by.","title":"Store Ids"},"variant_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated variant ids to filter by.","title":"Variant Ids"},"updated_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated at or after this UTC time, ISO 8601, for example 2026-01-01T00:00:00.000Z.","title":"Updated At Min"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_inventoryArguments","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_receipts":{"post":{"operationId":"list_receipts","summary":"List sales and refund receipts, newest first when order is DESC, with totals, tax, tip, store, employee and line items. ","description":"List sales and refund receipts, newest first when order is DESC, with totals, tax, tip, store, employee and line items. Filter by store and date range. Use for \"What were my Loyverse sales receipts yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts of this store id.","title":"Store Id"},"created_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created at or after this UTC time, ISO 8601, for example 2026-01-01T00:00:00.000Z.","title":"Created At Min"},"created_at_max":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created at or before this UTC time, ISO 8601.","title":"Created At Max"},"source":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts from this source, for example 'My app'.","title":"Source"},"receipt_numbers":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated receipt numbers to return.","title":"Receipt Numbers"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_receiptsArguments","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_receipt":{"post":{"operationId":"get_receipt","summary":"Get one receipt by its receipt number with line items, discounts, taxes and payments. Use for \"Show Loyverse receipt 1-1","description":"Get one receipt by its receipt number with line items, discounts, taxes and payments. Use for \"Show Loyverse receipt 1-1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"receipt_number":{"description":"Receipt number, for example '1-1001'.","maxLength":200,"title":"Receipt Number","type":"string"}},"required":["receipt_number"],"title":"get_receiptArguments","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_shifts":{"post":{"operationId":"list_shifts","summary":"List cash shifts with opening and closing time, sales, refunds, discounts, cash expected and counted. Use for \"How did m","description":"List cash shifts with opening and closing time, sales, refunds, discounts, cash expected and counted. Use for \"How did my last Loyverse shifts close out\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"store_ids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated store ids to filter by.","title":"Store Ids"},"created_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created at or after this UTC time, ISO 8601, for example 2026-01-01T00:00:00.000Z.","title":"Created At Min"},"created_at_max":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created at or before this UTC time, ISO 8601.","title":"Created At Max"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_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/list_employees":{"post":{"operationId":"list_employees","summary":"List employees with id, name, owner flag and the stores they work in (no contact details are returned). Use for \"Who are","description":"List employees with id, name, owner flag and the stores they work in (no contact details are returned). Use for \"Who are the employees in my Loyverse account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_employeesArguments","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 customers with visit counts, total spent, points and first and last visit (name only; no email, phone or address is","description":"List customers with visit counts, total spent, points and first and last visit (name only; no email, phone or address is returned). Use for \"Who are my best Loyverse customers by total spent\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"updated_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers updated at or after this UTC ISO 8601 time.","title":"Updated At Min"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 250).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to fetch the next page; 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_payment_types":{"post":{"operationId":"list_payment_types","summary":"List the payment types configured in the account (cash, card and others) with the stores they apply to. Use for \"Which p","description":"List the payment types configured in the account (cash, card and others) with the stores they apply to. Use for \"Which payment types are set up in Loyverse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"show_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include soft-deleted records.","title":"Show Deleted"}},"title":"list_payment_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}}}}