{"openapi":"3.1.0","info":{"title":"Recurly Catalog (BYOK) API","version":"0.1.0","description":"Recurly Catalog (BYOK) lets an AI assistant read your own Recurly Catalog data through the Recurly Catalog API with a key you supply (Recurly private API key (US data center sites)). Read-only: 9 tools (get_plan, list_plan_add_ons, list_items, get_item, list_coupons, get_coupon, list_measured_units, list_shipping_methods, list_price_segments). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-recurly-catalog.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-recurly-catalog/docs"},"termsOfService":"https://connectorbay.com/byok-recurly-catalog/terms"},"servers":[{"url":"https://byok-recurly-catalog.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-recurly-catalog/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_plan":{"post":{"operationId":"get_plan","summary":"Get one Recurly plan by id or code with pricing per currency, setup fees, billing interval, trial, billing cycles, tax s","description":"Get one Recurly plan by id or code with pricing per currency, setup fees, billing interval, trial, billing cycles, tax settings and accounting code. Use for \"What does the Recurly plan with code gold cost and what trial does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan, item or coupon id (no prefix, for example e28zov4fw0v2) or code with the prefix 'code-', for example code-gold.","maxLength":200,"title":"Plan Id","type":"string"}},"required":["plan_id"],"title":"get_planArguments","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_plan_add_ons":{"post":{"operationId":"list_plan_add_ons","summary":"List the add-ons of one Recurly plan with type (fixed or usage), price per currency, tiers, default quantity and whether","description":"List the add-ons of one Recurly plan with type (fixed or usage), price per currency, tiers, default quantity and whether they are optional. Use for \"Which add-ons can customers buy with the gold plan in Recurly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"description":"Plan, item or coupon id (no prefix, for example e28zov4fw0v2) or code with the prefix 'code-', for example code-gold.","maxLength":200,"title":"Plan Id","type":"string"},"state":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only records in this state.","title":"State"},"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: created_at or updated_at (default created_at).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or after this ISO 8601 time (applies to the sort field), for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or before this ISO 8601 time (applies to the sort field).","title":"End Time"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"required":["plan_id"],"title":"list_plan_add_onsArguments","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 Recurly items (one-off catalog charges) with code, name, state, SKU, accounting code, tax settings and price per cu","description":"List Recurly items (one-off catalog charges) with code, name, state, SKU, accounting code, tax settings and price per currency. Use for \"What one-off items are in my Recurly catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only records in this state.","title":"State"},"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: created_at or updated_at (default created_at).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or after this ISO 8601 time (applies to the sort field), for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or before this ISO 8601 time (applies to the sort field).","title":"End Time"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"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 Recurly item by id or code with price per currency, SKU, accounting and tax settings. Use for \"What does the Rec","description":"Get one Recurly item by id or code with price per currency, SKU, accounting and tax settings. Use for \"What does the Recurly item setup-service cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_id":{"description":"Item id (no prefix) or code with the prefix 'code-', for example code-setup-service.","maxLength":200,"title":"Item Id","type":"string"}},"required":["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_coupons":{"post":{"operationId":"list_coupons","summary":"List Recurly coupons with code, name, state, redemption limits, duration, discount, free trial and expiry. Redeeming acc","description":"List Recurly coupons with code, name, state, redemption limits, duration, discount, free trial and expiry. Redeeming accounts are not returned. Use for \"Which Recurly coupons can still be redeemed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: created_at or updated_at (default created_at).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or after this ISO 8601 time (applies to the sort field), for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or before this ISO 8601 time (applies to the sort field).","title":"End Time"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"title":"list_couponsArguments","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_coupon":{"post":{"operationId":"get_coupon","summary":"Get one Recurly coupon by id or code with its discount, duration, redemption limits and the plans or items it applies to","description":"Get one Recurly coupon by id or code with its discount, duration, redemption limits and the plans or items it applies to. Use for \"What discount does the Recurly coupon spring10 give\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"coupon_id":{"description":"Coupon id (no prefix) or code with the prefix 'code-', for example code-spring10.","maxLength":200,"title":"Coupon Id","type":"string"}},"required":["coupon_id"],"title":"get_couponArguments","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_measured_units":{"post":{"operationId":"list_measured_units","summary":"List measured units (what usage add-ons are measured in, such as API calls) with name, display name and state. Use for \"","description":"List measured units (what usage add-ons are measured in, such as API calls) with name, display name and state. Use for \"Which measured units do I bill usage in on Recurly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only records in this state.","title":"State"},"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: created_at or updated_at (default created_at).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or after this ISO 8601 time (applies to the sort field), for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or before this ISO 8601 time (applies to the sort field).","title":"End Time"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"title":"list_measured_unitsArguments","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_shipping_methods":{"post":{"operationId":"list_shipping_methods","summary":"List shipping methods with code, name, accounting code and tax code. Use for \"Which shipping methods are set up in Recur","description":"List shipping methods with code, name, accounting code and tax code. Use for \"Which shipping methods are set up in Recurly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: created_at or updated_at (default created_at).","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"begin_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or after this ISO 8601 time (applies to the sort field), for example 2026-09-01T00:00:00Z.","title":"Begin Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records at or before this ISO 8601 time (applies to the sort field).","title":"End Time"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"title":"list_shipping_methodsArguments","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_price_segments":{"post":{"operationId":"list_price_segments","summary":"List price segments (code and id) used to give different prices to different groups of customers. Use for \"Which price s","description":"List price segments (code and id) used to give different prices to different groups of customers. Use for \"Which price segments exist in my Recurly site\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort order: asc (oldest first) or desc (newest first).","title":"Order"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 200; provider default 20). Page forward by sorting and moving begin_time past the last record.","title":"Limit"}},"title":"list_price_segmentsArguments","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}}}}