Connect Billsby to ChatGPT: Automate Subscription Lifecycle & Plans

You want to connect Billsby to ChatGPT so your AI agents can read customer subscriptions, issue refunds, and modify billing plans directly from a chat interface. If your team uses Claude, check out our guide on connecting Billsby to Claude, or if you are building autonomous workflows, read about connecting Billsby to AI Agents. Here is exactly how to do it using a Model Context Protocol (MCP) server.

Giving a Large Language Model (LLM) read and write access to your billing and subscription infrastructure is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom MCP server, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Billsby, connect it natively to ChatGPT, and execute complex billing workflows using natural language.

The Engineering Reality of Custom Billsby Connectors

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While Anthropic's open standard provides a predictable way for models to discover tools, implementing it against vendor APIs is painful.

As we've seen with other complex integrations like Affinity, if you decide to build a custom MCP server for Billsby, you are responsible for the entire API lifecycle. Billsby's API has specific quirks that make it particularly tricky to expose directly to an LLM without a translation layer.

The companyDomain Requirement

Almost every endpoint in the Billsby API requires the companyDomain as a path or query parameter. If you build a custom server, you must explicitly instruct the LLM to pass this value on every single request. If the model forgets or hallucinates the domain, the request fails. A managed MCP server automatically injects this context into the tool schema as a required property, forcing the LLM to provide it before executing the call.

Disparate Identity Keys

Billsby uses a strict distinction between a standard id, a customerUniqueId, and a subscriptionUniqueId. For example, refunding an invoice requires both the customerUniqueId and the invoiceNumber, but updating a subscription requires the id of the subscription itself. LLMs frequently mix these up if the tool descriptions are ambiguous. Just as we noted when connecting Attio to ChatGPT, exposing complex data models requires precise tool definitions, meaning you have to write massive JSON schemas for every endpoint to ensure the LLM understands exactly which ID goes where.

Nested Subscription Lifecycles

Changing a plan in Billsby is not a simple PATCH request to a user record. You must hit the specific /subscriptions/{company_domain}/{id}/plan endpoint and provide the new planId and cycleId. This requires the LLM to first query the available plans, extract the correct cycle ID, and then execute the change. Managing this multi-step orchestration requires highly accurate tool definitions.

Generating the Billsby MCP Server

Truto's MCP servers feature turns any connected integration into an MCP-compatible tool server. Tool generation is dynamic and documentation-driven. Rather than hand-coding tool definitions for Billsby, the platform derives them from the integration's resource definitions and schemas.

Each MCP server is scoped to a single connected Billsby account. The server URL contains a cryptographic token that encodes which account to use and what tools to expose.

You can generate this server in two ways.

Method 1: Via the Truto UI

For quick configuration and testing, you can generate the server directly from the dashboard:

1. Navigate to the integrated account page for your active Billsby connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (name, allowed methods, tags, expiry).
5. Copy the generated MCP server URL.

Method 2: Via the API

For programmatic provisioning, you can generate the server via a POST request. The API validates that the integration has tools available, generates a secure token, and returns a ready-to-use URL.

Endpoint: POST /integrated-account/:id/mcp

