{"openapi":"3.1.0","info":{"title":"Ordergroove (BYOK) API","version":"0.1.0","description":"Ordergroove (BYOK) lets an AI assistant read your own Ordergroove data through the Ordergroove API with a key you supply (Application API key (x-api-key)). Read-only: 7 tools (list_subscriptions, list_orders, list_order_items, list_products, list_product_groups, list_offer_profiles, list_one_time_incentives). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ordergroove.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ordergroove/docs"},"termsOfService":"https://connectorbay.com/byok-ordergroove/terms"},"servers":[{"url":"https://byok-ordergroove.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ordergroove/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_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List subscriptions with price, frequency in days, start date, cancel reason, merchant order ID, type, components (produc","description":"List subscriptions with price, frequency in days, start date, cancel reason, merchant order ID, type, components (product and quantity) and dates. Filter by active flag, product, customer or dates. Use for \"Which subscriptions were cancelled this month and why\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"live":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for active subscriptions, false for inactive ones.","title":"Live"},"product":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this product ID.","title":"Product"},"customer":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this customer ID (the ID your store uses). Without the Bulk Operations permission on the key, a customer is required.","title":"Customer"},"created_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or after this date (YYYY-MM-DD).","title":"Created Start"},"created_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or before this date (YYYY-MM-DD).","title":"Created End"},"updated_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Updated on or after this date (YYYY-MM-DD).","title":"Updated Start"},"updated_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Updated on or before this date (YYYY-MM-DD).","title":"Updated End"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 100, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_subscriptionsArguments","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_orders":{"post":{"operationId":"list_orders","summary":"List recurring orders with customer ID, subtotal, tax, shipping, discount and total, status code, place date, cancellati","description":"List recurring orders with customer ID, subtotal, tax, shipping, discount and total, status code, place date, cancellation and retry counts. Filter by status, subscription, customer or dates. Use for \"Which Ordergroove orders were placed this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Order status code (see the Order Status Codes page of the docs).","title":"Status"},"subscription":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders of this subscription ID.","title":"Subscription"},"customer":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this customer ID (the ID your store uses). Without the Bulk Operations permission on the key, a customer is required.","title":"Customer"},"place_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Placed on or after this date (YYYY-MM-DD).","title":"Place Start"},"place_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Placed on or before this date (YYYY-MM-DD).","title":"Place End"},"created_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or after this date (YYYY-MM-DD).","title":"Created Start"},"created_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or before this date (YYYY-MM-DD).","title":"Created End"},"updated_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Updated on or after this date (YYYY-MM-DD).","title":"Updated Start"},"updated_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Updated on or before this date (YYYY-MM-DD).","title":"Updated End"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 100, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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/list_order_items":{"post":{"operationId":"list_order_items","summary":"List the items of recurring orders: product, quantity, price, total price, subscription, one-time flag and order update ","description":"List the items of recurring orders: product, quantity, price, total price, subscription, one-time flag and order update time. Filter by order, subscription, product or place date. Use for \"What items are in order 6120\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this order ID.","title":"Order"},"subscription":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this subscription ID.","title":"Subscription"},"product":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this product (external product ID).","title":"Product"},"one_time":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items added through one-time upsell.","title":"One Time"},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Order status code.","title":"Status"},"place_start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Order placed on or after this date (YYYY-MM-DD).","title":"Place Start"},"place_end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Order placed on or before this date (YYYY-MM-DD).","title":"Place End"},"omit_price_calculation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to leave out price fields and answer faster.","title":"Omit Price Calculation"}},"title":"list_order_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_products":{"post":{"operationId":"list_products","summary":"List autoship products with name, SKU, external product ID, price, type, autoship flags, discontinued flag and groups. S","description":"List autoship products with name, SKU, external product ID, price, type, autoship flags, discontinued flag and groups. Search by name, SKU or ID. Use for \"Which products can be on autoship\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text, matched against the field named in 'fields'.","title":"Search"},"fields":{"anyOf":[{"enum":["name","sku","external_product_id"],"type":"string"},{"type":"null"}],"default":null,"description":"Field the search text is matched against: name, sku or external_product_id.","title":"Fields"},"id_or_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive partial match on product ID or name.","title":"Id Or Name"},"autoship_enabled":{"anyOf":[{"enum":["true","false","all"],"type":"string"},{"type":"null"}],"default":null,"description":"true (default) for autoship products, false for others, or all for every product.","title":"Autoship Enabled"},"allow_discontinued":{"anyOf":[{"enum":["true","strict"],"type":"string"},{"type":"null"}],"default":null,"description":"true to include discontinued products, strict to list only discontinued ones.","title":"Allow Discontinued"},"group_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only products in this product group name.","title":"Group Name"},"product_type":{"anyOf":[{"enum":["standard","rotating","static price bundle","dynamic price bundle"],"type":"string"},{"type":"null"}],"default":null,"description":"Product type.","title":"Product Type"},"live":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for active products only.","title":"Live"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 100, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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/list_product_groups":{"post":{"operationId":"list_product_groups","summary":"List product groups (eligibility, incentive and SKU-swap groups) with name and type. Use for \"Which product groups are s","description":"List product groups (eligibility, incentive and SKU-swap groups) with name and type. Use for \"Which product groups are set up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the group with this name.","title":"Name"},"group_type":{"anyOf":[{"enum":["eligibility","incentive","sku_swap"],"type":"string"},{"type":"null"}],"default":null,"description":"Group type.","title":"Group Type"}},"title":"list_product_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_offer_profiles":{"post":{"operationId":"list_offer_profiles","summary":"List offer profiles with name, status, weight and the offers attached. Use for \"Which offer profiles are live\".","description":"List offer profiles with name, status, weight and the offers attached. Use for \"Which offer profiles are live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 100, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_offer_profilesArguments","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_one_time_incentives":{"post":{"operationId":"list_one_time_incentives","summary":"List one-time incentives (single-use discounts) with customer ID, description, external code, expiry, applied time and d","description":"List one-time incentives (single-use discounts) with customer ID, description, external code, expiry, applied time and discount rules. Use for \"Which one-time discounts are still unused\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this customer ID (the ID your store uses). Without the Bulk Operations permission on the key, a customer is required.","title":"Customer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 100, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_one_time_incentivesArguments","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}}}}