Connect Billsby to AI Agents: Sync Customer Profiles & Usage Data

You want to connect Billsby to your AI agents so they can autonomously read customer subscriptions, issue refunds, and modify billing plans directly from a chat interface or background worker. If your team uses ChatGPT, check out our guide on connecting Billsby to ChatGPT, or if you prefer Anthropic's ecosystem, read about connecting Billsby to Claude. Building an autonomous agent that can safely interact with billing infrastructure requires more than a simple API wrapper. You need structured tool schemas, strict error handling, and predictable execution.

Giving a Large Language Model (LLM) read and write access to your billing infrastructure is a significant engineering challenge. You either spend weeks building, hosting, and maintaining custom API wrappers, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to use Truto's /tools endpoint to generate AI-ready tools for Billsby, bind them natively to your LLM using frameworks like LangChain or LangGraph, and execute complex billing workflows autonomously.

The Engineering Reality of Custom Billsby Connectors

A custom integration layer is essentially a translation service that converts an LLM's tool calls into standard REST API requests. While modern models are excellent at generating JSON payloads, implementing those payloads against vendor APIs is highly error-prone.

If you decide to build a custom integration layer for Billsby, you are responsible for the entire API lifecycle. You must write and maintain massive JSON schemas for every endpoint you want the LLM to access. You also have to handle a few very specific API quirks that break naive agent implementations.

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 inject this into every LLM prompt or hardcode it into your server logic. If the LLM hallucinates the domain or forgets to include it, the API call fails immediately. Truto normalizes this by exposing the companyDomain as a required property in the tool schema, forcing the LLM to provide it based on its system instructions.

Customer vs. Subscription Hierarchy

Billsby enforces a strict separation between customers and subscriptions. A customer record can exist without an active subscription, but a subscription always requires a customer. An AI agent must understand this relational hierarchy. It must know to query the customer endpoint to retrieve a customerUniqueId before it can successfully query the subscription endpoints. If you hand-code these tools, you have to write complex prompt instructions to teach the LLM this dependency. Truto's tool descriptions automatically provide the necessary context to the LLM.

Rate Limits and Pagination

As we've noted when connecting Pylon to AI agents, LLMs are notoriously bad at guessing pagination cursors. If a customer has 500 invoices, you cannot dump the entire array into the LLM's context window. Billsby enforces rate limits to protect its infrastructure. Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Note that Truto does not automatically retry HTTP 429 errors - it passes them to the caller. Your agent executor must implement its own exponential backoff strategy when interacting with these tools.

Generating AI-Ready Tools with Truto

Instead of writing integration code, Truto provides all the resources defined on an integration as ready-to-use tools. Every integration on Truto is represented as a comprehensive JSON object mapping the underlying product's API endpoints to standard resources and methods.

When you call the GET /integrated-account/<id>/tools endpoint, Truto dynamically generates tool definitions complete with descriptions, query schemas, and body schemas. These definitions update automatically whenever the underlying API or your Truto configuration changes.

Billsby Tool Inventory

Truto exposes the entire Billsby API surface to your AI agents. We have categorized these into hero tools - the high-value operations you will use most often - and the full inventory.

billsby_subscriptions_change_plan

• Description: Change the plan of an active subscription in Billsby. Requires company_domain, id (subscription ID), planId, and cycleId.
• Example Prompt: "Upgrade customer sub_12345 to the Enterprise plan (planId: 987, cycleId: 654) for the acmecorp domain."

billsby_invoices_refund_invoice

• Description: Issue a refund for a specific invoice. Requires company_domain, customer_unique_id, and invoiceNumber.
• Example Prompt: "Refund invoice INV-001 for customer cust_999 because they accidentally double-paid."

create_a_billsby_subscription

• Description: Create a new subscription and customer record simultaneously. Accepts customer details, address, and plan configuration.
• Example Prompt: "Create a new subscription for Jane Doe (jane@example.com) on the Pro plan."

billsby_invoices_reattempt_invoice_payment

• Description: Manually trigger a payment reattempt for a failed invoice using invoiceNumber and companyDomain.
• Example Prompt: "The customer updated their credit card. Reattempt the payment for invoice INV-404."

list_all_billsby_customer_invoices

• Description: Retrieve a paginated list of all invoices for a specific customer. Essential for billing history queries.
• Example Prompt: "Pull all invoices for customer cust_123 and calculate their total spend this year."

update_a_billsby_counter_value_by_id