{
  "name": "Billsby Finance Agent MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["invoices", "subscriptions"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Response:

{
  "id": "mcp_abc123",
  "name": "Billsby Finance Agent MCP",
  "config": { 
    "methods": ["read", "write", "custom"], 
    "tags": ["invoices", "subscriptions"] 
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to ChatGPT

Once you have the server URL, you need to register it with your LLM client. Communication happens over HTTP POST with JSON-RPC 2.0 messages.

Method A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode (MCP support is gated behind this flag).
3. Under MCP servers / Custom connectors, click Add new server.
4. Set the Name (e.g., "Billsby Billing Ops").
5. Paste the Truto MCP URL into the Server URL field.
6. Save the configuration. ChatGPT will immediately connect and list the available Billsby tools.

Method B: Via Manual Config File (SSE)

If you are running a custom agent framework or a local client that uses configuration files, you can connect using the Server-Sent Events (SSE) transport. Use the official MCP SSE proxy utility to map the Truto HTTP endpoint to stdio if your client requires it, or connect directly via SSE.

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

graph TD
    A[ChatGPT / LLM Client] -->|JSON-RPC 2.0 over HTTP| B[Truto MCP Router]
    B -->|Token Validation| C[Distributed Key-Value Store]
    B -->|Tool Execution| D[Truto Proxy API]
    D -->|Standardized HTTP Request| E[Billsby API]
    
    classDef client fill:#2A2B32,stroke:#4A4B53,stroke-width:2px,color:#fff;
    classDef truto fill:#0F172A,stroke:#3B82F6,stroke-width:2px,color:#fff;
    classDef vendor fill:#F8FAFC,stroke:#CBD5E1,stroke-width:2px,color:#0F172A;
    
    class A client;
    class B,C,D truto;
    class E vendor;

Security and Access Control

Exposing billing infrastructure to an AI model requires strict boundaries. To help build secure, compliant AI agents, Truto provides several mechanisms to lock down the MCP server:

• Method filtering: Restrict the MCP server to read-only operations by passing config.methods: ["read"]. This allows the LLM to query invoices and subscriptions but prevents it from issuing refunds or changing plans.
• Tag filtering: Scope the server to specific resource types using config.tags. For example, an agent focused strictly on customer support might only need the customers and invoices tags, keeping plans and products entirely out of context.
• Token auth: For enterprise environments, set require_api_token_auth: true. This forces the MCP client to provide a valid Truto API token in the Authorization header. Possession of the MCP URL alone is no longer sufficient.
• Ephemeral access: Use the expires_at field to generate temporary credentials. The platform automatically schedules cleanup routines that invalidate the token at the specified time, ensuring contractor or temporary agent access is automatically revoked.

Billsby Tool Inventory

Truto automatically maps Billsby's API endpoints into callable MCP tools. Here is how they are structured.

Hero Tools

These are the most high-value tools for automating billing workflows.

list_all_billsby_customer_subscriptions

• Description: Retrieves a list of all active, past due, or cancelled subscriptions for a specific customer in Billsby using companyDomain and customerUniqueId.
• Example Prompt: "Pull all active subscriptions for customer ID cust_8923 and tell me what plan they are currently on."

billsby_invoices_refund_invoice

• Description: Issues a refund for a specific invoice. Requires company_domain, customer_unique_id, and invoiceNumber.
• Example Prompt: "Customer cust_8923 accidentally renewed. Please refund invoice INV-40921 entirely."

billsby_subscriptions_change_plan

• Description: Changes the plan of an existing subscription. Requires company_domain, id (subscription ID), planId, and cycleId.
• Example Prompt: "Upgrade subscription sub_9912 to the Enterprise plan on the annual billing cycle."

billsby_invoices_reattempt_invoice_payment

• Description: Forces a reattempt of a failed invoice payment using invoiceNumber and companyDomain.
• Example Prompt: "The customer updated their credit card. Force a payment reattempt on failed invoice INV-3310."

create_a_billsby_one_time_charge

• Description: Creates an ad-hoc one-time charge for a specific customer. Requires companyDomain and customerUniqueId.
• Example Prompt: "Add a one-time setup fee of $500 to customer cust_1044's account."

Full Tool Inventory

Here is the complete inventory of additional Billsby tools available. For full schema details, visit the Billsby integration page.

• list_all_billsby_payments: Get payment logs for a specific customer payment in Billsby.
• billsby_company_credit_notes_reattempt_credit_note_payment: Reattempt a failed credit note payment.
• billsby_invoices_invoice_written_off: Mark an invoice as written off in Billsby.
• billsby_invoices_invoice_paid_offline: Mark an invoice as paid offline.
• list_all_billsby_customer_invoices: Get invoices for a specific customer.
• get_single_billsby_subscription_feature_tag_by_id: Get feature tags split by plan and custom tags for a subscription.
• billsby_subscriptions_update_next_renewal_date: Update next renewal date for a subscription.
• list_all_billsby_subscription_feature_tags: Get feature tags for a subscription.
• delete_a_billsby_subscription_feature_tag_by_id: Delete a custom feature tag by tagname.
• list_all_billsby_company_credit_notes: Get a list of all company credit notes.
• list_all_billsby_customer_credit_notes: Get customer credit notes for a specific customer.
• update_a_billsby_plan_order_by_id: Update the order of plans for a product.
• create_a_billsby_subscription_feature_tag: Add feature tags to subscriptions.
• update_a_billsby_payment_card_token_by_id: Update payment card token for a customer.
• get_single_billsby_payment_details_request_by_id: Get a request to update payment details.
• list_all_billsby_customer_feature_tags: Get all feature tags associated with a customer.
• list_all_billsby_event_logs: Get event logs for a subscription.
• update_a_billsby_clear_customer_datum_by_id: Clear personal data for a customer (GDPR/CCPA compliance).
• get_single_billsby_subscription_shipping_address_by_id: Get shipping address for a subscription.
• update_a_billsby_subscription_shipping_address_by_id: Update subscription shipping address.
• update_a_billsby_counter_value_by_id: Update counter value for a subscription.
• get_single_billsby_counter_value_by_id: Get the current usage and last updated timestamp of a specific counter.
• delete_a_billsby_customer_subscription_by_id: Cancel a subscription.
• create_a_billsby_subscription: Create a new subscription and customer.
• update_a_billsby_customer_subscription_by_id: Add a subscription to an existing customer.
• get_single_billsby_subscription_by_id: Get subscription details by id.
• billsby_invoices_customer_invoices: Get invoices for a specific customer.
• list_all_billsby_subscriptions: List all subscriptions for the company.
• create_a_billsby_customer: Create a customer without a subscription.
• update_a_billsby_customer_by_id: Update customer details.
• create_a_billsby_custom_field: Create a new custom field.
• update_a_billsby_custom_field_by_id: Update an existing custom field.
• list_all_billsby_custom_fields: Get a list of all custom fields.
• create_a_billsby_cycle: Create a cycle for a specific plan.
• list_all_billsby_plans: Get a list of plans for a product.
• update_a_billsby_plan_by_id: Update a plan and cycle.
• create_a_billsby_plan: Create a new plan for a specific product.
• list_all_billsby_products: List products for the company.
• create_a_billsby_product: Create a new product.
• get_single_billsby_product_by_id: Get details of a specific product.
• update_a_billsby_product_by_id: Update product details.
• list_all_billsby_subscription_add_ons: Get add-ons for a specific subscription.
• list_all_billsby_subscription_allowances: Get allowances for a specific subscription.
• get_single_billsby_allowance_by_id: Get allowance details by allowanceId.
• get_single_billsby_add_on_by_id: Get details of a specific add-on.
• list_all_billsby_allowances: Get a list of all allowances for the company.
• list_all_billsby_add_ons: Get a list of all add-ons for the company.
• get_single_billsby_customer_by_id: Get customer details by id.
• delete_a_billsby_customer_by_id: Delete a customer.
• list_all_billsby_invoices: Get a list of your company's invoices.
• get_single_billsby_invoice_by_id: Get invoice details by invoiceNumber.
• list_all_billsby_customers: List customers by companyDomain.

Workflows in Action

Giving an LLM access to these tools allows it to orchestrate multi-step billing operations autonomously. Here is how real-world scenarios play out.

Scenario 1: The Downgrade and Refund Support Ticket

A customer writes into support saying they meant to downgrade to the "Basic" plan before their renewal hit, and they want a refund for the difference.

User Prompt: "Customer cust_5099 requested a downgrade to the Basic plan. They just renewed on the Pro plan yesterday. Please downgrade their subscription, find the latest invoice, and issue a full refund."

Agent Execution:

1. Calls list_all_billsby_customer_subscriptions using cust_5099 to find the active subscription ID.
2. Calls list_all_billsby_plans to find the planId and cycleId for the "Basic" plan.
3. Calls billsby_subscriptions_change_plan using the subscription ID, new plan ID, and cycle ID to execute the downgrade.
4. Calls list_all_billsby_customer_invoices for cust_5099 to locate the most recent invoice number.
5. Calls billsby_invoices_refund_invoice using the invoice number to process the refund.

Result: The agent replies confirming the subscription has been downgraded to Basic and the latest invoice has been successfully refunded, saving the support rep 10 minutes of clicking through the billing UI.

Scenario 2: The Failed Payment Rescue

Finance operations is reviewing a list of accounts that entered the dunning process due to expired credit cards. The customer just updated their card on file via the customer portal.

User Prompt: "Customer cust_8112 just updated their payment method. Find their failed invoices and reattempt the charges."

Agent Execution:

1. Calls list_all_billsby_customer_invoices for cust_8112.
2. Filters the returned data in-memory to find invoices with a status indicating payment failure.
3. Iterates over the failed invoices and calls billsby_invoices_reattempt_invoice_payment for each invoiceNumber.

Result: The agent reports back that it found two failed invoices and successfully triggered the payment reattempt for both.

Summary

Connecting Billsby to ChatGPT using a managed MCP server removes the friction of building and maintaining custom integration code. You bypass the complexities of pagination (a common hurdle we've covered when connecting Pylon to ChatGPT and Ashby to Claude), OAuth token refresh lifecycles, and opaque API schemas, allowing you to focus entirely on designing the AI agent workflows that automate your billing operations.