{"openapi":"3.1.0","info":{"title":"Paddle (BYOK) API","version":"0.1.0","description":"Paddle (BYOK) lets an AI assistant read your own Paddle data through the Paddle API with a key you supply (Paddle Billing API key (live environment; sandbox keys use a different host and do not work here)). Read-only: 11 tools (list_products, get_product, list_prices, list_customers, get_customer, list_subscriptions, get_subscription, list_transactions, get_mrr_metrics, get_revenue_metrics,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-paddle.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-paddle/docs"},"termsOfService":"https://connectorbay.com/byok-paddle/terms"},"servers":[{"url":"https://byok-paddle.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-paddle/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_products":{"post":{"operationId":"list_products","summary":"List Paddle Billing products (the things you sell) with name, type, tax category and status. Active products only unless","description":"List Paddle Billing products (the things you sell) with name, type, tax category and status. Active products only unless a status is given. Use for \"What products do I sell in Paddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses to include: active, archived (provider default active).","title":"Status"},"type":{"anyOf":[{"enum":["custom","standard"],"type":"string"},{"type":"null"}],"default":null,"description":"Only custom or standard products.","title":"Type"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last ID of the previous page (the 'next' link of the previous answer carries it). Leave empty for the first page.","title":"After"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 200; provider default 50).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["id[ASC]","id[DESC]"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by id: 'id[ASC]' (oldest first) or 'id[DESC]' (newest first, default).","title":"Order By"}},"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 Paddle product with name, description, tax category, type and status. Use for \"Show the details of Paddle produc","description":"Get one Paddle product with name, description, tax category, type and status. Use for \"Show the details of Paddle product pro_01abc\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Paddle product ID, starting with pro_.","maxLength":200,"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_prices":{"post":{"operationId":"list_prices","summary":"List Paddle prices with product, billing cycle, trial period and unit price. Amounts are strings in the currency's small","description":"List Paddle prices with product, billing cycle, trial period and unit price. Amounts are strings in the currency's smallest unit (cents for USD). Active prices only unless a status is given. Use for \"What prices and billing cycles do my Paddle products have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Paddle product IDs to limit to.","title":"Product Id"},"recurring":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for recurring prices only, false for one-time prices.","title":"Recurring"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses to include: active, archived (provider default active).","title":"Status"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last ID of the previous page (the 'next' link of the previous answer carries it). Leave empty for the first page.","title":"After"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 200; provider default 50).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["id[ASC]","id[DESC]"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by id: 'id[ASC]' (oldest first) or 'id[DESC]' (newest first, default).","title":"Order By"}},"title":"list_pricesArguments","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 Paddle customers with name, email, locale and status; search by name, email or ID. Active customers only unless a s","description":"List Paddle customers with name, email, locale and status; search by name, email or ID. Active customers only unless a status is given. Use for \"Find the Paddle customer with email jo@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text matched against customer ID, name and email.","title":"Search"},"email":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Exact email address (comma-separated for several).","title":"Email"},"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses to include: active, archived (provider default active).","title":"Status"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last ID of the previous page (the 'next' link of the previous answer carries it). Leave empty for the first page.","title":"After"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 200; provider default 50).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["id[ASC]","id[DESC]"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by id: 'id[ASC]' (oldest first) or 'id[DESC]' (newest first, default).","title":"Order By"}},"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 Paddle customer's name, email, locale, status and creation time. Use for \"Show the Paddle customer ctm_01abc\".","description":"Get one Paddle customer's name, email, locale, status and creation time. Use for \"Show the Paddle customer ctm_01abc\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"description":"Paddle customer ID, starting with ctm_.","maxLength":200,"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_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List Paddle subscriptions with status, customer, billing cycle, next billing time, scheduled changes and items. Every st","description":"List Paddle subscriptions with status, customer, billing cycle, next billing time, scheduled changes and items. Every status unless filtered. Use for \"Which Paddle subscriptions are active and when do they renew\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses: active, canceled, past_due, paused, trialing.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated customer IDs to limit to.","title":"Customer Id"},"price_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated price IDs to limit to.","title":"Price Id"},"collection_mode":{"anyOf":[{"enum":["automatic","manual"],"type":"string"},{"type":"null"}],"default":null,"description":"automatic or manual.","title":"Collection Mode"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last ID of the previous page (the 'next' link of the previous answer carries it). Leave empty for the first page.","title":"After"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 200; provider default 50).","title":"Per Page"},"order_by":{"anyOf":[{"enum":["id[ASC]","id[DESC]"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by id: 'id[ASC]' (oldest first) or 'id[DESC]' (newest first, default).","title":"Order By"}},"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/get_subscription":{"post":{"operationId":"get_subscription","summary":"Get one Paddle subscription with status, billing cycle, current period, next billing time, scheduled change and manageme","description":"Get one Paddle subscription with status, billing cycle, current period, next billing time, scheduled change and management links. Use for \"Show the details of Paddle subscription sub_01abc\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subscription_id":{"description":"Paddle subscription ID, starting with sub_.","maxLength":200,"title":"Subscription Id","type":"string"}},"required":["subscription_id"],"title":"get_subscriptionArguments","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_transactions":{"post":{"operationId":"list_transactions","summary":"List Paddle transactions (orders and renewals) with status, customer, subscription, invoice number, dates and totals. Am","description":"List Paddle transactions (orders and renewals) with status, customer, subscription, invoice number, dates and totals. Amounts are strings in the currency's smallest unit (cents for USD). Up to 30 per page. Use for \"Show my latest Paddle transactions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses: draft, ready, billed, paid, completed, canceled, past_due.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated customer IDs to limit to.","title":"Customer Id"},"subscription_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated subscription IDs to limit to.","title":"Subscription Id"},"created_at_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions created after this RFC 3339 time, for example 2026-09-01T00:00:00Z.","title":"Created At After"},"order_by":{"anyOf":[{"enum":["id[DESC]","id[ASC]","billed_at[DESC]","billed_at[ASC]","created_at[DESC]","created_at[ASC]","updated_at[DESC]","updated_at[ASC]"],"type":"string"},{"type":"null"}],"default":"id[DESC]","description":"Order by id, billed_at, created_at or updated_at, as 'created_at[DESC]' (newest first) or '[ASC]'.","title":"Order By"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last ID of the previous page (the 'next' link of the previous answer carries it). Leave empty for the first page.","title":"After"},"per_page":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page (1 to 30; provider default 30).","title":"Per Page"}},"title":"list_transactionsArguments","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_mrr_metrics":{"post":{"operationId":"get_mrr_metrics","summary":"Get monthly recurring revenue (MRR) over a date range as a daily time series in the account's currency. Use for \"What wa","description":"Get monthly recurring revenue (MRR) over a date range as a daily time series in the account's currency. Use for \"What was my Paddle MRR over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"description":"First date, YYYY-MM-DD (UTC). Must not be after to_date.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last date, YYYY-MM-DD (UTC).","maxLength":10,"title":"To Date","type":"string"}},"required":["from_date","to_date"],"title":"get_mrr_metricsArguments","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_revenue_metrics":{"post":{"operationId":"get_revenue_metrics","summary":"Get net revenue over a date range as a time series in the account's currency. Use for \"How much net revenue did Paddle r","description":"Get net revenue over a date range as a time series in the account's currency. Use for \"How much net revenue did Paddle record in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"description":"First date, YYYY-MM-DD (UTC). Must not be after to_date.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last date, YYYY-MM-DD (UTC).","maxLength":10,"title":"To Date","type":"string"}},"required":["from_date","to_date"],"title":"get_revenue_metricsArguments","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_active_subscribers_metrics":{"post":{"operationId":"get_active_subscribers_metrics","summary":"Get the number of paying active subscribers over a date range as a daily time series (trialing users are not counted). U","description":"Get the number of paying active subscribers over a date range as a daily time series (trialing users are not counted). Use for \"How many active Paddle subscribers did I have last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"description":"First date, YYYY-MM-DD (UTC). Must not be after to_date; equal dates return nothing.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last date, YYYY-MM-DD (UTC).","maxLength":10,"title":"To Date","type":"string"}},"required":["from_date","to_date"],"title":"get_active_subscribers_metricsArguments","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}}}}