{"openapi":"3.1.0","info":{"title":"Snipcart (BYOK) API","version":"0.1.0","description":"Snipcart (BYOK) lets an AI assistant read your own Snipcart data through the Snipcart API with a key you supply (secret API key (Test or Live mode)). Read-only: 8 tools (list_orders, get_order, list_customers, get_customer, list_products, get_product, list_discounts, get_discount). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-snipcart.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-snipcart/docs"},"termsOfService":"https://connectorbay.com/byok-snipcart/terms"},"servers":[{"url":"https://byok-snipcart.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-snipcart/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_orders":{"post":{"operationId":"list_orders","summary":"List completed orders (lighter excerpt form by default) with status, payment and invoice number. Filter by status, payme","description":"List completed orders (lighter excerpt form by default) with status, payment and invoice number. Filter by status, payment status, purchaser, product or date range. Use for \"What Snipcart orders were placed this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["InProgress","Processed","Disputed","Shipped","Delivered","Pending","Cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Order status.","title":"Status"},"payment_status":{"anyOf":[{"enum":["Paid","Deferred","PaidDeferred","ChargedBack","Refunded","Paidout","Failed","Pending","Expired","Cancelled","Open","Authorized"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status.","title":"Payment Status"},"format":{"anyOf":[{"enum":["Excerpt","Full"],"type":"string"},{"type":"null"}],"default":"Excerpt","description":"Level of detail: Excerpt (default here, light summaries) or Full (complete orders, long).","title":"Format"},"placed_by":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Purchaser name or email.","title":"Placed By"},"product_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders containing the product with this user-defined id.","title":"Product Id"},"invoice_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only the order with this invoice number.","title":"Invoice Number"},"include_test_orders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include Test-mode orders when using a Live key.","title":"Include Test Orders"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or after this date-time (ISO 8601, for example 2026-01-01T00:00:00Z).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or before this date-time (ISO 8601).","title":"Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0). The answer's totalItems gives the total.","title":"Offset"}},"title":"list_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 complete order by its token, including items, promo codes, taxes and shipping packages. Use for \"Show me the ful","description":"Get one complete order by its token, including items, promo codes, taxes and shipping packages. Use for \"Show me the full Snipcart order d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"token":{"description":"Order token (a GUID) from list_orders.","maxLength":60,"title":"Token","type":"string"}},"required":["token"],"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_customers":{"post":{"operationId":"list_customers","summary":"List customers (Snipcart users) with order count and total spent, billing name and location. Default order is by number ","description":"List customers (Snipcart users) with order count and total spent, billing name and location. Default order is by number of orders. Use for \"Who are my top Snipcart customers by order value\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["Unconfirmed","Confirmed"],"type":"string"},{"type":"null"}],"default":null,"description":"Customer status.","title":"Status"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the customer with this exact email.","title":"Email"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Customers whose billing name contains this text.","title":"Name"},"order_by":{"anyOf":[{"enum":["OrdersValue","NbrOrders","Date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order.","title":"Order By"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or after this date-time (ISO 8601, for example 2026-01-01T00:00:00Z).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or before this date-time (ISO 8601).","title":"Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0). The answer's totalItems gives the total.","title":"Offset"}},"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/get_customer":{"post":{"operationId":"get_customer","summary":"Get one customer by id with statistics and billing details. Use for \"Show Snipcart customer c8de947a-2483-4e36-9052-031e","description":"Get one customer by id with statistics and billing details. Use for \"Show Snipcart customer c8de947a-2483-4e36-9052-031e2aa3f0ac\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"description":"Customer id (a GUID) from list_customers.","maxLength":60,"title":"Customer Id","type":"string"}},"required":["customer_id"],"title":"get_customerArguments","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_products":{"post":{"operationId":"list_products","summary":"List products with sales statistics (number of sales, total sales), price, stock and variants. Use for \"Which Snipcart p","description":"List products with sales statistics (number of sales, total sales), price, stock and variants. Use for \"Which Snipcart products sell the most\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_by":{"anyOf":[{"enum":["NbrSales","SalesValue","CreationDate"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort: NbrSales (most sold first), SalesValue (highest sales first) or CreationDate (newest first).","title":"Order By"},"keywords":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Products whose name, description or user-defined id contains this text.","title":"Keywords"},"user_defined_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Products whose user-defined id contains this text.","title":"User Defined Id"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived products.","title":"Archived"},"exclude_zero_sales":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only products with at least one sale.","title":"Exclude Zero Sales"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or after this date-time (ISO 8601, for example 2026-01-01T00:00:00Z).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records on or before this date-time (ISO 8601).","title":"Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging (default 0). The answer's totalItems gives the total.","title":"Offset"}},"title":"list_productsArguments","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_product":{"post":{"operationId":"get_product","summary":"Get one product by its Snipcart id or by the user-defined id from your buy button. Use for \"Show Snipcart product HGW\".","description":"Get one product by its Snipcart id or by the user-defined id from your buy button. Use for \"Show Snipcart product HGW\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Snipcart product id (GUID) or user-defined id.","maxLength":100,"title":"Product Id","type":"string"}},"required":["product_id"],"title":"get_productArguments","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 all discounts (promo codes and automatic rules) with trigger, type, rate or amount, usage count and expiry. Not pag","description":"List all discounts (promo codes and automatic rules) with trigger, type, rate or amount, usage count and expiry. Not paginated. Use for \"What Snipcart discount codes are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/get_discount":{"post":{"operationId":"get_discount","summary":"Get one discount by id. Use for \"Show Snipcart discount 2223490d-84c1-480c-b713-50cb0b819313\".","description":"Get one discount by id. Use for \"Show Snipcart discount 2223490d-84c1-480c-b713-50cb0b819313\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"discount_id":{"description":"Discount id (a GUID) from list_discounts.","maxLength":60,"title":"Discount Id","type":"string"}},"required":["discount_id"],"title":"get_discountArguments","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}}}}