---
title: "Connect Billsby to ChatGPT: Automate Subscription Lifecycle & Plans"
slug: connect-billsby-to-chatgpt-automate-subscription-lifecycle-plans
date: 2026-04-20
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "A complete engineering guide to connecting Billsby to ChatGPT using an MCP server. Learn how to automate subscription management, invoices, and plan changes."
tldr: "Connect Billsby to ChatGPT via a managed MCP server to automate subscription lifecycles, handle failed payments, and manage customer invoices without writing custom integration code."
canonical: https://truto.one/blog/connect-billsby-to-chatgpt-automate-subscription-lifecycle-plans/
---

# 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](https://truto.one/connect-billsby-to-claude-manage-invoices-payment-reattempts/), or if you are building autonomous workflows, read about [connecting Billsby to AI Agents](https://truto.one/connect-billsby-to-ai-agents-sync-customer-profiles-usage-data/). Here is exactly how to do it using a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/).

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](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/) 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](https://truto.one/connect-affinity-to-chatgpt-manage-relationships-track-deals/), 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](https://truto.one/connect-attio-to-chatgpt-manage-relationships-and-sales-workflows/), 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`

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

**Response:**

```json
{
  "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..."
}
```

> [!NOTE]
> Truto does not retry or absorb rate limit errors from Billsby. When the Billsby API returns an HTTP 429, Truto passes that error to the caller and normalizes the upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). Your orchestration layer is responsible for retry and backoff logic.

## 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.

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

```mermaid
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](https://truto.one/zero-data-retention-mcp-servers-building-soc-2-gdpr-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](https://truto.one/integrations/detail/billsby).

*   **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](https://truto.one/connect-pylon-to-chatgpt-automate-support-issues-account-sync/) and [Ashby to Claude](https://truto.one/connect-ashby-to-claude-streamline-hiring-workflows-job-postings/)), OAuth token refresh lifecycles, and opaque API schemas, allowing you to focus entirely on designing the AI agent workflows that automate your billing operations.

> Want to connect your AI agents to Billsby and 100+ other SaaS platforms? Book a technical deep dive with our engineering team.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)