{"openapi":"3.1.0","info":{"title":"Paid (BYOK) API","version":"0.1.0","description":"Paid (BYOK) lets an AI assistant read your own Paid data through the Paid API with a key you supply (Paid API key). Read-only: 11 tools (list_customers, get_customer, list_orders, get_order, list_invoices, get_invoice, list_payments, list_plans, list_products, list_credit_currencies, list_value_metrics). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-paid-ai.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-paid-ai/docs"},"termsOfService":"https://connectorbay.com/byok-paid-ai/terms"},"servers":[{"url":"https://byok-paid-ai.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-paid-ai/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_customers":{"post":{"operationId":"list_customers","summary":"List customers: name, legal name, website, external ID, creation state, churn status and VAT number. Search by name or f","description":"List customers: name, legal name, website, external ID, creation state, churn status and VAT number. Search by name or filter by status. Use for \"Which Paid customers have churned\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search by customer name (case-insensitive substring).","title":"Name"},"status":{"anyOf":[{"enum":["active","churned"],"type":"string"},{"type":"null"}],"default":null,"description":"Customer status.","title":"Status"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","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 Paid customer ID. Use for \"Show Paid customer cus_1\".","description":"Get one customer by Paid customer ID. Use for \"Show Paid customer cus_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Paid customer ID.","maxLength":64,"title":"Id","type":"string"}},"required":["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_orders":{"post":{"operationId":"list_orders","summary":"List orders (subscriptions): name, number, customer, dates, terms, order, billed and pending amounts. Filter by customer","description":"List orders (subscriptions): name, number, customer, dates, terms, order, billed and pending amounts. Filter by customer or status. Use for \"Which Paid orders are active for customer cus_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Paid customer ID to filter on.","title":"Customer Id"},"external_customer_id":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Optional external customer ID to filter on.","title":"External Customer Id"},"creation_state":{"anyOf":[{"enum":["draft","active"],"type":"string"},{"type":"null"}],"default":null,"description":"Creation state.","title":"Creation State"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","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 order by Paid order ID: amounts, dates, terms and creation state. Use for \"Show Paid order ord_1\".","description":"Get one order by Paid order ID: amounts, dates, terms and creation state. Use for \"Show Paid order ord_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Paid order ID.","maxLength":64,"title":"Id","type":"string"}},"required":["id"],"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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices: number, customer, order, status, payment status, currency, dates, totals, paid and remaining amounts. Fil","description":"List invoices: number, customer, order, status, payment status, currency, dates, totals, paid and remaining amounts. Filter by customer, order, status or payment status. Use for \"Which Paid invoices are overdue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Paid customer ID to filter on.","title":"Customer Id"},"external_customer_id":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Optional external customer ID to filter on.","title":"External Customer Id"},"order_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Order ID the invoice came from.","title":"Order Id"},"status":{"anyOf":[{"enum":["building","draft","pending","posted","voided","canceled","error"],"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status.","title":"Status"},"payment_status":{"anyOf":[{"enum":["pending","paid","partiallyPaid","overdue","error"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status.","title":"Payment Status"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Currency code such as USD.","title":"Currency"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"title":"list_invoicesArguments","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_invoice":{"post":{"operationId":"get_invoice","summary":"Get one invoice by Paid invoice ID: status, dates, totals, tax and remaining amount. Use for \"Show Paid invoice inv_1\".","description":"Get one invoice by Paid invoice ID: status, dates, totals, tax and remaining amount. Use for \"Show Paid invoice inv_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Paid invoice ID.","maxLength":64,"title":"Id","type":"string"}},"required":["id"],"title":"get_invoiceArguments","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_payments":{"post":{"operationId":"list_payments","summary":"List payments: number, customer, invoice, amount in cents, allocated amount, balance, currency, date, type and status. U","description":"List payments: number, customer, invoice, amount in cents, allocated amount, balance, currency, date, type and status. Use for \"List the failed Paid payments\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Optional Paid customer ID to filter on.","title":"Customer Id"},"external_customer_id":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Optional external customer ID to filter on.","title":"External Customer Id"},"status":{"anyOf":[{"enum":["draft","posted","processing","requiresAction","failed","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status.","title":"Status"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"title":"list_paymentsArguments","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_plans":{"post":{"operationId":"list_plans","summary":"List plans: product, name, supported currencies, default flag, status and archive date. Use for \"What pricing plans exis","description":"List plans: product, name, supported currencies, default flag, status and archive date. Use for \"What pricing plans exist in Paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Optional product ID to filter on.","title":"Product Id"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include archived plans.","title":"Include Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"title":"list_plansArguments","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: name, description, product code, active flag and archive date. Search by name. Use for \"What products do ","description":"List products: name, description, product code, active flag and archive date. Search by name. Use for \"What products do I have in Paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search by product name (case-insensitive substring).","title":"Name"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Filter by active flag.","title":"Active"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Filter by archived state.","title":"Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","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/list_credit_currencies":{"post":{"operationId":"list_credit_currencies","summary":"List credit currencies (prepaid credit types): name, key, status and description. Use for \"Which credit currencies are d","description":"List credit currencies (prepaid credit types): name, key, status and description. Use for \"Which credit currencies are defined in Paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["all","active","archived"],"type":"string"},{"type":"null"}],"default":"all","description":"Credit currency status.","title":"Status"}},"title":"list_credit_currenciesArguments","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_value_metrics":{"post":{"operationId":"list_value_metrics","summary":"List value metrics (outcomes you measure for pricing): slug, name, category, unit and monetary conversion. Use for \"Whic","description":"List value metrics (outcomes you measure for pricing): slug, name, category, unit and monetary conversion. Use for \"Which value metrics are set up in Paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include archived metrics.","title":"Include Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"title":"list_value_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}}}}