openapi: 3.2.0 info: title: 'GTM API public contract: gtm.service.id Billing…' description: 'Identity, access and money: users, teams and members, API keys, OAuth clients and authorizations, billing products, subscriptions, transactions and payment methods, notifications, TLS certificates and support requests.' version: '1.0' contact: name: GTM API url: https://gtm-api.com email: support@gtm-api.com license: name: Proprietary url: https://gtm-api.com/license servers: - url: https://app.gtm-api.com/id/v4 description: Production, through the app.gtm-api.com gateway security: - BearerJwt: [] TeamSid: [] tags: - name: billing_subscriptions description: Registry package `mcp.id/billing_subscriptions`, served on MCP mount `id.billing`. paths: /api/billing-subscriptions/create-checkout: post: operationId: create_billing_subscription_checkout summary: Create subscription checkout description: 'Start a self-serve purchase of a subscription. DANGEROUS (charges money): it pre-creates a billed Paddle transaction and returns a hosted checkout_url the buyer pays in the Paddle overlay (server-side preview→commit gate applies). Resolves the bracket price for the requested slot count, optionally applies to team_sid on activation (omit to buy floating), and can bundle add-ons in the same checkout. The real subscription row is born on the billing-subscriptions.activated webhook; poll get/search afterwards. Requires billing.manage. Contract: - MCP tool `create_billing_subscription_checkout`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBillingSubscriptionCheckoutRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/CreateBillingSubscriptionCheckoutResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: create_billing_subscription_checkout x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: complex /api/billing-subscriptions/search: post: operationId: search_billing_subscriptions summary: Search billing subscriptions description: 'List the caller''s billing subscriptions: the ones they bought (owner = caller, including floating subscriptions applied to no team) plus the one applied to a team they can read. Filter by status, team_sid:{is_null:true} for floating, paddle_subscription_id:{is_null:true} for the internal sentinels (free/partner), or current_period_ends_at for expiry windows. include price / product / team / latest_transactions to hydrate context. page_size:0 returns counts only. Contract: - MCP tool `search_billing_subscriptions`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `search`, response envelope `search`. - Flags: read only.' tags: - billing_subscriptions requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SearchBillingSubscriptionsRequest' responses: '200': description: '`search` success envelope.' content: application/json: schema: $ref: '#/components/schemas/SearchBillingSubscriptionsResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: search_billing_subscriptions x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: search x-gtm-envelope: search x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}: get: operationId: get_billing_subscription summary: Get billing subscription description: 'Fetch a single billing subscription by sid, with optional includes (price, product, team, latest_transactions). Contract: - MCP tool `get_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `get`, response envelope `get`. - Flags: read only.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Path segment `{sid}`. schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ - name: include[] in: query required: false description: Query parameter `include`. style: form explode: true schema: type: array items: type: string responses: '200': description: '`get` success envelope.' content: application/json: schema: $ref: '#/components/schemas/GetBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: get_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: get x-gtm-envelope: get x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: trivial /api/billing-subscriptions/{sid}/add-addon: post: operationId: add_billing_subscription_addon summary: Add subscription add-on description: 'Add a recurring add-on item to the SAME subscription (one Paddle PATCH, one prorated charge). DANGEROUS: money moves; server-side confirm gate applies. The proration rides the subscription''s own next invoice (prorated_next_billing_period) so the buyer sees one charge on one date, except while a cancel or pause is scheduled, where Paddle refuses a next-period mode and the prorated amount is charged immediately instead. result.proration_mode reports which of the two was used. Not idempotent: every call buys quantity more units. When Paddle''s answer to the change is lost, or it answers 5xx, the service reads the subscription back: the call succeeds when Paddle carries the change, and anything else is 409 billing_change_unconfirmed, which is not a retry: read the subscription again before buying more. Requires billing.manage. Contract: - MCP tool `add_billing_subscription_addon`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddBillingSubscriptionAddonRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/AddBillingSubscriptionAddonResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: add_billing_subscription_addon x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/apply: post: operationId: apply_billing_subscription summary: Apply subscription to team description: 'Apply a floating subscription (owned by the caller) to a team, activating its slots + limits there. Owner-only. DANGEROUS state change (server-side confirm gate); rejects with 409 if the team already has a live applied subscription or is soft-deleted. No charge. Requires billing.manage. Contract: - MCP tool `apply_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplyBillingSubscriptionRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/ApplyBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: apply_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/cancel: post: operationId: cancel_billing_subscription summary: Cancel subscription description: 'Cancel the subscription at the end of the current period (terminal). DANGEROUS: the team loses capacity when the period ends, though data is retained and there is no immediate charge or refund. Server-side confirm gate applies. There is no delete verb; cancel is the canonical termination. Requires billing.manage. Contract: - MCP tool `cancel_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/CancelBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: cancel_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/change: post: operationId: change_billing_subscription summary: Change subscription description: 'Commit a quantity / bracket-price change. DANGEROUS: an UPGRADE charges the owner''s card immediately (prorated); a downgrade applies next period (no immediate charge). Server-side preview→commit gate applies; call preview_billing_subscription_change first. manual (sales) subscriptions are not re-bracketed (422). The committed state arrives via webhook; the response returns the optimistic post-change row. Provide at least one of quantity / price_sid. Requires billing.manage. Contract: - MCP tool `change_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ChangeBillingSubscriptionRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/ChangeBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: change_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: complex /api/billing-subscriptions/{sid}/get-update-payment-method-link: post: operationId: get_billing_subscription_update_payment_method_link summary: Get update-payment-method link description: 'Return a short-lived Paddle portal deep link to update the card for this subscription (the typical past_due recovery path). No charge, mutates nothing on our side. Requires billing.manage. Contract: - MCP tool `get_billing_subscription_update_payment_method_link`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: read only.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/GetBillingSubscriptionUpdatePaymentMethodLinkResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: get_billing_subscription_update_payment_method_link x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: trivial /api/billing-subscriptions/{sid}/pause: post: operationId: pause_billing_subscription summary: Pause subscription description: 'Pause the subscription effective the next billing period. DANGEROUS state change (server-side confirm gate); while paused the applied team is gated like suspended, slots/data retained, billing stops. No charge. The committed status arrives via webhook. Resume with resume_billing_subscription. Requires billing.manage. Contract: - MCP tool `pause_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/PauseBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: pause_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/preview-change: post: operationId: preview_billing_subscription_change summary: Preview subscription change description: 'Read-only proration preview for a quantity / bracket-price change BEFORE committing. Calls Paddle Pricing Preview and returns the immediate charge (upgrade) or next-period credit (downgrade), the resolved new bracket price, and whether it crosses a bracket boundary. No state change, no charge. This is the confirmation gate to show the user before change_billing_subscription. Provide at least one of quantity / price_sid. Requires billing.view. Contract: - MCP tool `preview_billing_subscription_change`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: read only.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/PreviewBillingSubscriptionChangeRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/PreviewBillingSubscriptionChangeResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: preview_billing_subscription_change x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: complex /api/billing-subscriptions/{sid}/remove-addon: post: operationId: remove_billing_subscription_addon summary: Remove subscription add-on description: 'Remove add-on units from the subscription, effective next period (no refund, no immediate charge). Pass quantity to give back part of the line, or omit it to drop the whole line; result.remaining_quantity reports what is left (0 means the line is gone). The price_sid must be a live item on this subscription (422 addon_not_on_subscription otherwise). Works while a cancel or pause is scheduled. A give-back Paddle did not confirm (its answer lost, or a 5xx) is 409 billing_change_unconfirmed: read the subscription again before repeating it. DANGEROUS state change (server-side confirm gate). Requires billing.manage. Contract: - MCP tool `remove_billing_subscription_addon`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RemoveBillingSubscriptionAddonRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/RemoveBillingSubscriptionAddonResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: remove_billing_subscription_addon x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/resume: post: operationId: resume_billing_subscription summary: Resume subscription description: 'Resume a paused subscription; billing continues from the next period and the applied team re-derives active. DANGEROUS state change (server-side confirm gate). No charge. The committed status arrives via webhook. Requires billing.manage. Contract: - MCP tool `resume_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/ResumeBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: resume_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/unapply: post: operationId: unapply_billing_subscription summary: Unapply subscription description: 'Detach a subscription from its team, returning it to floating on the buyer''s balance. DANGEROUS: removes the team''s capacity (the team goes suspended if this was its only applied subscription); does NOT cancel billing or refund. Used to move a subscription to another team. Requires billing.manage. Contract: - MCP tool `unapply_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/UnapplyBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: unapply_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: true x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/billing-subscriptions/{sid}/undo-cancel: post: operationId: undo_cancel_billing_subscription summary: Undo scheduled cancel description: 'Drop a scheduled cancel before it takes effect; billing continues as if cancel was never asked. Decided on the live Paddle state: nothing pending is a success no-op (cleared:false), a scheduled pause or resume is refused with 409 scheduled_change_is_not_cancel naming the verb that clears it, and an already canceled subscription is too late to undo. Synchronous, no charge, no pending block. Also the unlock a 409 subscription_locked_pending_changes points at. Requires billing.manage. Contract: - MCP tool `undo_cancel_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: none.' tags: - billing_subscriptions parameters: - name: sid in: path required: true description: Billing subscription sid (bl_sb_…). schema: type: string minLength: 18 maxLength: 18 pattern: ^bl_sb_ description: Billing subscription sid (bl_sb_…). responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/UndoCancelBillingSubscriptionResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: undo_cancel_billing_subscription x-gtm-mcp-mount: id.billing x-gtm-entity: billing_subscriptions x-gtm-operation: action x-gtm-envelope: action x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical components: schemas: GetBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - get item: type: object properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at included: type: object additionalProperties: {} includes: type: array items: type: string meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - item - included - includes - meta AddBillingSubscriptionAddonResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta ChangeBillingSubscriptionRequest: type: object description: Request body of `change_billing_subscription`. properties: quantity: type: integer minimum: 1 description: New slot count (re-bracketed). Omit for a price-only change. price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: Explicit target bracket; usually derived from quantity. SearchBillingSubscriptionsResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - search items: type: array items: type: object properties: item: type: object properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at included: type: object additionalProperties: {} required: - item - included pagination: type: object properties: next_cursor: type: - string - 'null' has_more: type: boolean total_count: type: - integer - 'null' required: - next_cursor - has_more - total_count applied_filters: type: object additionalProperties: {} includes: type: array items: type: string meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms counts: type: object properties: {} required: - success - operation - items - pagination - applied_filters - includes - meta SearchBillingSubscriptionsRequest: type: object description: Request body of `search_billing_subscriptions`. properties: filter: type: object properties: sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false owner_user_sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false team_sid: type: object properties: eq: type: string in: type: array items: type: string is_null: type: boolean additionalProperties: false paddle_subscription_id: type: object properties: eq: type: string in: type: array items: type: string is_null: type: boolean additionalProperties: false status: type: object properties: eq: type: string enum: - active - past_due - paused - canceled ne: type: string enum: - active - past_due - paused - canceled in: type: array items: type: string enum: - active - past_due - paused - canceled nin: type: array items: type: string enum: - active - past_due - paused - canceled additionalProperties: false collection_mode: type: object properties: eq: type: string enum: - automatic - manual in: type: array items: type: string enum: - automatic - manual additionalProperties: false price_sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false current_period_ends_at: type: object properties: gte: type: string lte: type: string gt: type: string lt: type: string is_null: type: boolean additionalProperties: false next_billed_at: type: object properties: gte: type: string lte: type: string gt: type: string lt: type: string is_null: type: boolean additionalProperties: false canceled_at: type: object properties: gte: type: string lte: type: string is_null: type: boolean additionalProperties: false created_at: type: object properties: gte: type: string lte: type: string gt: type: string lt: type: string additionalProperties: false updated_at: type: object properties: gte: type: string lte: type: string gt: type: string lt: type: string additionalProperties: false deleted_at: type: object properties: gte: type: string lte: type: string is_null: type: boolean additionalProperties: false include: type: array items: type: string enum: - price - product - team - latest_transactions description: Relations to eager-load (see entity Includes). sort: type: object properties: field: type: string enum: - created_at - updated_at - current_period_ends_at direction: type: string enum: - asc - desc description: Default desc. required: - field page_size: type: integer minimum: 0 maximum: 500 description: 0..500, default 50. page_size=0 = count-only, page_size=1 = getFirst. cursor: type: - string - 'null' description: Opaque forward cursor from a previous response pagination.next_cursor. ChangeBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: - string - 'null' count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error PauseBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta PreviewBillingSubscriptionChangeRequest: type: object description: Request body of `preview_billing_subscription_change`. properties: quantity: type: integer minimum: 1 description: Proposed new slot count (re-bracketed automatically). price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: Explicit target bracket price; usually resolved from quantity. UnapplyBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta CreateBillingSubscriptionCheckoutResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta GetBillingSubscriptionUpdatePaymentMethodLinkResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta ResumeBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta ApplyBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta RemoveBillingSubscriptionAddonResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta PreviewBillingSubscriptionChangeResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta CancelBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta AddBillingSubscriptionAddonRequest: type: object description: Request body of `add_billing_subscription_addon`. properties: price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: The add-on price (product.type=addon). quantity: type: integer minimum: 1 description: Units of the add-on. required: - price_sid - quantity CreateBillingSubscriptionCheckoutRequest: type: object description: Request body of `create_billing_subscription_checkout`. properties: price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: 'Billing price sid (bl_pc_…): a bracket / cadence price.' quantity: type: integer minimum: 1 description: Slots to buy on the base plan line; must fall inside the price bracket. team_sid: type: string minLength: 18 maxLength: 18 pattern: ^ts_tm_ description: Apply to this team on activation; omit / null to buy floating. addons: type: array items: type: object properties: price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: 'Billing price sid (bl_pc_…): a bracket / cadence price.' quantity: type: integer minimum: 1 required: - price_sid - quantity description: Optional add-on items bought in the same checkout (one Paddle transaction). required: - price_sid - quantity ApplyBillingSubscriptionRequest: type: object description: Request body of `apply_billing_subscription`. properties: team_sid: type: string minLength: 18 maxLength: 18 pattern: ^ts_tm_ description: 'Team sid (ts_tm_…): the applied team.' required: - team_sid UndoCancelBillingSubscriptionResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: - object - 'null' properties: sid: type: string owner_user_sid: type: string team_sid: type: - string - 'null' paddle_subscription_id: type: - string - 'null' status: type: string enum: - active - past_due - paused - canceled collection_mode: type: string enum: - automatic - manual price_sid: type: string quantity: type: number addons: type: array items: type: object properties: product_sid: type: string price_sid: type: string paddle_item_id: type: - string - 'null' quantity: type: number status: type: string enum: - active - canceled required: - product_sid - price_sid - paddle_item_id - quantity - status currency: type: string current_period_starts_at: type: - string - 'null' current_period_ends_at: type: - string - 'null' next_billed_at: type: - string - 'null' paused_at: type: - string - 'null' scheduled_resume_at: type: - string - 'null' scheduled_change: type: - object - 'null' properties: action: type: string enum: - cancel - pause - resume effective_at: type: string resume_at: type: - string - 'null' required: - action - effective_at - resume_at canceled_at: type: - string - 'null' canceled_by: type: - object - 'null' properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} request_sid: type: - string - 'null' reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string deleted_at: type: - string - 'null' required: - sid - owner_user_sid - team_sid - paddle_subscription_id - status - collection_mode - price_sid - quantity - addons - currency - current_period_starts_at - current_period_ends_at - next_billed_at - paused_at - scheduled_resume_at - scheduled_change - canceled_at - canceled_by - created_at - updated_at - deleted_at result: type: object additionalProperties: {} meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta RemoveBillingSubscriptionAddonRequest: type: object description: Request body of `remove_billing_subscription_addon`. properties: price_sid: type: string minLength: 18 maxLength: 18 pattern: ^bl_pc_ description: The add-on price to remove; must be a live item on this subscription. quantity: type: integer minimum: 1 description: Units to give back (delta, mirrors add_billing_subscription_addon). Omit to drop the whole line. required: - price_sid responses: McpServerError: description: MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' McpClientError: description: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: Access token issued by gtm.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: Team scope for tokens that do not carry one. Ignored when the token already names a team.