Connect Paddle to ChatGPT: Manage Subscriptions and Customers via MCP

If you want to connect Paddle to ChatGPT so your AI agents can read revenue metrics, draft custom discounts, update customer payment details, and orchestrate subscription lifecycles, you need a Model Context Protocol (MCP) server. If your team uses Claude, check out our guide on connecting Paddle to Claude or explore our broader architectural overview on connecting Paddle to AI Agents.

Giving a Large Language Model (LLM) read and write access to a Merchant of Record (MoR) billing platform is a high-stakes engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server to translate LLM JSON arguments into Paddle's strictly typed billing models, or you use a managed infrastructure layer to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a secure MCP server for Paddle, connect it natively to ChatGPT, and execute complex billing workflows using natural language.

The Engineering Reality of the Paddle API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Paddle's API is exceptionally demanding because of its Merchant of Record architecture.

If you decide to build a custom MCP server for Paddle, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when exposing Paddle to an LLM:

The Product-Price-Subscription Hierarchy

Unlike simple SaaS billing APIs where you just pass a dollar amount to a checkout endpoint, Paddle enforces a strict catalog hierarchy. Products represent the logical item being sold. Prices are attached to Products and define the billing cycle, currency, and regional overrides (unit_price_overrides). Subscriptions are generated from Prices. If an LLM needs to upgrade a customer, it cannot simply "change the price to $50" - your MCP server must expose tools that allow the LLM to query the catalog, find the correct Price ID attached to the specific Product ID, and pass that exact Price ID to the subscription update endpoint.

Transactions vs. Adjustments

When an LLM attempts to process a refund, it will instinctively look for a "refund subscription" endpoint. In Paddle, refunds are modeled as Adjustments. You do not refund a subscription; you query the subscription's history to find the specific transaction_id, and then create a pending_approval adjustment against that transaction. Your MCP server must expose these discrete entities correctly, or the LLM will hallucinate invalid API requests.

Strict Merchant of Record Validation

Because Paddle assumes tax liability for every transaction, their API enforces strict geographic and entity validation. Creating a customer or updating a billing profile often requires mandatory postal codes mapped perfectly to the country_code for tax compliance. If the LLM generates a malformed address object, the API will reject it with a 422 error. Your MCP server must provide exact JSON Schema definitions for these nested requirements so the LLM knows how to structure the payload before executing the call.

Step 1: Generate a Paddle MCP Server

Truto abstracts away the complexity of the Paddle API by automatically mapping its resources into an MCP-compliant JSON-RPC server. You can generate a server URL for a specific integrated Paddle account using either the Truto UI or the API.

Method A: Via the Truto UI

If you prefer a visual interface, you can generate the MCP server directly from your dashboard:

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Paddle integration.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to specific methods like "read" or tags like "subscriptions").
6. Copy the generated MCP server URL. Treat this URL as a sensitive credential - it contains the authentication token required to route requests to your Paddle instance.

Method B: Via the API

For teams building programmatic AI workflows, you can generate the MCP server dynamically via a single API call. This scopes an MCP endpoint to a specific integrated account ID.

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ChatGPT Paddle Operations",
    "config": {
      "methods": ["read", "write"],
      "tags": ["subscriptions", "customers", "transactions"]
    }
  }'

The API returns a payload containing your unique server URL:

{
  "id": "mcp_8f9a2b1c",
  "name": "ChatGPT Paddle Operations",
  "config": { 
    "methods": ["read", "write"], 
    "tags": ["subscriptions", "customers", "transactions"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0j..."
}

Step 2: Connect the MCP Server to ChatGPT

Once you have the Truto MCP server URL, you must register it with your ChatGPT environment.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education accounts with Developer mode enabled, you can add the server directly via the interface:

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Ensure Developer mode is enabled.
3. Under the MCP servers / Custom connectors section, click Add new server.
4. Enter a descriptive name (e.g., "Paddle Billing Ops").
5. Paste the Truto MCP url copied from the previous step.
6. Click Save.

ChatGPT will immediately perform an initialization handshake with the Truto MCP server, requesting the full list of available Paddle tools and their JSON schemas.

Method B: Via Manual Config File

If you are orchestrating agents locally or running a headless ChatGPT integration via the OpenAI API, you can configure the MCP server using standard SSE (Server-Sent Events) transport. Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "paddle_billing": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0j..."
      ]
    }
  }
}