• Description: Update the value of a metered billing counter. Requires companyDomain, subscriptionUniqueId, and counterId.
• Example Prompt: "Add 50 API calls to the usage counter (counterId: 12) for subscription sub_777."

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.
• 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.
• billsby_invoices_invoice_paid_offline: Mark an invoice as paid offline.
• get_single_billsby_subscription_feature_tag_by_id: Get feature tags split by plan and custom tags.
• billsby_subscriptions_update_next_renewal_date: Update the 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 domain.
• 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.
• 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.
• create_a_billsby_one_time_charge: Create a one-time charge for a specific customer.
• get_single_billsby_counter_value_by_id: Get the current usage of a specific counter.
• delete_a_billsby_customer_subscription_by_id: Cancel a subscription.
• list_all_billsby_customer_subscriptions: Get a list of subscriptions for a 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 a company domain.
• 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 a company domain.
• 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 a product.
• 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.
• list_all_billsby_add_ons: Get a list of all add-ons.
• get_single_billsby_customer_by_id: Get customer details by id.
• delete_a_billsby_customer_by_id: Delete a customer by id.
• 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 all customers.

Building Multi-Step Workflows

Connecting these tools to an LLM requires an orchestration framework. While this approach works with CrewAI, Vercel AI SDK, and others, we will demonstrate a LangGraph implementation using the @truto/truto-langchainjs-toolset package. This package automatically fetches the tool schemas from Truto and binds them to your model.

import { TrutoToolManager } from '@truto/truto-langchainjs-toolset';
import { ChatOpenAI } from '@langchain/openai';
import { createReactAgent } from '@langchain/langgraph/prebuilt';
 
// 1. Initialize the Truto Tool Manager
const toolManager = new TrutoToolManager({
  trutoToken: process.env.TRUTO_API_KEY,
  integratedAccountId: process.env.BILLSBY_ACCOUNT_ID,
});
 
// 2. Fetch all available Billsby tools dynamically
const tools = await toolManager.getTools();
 
// 3. Initialize the LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4o',
  temperature: 0,
});
 
// 4. Create the LangGraph ReAct agent
const agent = createReactAgent({
  llm,
  tools,
});
 
// 5. Execute the workflow
const result = await agent.invoke({
  messages: [
    {
      role: 'system',
      content: 'You are a billing assistant. Our Billsby companyDomain is "acmecorp". Always use this domain when interacting with Billsby tools.',
    },
    {
      role: 'user',
      content: 'Find customer johndoe@example.com. If they have any unpaid invoices, reattempt the payment.',
    },
  ],
});
 
console.log(result.messages[result.messages.length - 1].content);

sequenceDiagram
    participant User
    participant Agent as LangGraph Agent
    participant Truto as Truto Proxy API
    participant Billsby as Billsby API

    User->>Agent: "Refund invoice #12345"
    Agent->>Truto: Call billsby_invoices_refund_invoice<br>(invoiceNumber: 12345)
    Truto->>Billsby: POST /api/v1/rest/core/company/...
    Billsby-->>Truto: 200 OK (Refund Processed)
    Truto-->>Agent: Normalized JSON Response
    Agent-->>User: "Invoice #12345 has been refunded."

Workflows in Action

To understand the value of exposing the entire Billsby API to an agent, consider how it handles complex, multi-step customer support requests.

Scenario 1: Automated Payment Recovery

Support teams waste hours manually chasing failed payments. An AI agent can handle the triage and recovery autonomously.

"Customer Alice Smith just emailed saying she updated her credit card. Find her account, check for failed invoices, and reattempt the charge."

Step-by-Step Execution:

1. The agent calls list_all_billsby_customers with a search query for "Alice Smith" to retrieve her customerUniqueId.
2. It calls list_all_billsby_customer_invoices using that ID, filtering the results to find invoices with an "unpaid" or "failed" status.
3. It extracts the invoiceNumber from the failed invoice.
4. It calls billsby_invoices_reattempt_invoice_payment to trigger the charge against the newly updated card.

The user receives a confirmation message stating the exact invoice number that was successfully processed.

Scenario 2: Metered Usage Adjustments

For companies using usage-based billing, sales or support reps frequently need to apply manual credits or adjust counters based on customer disputes.

"Add 500 free API credits to TechCorp's main subscription counter to resolve their downtime complaint."

Step-by-Step Execution:

1. The agent calls list_all_billsby_customers to find TechCorp.
2. It calls list_all_billsby_customer_subscriptions to identify their active subscription and retrieve the subscriptionUniqueId.
3. It calls get_single_billsby_counter_value_by_id to read the current balance of the API credits counter.
4. It calculates the new total and calls update_a_billsby_counter_value_by_id with the adjusted value.

The agent confirms the new counter balance without the support rep ever logging into the Billsby dashboard.

Moving Beyond Basic API Wrappers

As we've seen with other complex integrations like Ashby, writing custom integration code for billing APIs is a massive liability. Every time Billsby updates an endpoint, adds a query parameter, or deprecates a field, your hardcoded LLM tools break. By relying on Truto's dynamically generated tools, your agent architecture remains decoupled from the underlying API changes.

You pass the integrated account ID, Truto provides the schemas, and the LLM handles the orchestration. This allows your engineering team to focus on building better agent logic rather than maintaining endless integration wrappers.