Hero Tools for Paddle

Truto exposes the entire Paddle API surface area as MCP tools. To ensure reliable LLM execution, each tool is injected with precise JSON schemas, descriptions, and automatic cursor pagination handling. Here are six high-leverage tools available for your AI agents.

1. list_all_paddle_subscriptions

This tool retrieves paginated lists of subscriptions. It is the primary entry point for AI agents auditing MRR, checking churn risk, or looking up customer status. The tool automatically returns active subscriptions by default, but the LLM can override the status filter to find paused or canceled records.

"Find all active subscriptions for the customer ID cus_01h8... and tell me their next billing dates."

2. get_single_paddle_customer_by_id

Retrieves the full customer entity, including their locale, marketing consent, and any custom metadata you have appended to the record. Agents use this tool to verify identity before executing sensitive billing changes.

"Look up customer cus_99x8... and verify if they are opted into marketing emails."

3. update_a_paddle_subscription_by_id

This powerful tool alters an active subscription without replacing it. The LLM can pass a new items array to upgrade or downgrade a tier, or modify the next_billed_at date. Truto handles the complex JSON structure required to specify proration_billing_mode alongside item changes.

"Upgrade the subscription sub_456 to the Pro tier price pri_789. Prorate the charge immediately."

4. paddle_subscriptions_cancel

Cancels an active subscription. By default, the API schedules the cancellation for the end of the current billing cycle. The LLM can use this tool and set effective_from to immediately if a hard churn is required.

"Cancel the subscription sub_123 immediately and confirm the cancellation timestamp."

5. create_a_paddle_adjustment

Because you cannot simply "refund a subscription", this tool is required for issuing money back. The LLM supplies a transaction_id, an action (refund or credit), and a reason. Paddle creates the adjustment in a pending_approval state for manual review, ensuring AI agents cannot unilaterally drain company funds without oversight.

"Create a full refund adjustment for transaction txn_001 because the customer requested a refund under the 30 - day guarantee."

6. create_a_paddle_discount

Generates a new promotional code in the Paddle catalog. The LLM must define the description, type (flat or percentage), and amount. This is highly effective for automated sales enablement agents drafting custom quotes.

"Create a 20% off discount code named 'Q4_ENTERPRISE_WIN' that expires at the end of the year."

Note: This is just a fraction of the available endpoints. For the complete inventory of Webhooks, Checkout Domains, FinOps Metrics, and Event Replays, view the full Paddle integration schema on Truto.

Workflows in Action

With the MCP server connected, ChatGPT can sequence multiple complex Paddle API calls together to solve actual business problems. Here are two real-world scenarios.

Scenario 1: Support Escalation and Refund

A user emails support asking for a refund and immediate cancellation. The support agent instructs ChatGPT to handle the administrative work.

"The user with customer ID cus_77b wants to cancel their subscription immediately and get a refund for their last payment. Process this for me."

1. Lookup Subscription: ChatGPT calls list_all_paddle_subscriptions filtering by customer_id=cus_77b to find the active subscription_id.
2. Find Transaction: ChatGPT calls list_all_paddle_subscription_history using the subscription_id to locate the most recent successful transaction_id.
3. Create Adjustment: ChatGPT calls create_a_paddle_adjustment passing the transaction_id, action="refund", and a reason string. Paddle queues this for approval.
4. Cancel Subscription: ChatGPT calls paddle_subscriptions_cancel with effective_from="immediately".

Result: The customer's subscription is hard-canceled, and a refund is queued in the Paddle dashboard. ChatGPT summarizes the completed actions for the support rep.

Scenario 2: Sales Enablement and Discounting

A sales rep is negotiating a deal and asks ChatGPT to prepare the billing infrastructure.

"I just closed the Acme Corp deal. Create a custom 15% discount code for them, then look up the Enterprise Product ID and tell me what the final monthly price will be."

1. Generate Discount: ChatGPT calls create_a_paddle_discount with type="percentage" and amount="15", storing the returned discount ID.
2. Lookup Catalog: ChatGPT calls list_all_paddle_products to find the Enterprise product.
3. Preview Pricing: ChatGPT calls create_a_paddle_pricing_preview passing the Enterprise item ID and the newly created discount ID.

Result: ChatGPT returns the exact generated discount code and the mathematically accurate final price, sourced directly from Paddle's internal pricing engine rather than relying on LLM math.

Execution Flow

sequenceDiagram
    participant User as ChatGPT User
    participant AI as ChatGPT
    participant Truto as Truto MCP Server
    participant Paddle as Paddle API
    
    User->>AI: "Refund txn_888 and cancel sub_999"
    AI->>Truto: Call create_a_paddle_adjustment
    Truto->>Paddle: POST /adjustments
    Paddle-->>Truto: Return pending adjustment
    Truto-->>AI: Result (JSON)
    AI->>Truto: Call paddle_subscriptions_cancel
    Truto->>Paddle: POST /subscriptions/sub_999/cancel
    Paddle-->>Truto: Return canceled subscription
    Truto-->>AI: Result (JSON)
    AI-->>User: "Done. Refund is pending approval and subscription is canceled."

Security and Access Control

Giving an AI agent access to your billing infrastructure requires strict governance. Truto MCP servers provide multiple layers of security to prevent LLM hallucinations from causing production damage.

• Method Filtering: Limit the server to safe operations. Setting config.methods: ["read"] ensures the LLM can list subscriptions and view customers, but categorically blocks it from creating discounts, processing refunds, or canceling accounts.
• Tag Filtering: Restrict access by resource domain. If you only want the AI to analyze pricing, set config.tags: ["prices", "products"] to hide all PII and transaction history.
• Require API Token Auth: By default, possessing the MCP URL grants access. For higher security, enable require_api_token_auth: true. This forces the MCP client to pass a valid Truto API bearer token in the headers, ensuring only authenticated systems can invoke the tools.
• Automatic Expiration: Use the expires_at field to create ephemeral MCP servers. If you are generating a server for a temporary AI contractor or a specific sandbox workflow, the server (and its underlying KV storage) will self-destruct at the specified ISO datetime.

Handling Rate Limits

Paddle enforces rate limits on API requests to protect their infrastructure. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors.

When the upstream Paddle API returns an HTTP 429 Too Many Requests error, Truto passes that exact error back to the caller (your MCP client). Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) according to the IETF specification.

The caller - whether that is ChatGPT, an orchestration framework like LangChain, or your custom agent architecture - is completely responsible for detecting the 429 response, inspecting the reset headers, and executing its own retry and backoff logic. Do not assume the integration layer will absorb traffic spikes for you.

Ship AI Integrations Faster

Building a custom MCP server for a complex Merchant of Record platform like Paddle requires deep domain expertise. You must handle complex payload construction, enforce strict JSON schemas, map discrete transactions to adjustments, and secure the endpoint against unauthorized execution.

Truto abstracts this away entirely. By deriving tool definitions directly from the integration's configuration and documentation, Truto provides a maintenance-free, fully managed MCP endpoint. When Paddle releases new API versions or alters their schema, the Truto MCP server updates dynamically, ensuring your LLM always has the correct context.

Stop writing boilerplate integration code. Let your AI agents securely interface with Paddle today.