--- title: Billsby API Integration on Truto slug: billsby category: Subscription Platform canonical: "https://truto.one/integrations/detail/billsby/" --- # Billsby API Integration on Truto **Category:** Subscription Platform **Status:** Generally available ## Unified APIs ### Unified Subscription Management API - **Customers** — The customer represents a customer in Subscription Management. - **Invoices** — The invoice represents an invoice in Subscription Management. ## MCP-ready AI tools Truto exposes 53 tools for Billsby that AI agents can call directly. - **list_all_billsby_customers** — List customers by companyDomain, page, and pageSize in Billsby. Returns customerUniqueId, firstName, lastName, email, createdOn, status, phoneNumber, phoneNumberDialCode, phoneNumberDialCodeCountry, and billingAddress with addressLine1, addressLine2, city, country, state, and postCode. - **delete_a_billsby_customer_by_id** — Delete a customer by id in Billsby using company_domain and id. - **get_single_billsby_customer_by_id** — Get customer details by id and company_domain in Billsby. Returns companyCurrency, totalAmountPaid, averageAmountPerMonth, cardStatus, customerUniqueId, firstName, lastName, billingAddress, email, additionalEmail, phoneNumberDialCountry, phoneNumberDialCode, phoneNumber, isMarketingConsentGiven, createdOn, and status. - **update_a_billsby_customer_by_id** — Update customer details with companyDomain and id in Billsby. Returns customerId, firstName, lastName, billingAddress, email, additionalEmail, phoneNumber, isMarketingConsentGiven, createdOn, and uniqueId. - **create_a_billsby_customer** — Create a customer without a subscription in Billsby using companyDomain. Returns customerUniqueId assigned by Billsby. - **list_all_billsby_invoices** — Get a list of your company's invoices in Billsby using company_domain. Returns invoiceId, invoiceNumber, customerId, customerUniqueId, customerFullName, createdOn, amount, formattedAmount, status, and currency for each invoice. - **get_single_billsby_invoice_by_id** — Get invoice details by invoiceNumber in Billsby. Returns invoiceId, customerEmail, customerFirstName, customerLastName, invoiceNumber, createdOn, formattedAmount, amount, currency, status, subTotal, taxTotal, invoiceType, subscriptionUniqueId, planName, billingPeriodStart, billingPeriodEnd, units, companyName, companyEmail, companyTaxNumber, companyDomain, companyPhoneNumber, companyAddressLine1, companyCity, companyState, companyPostCode, companyCountry, brandingLogo, supportUrl, cardType, cardLast4Digits, cardExpiryMonth, cardExpiryYear, refundableAmount, footerCompanyName, footerAddressLine1, footerAddressCity, footerAddressState, footerAddressPostCode, footerAddressCountryISO3, footerEmailAddress, footerPhoneNumberDialCountry, footerPhoneNumberDialCode, footerPhoneNumber, supportContactHeading, supportContactContent, supportContactSupportUrl, supportContactSupportUrlButtonText, isAdvertEnabled, advertImageUrl, advertLinkToUrl. - **billsby_invoices_refund_invoice** — Refund an invoice for a customer in Billsby using company_domain, customer_unique_id, invoiceNumber, and amount. Returns invoiceNumber and the amount left to refund after the operation. - **billsby_invoices_reattempt_invoice_payment** — Reattempt a failed invoice payment using invoiceNumber and companyDomain in Billsby. Returns success status indicating the payment reattempt result. - **billsby_invoices_invoice_paid_offline** — Mark an invoice as paid offline in Billsby using company_domain and id. Returns success status indicating the invoice was updated. - **billsby_invoices_invoice_written_off** — Mark an invoice as written off in Billsby using company_domain and id. Returns success status. - **list_all_billsby_payments** — Get payment logs for a specific customer payment in Billsby using companyDomain, customerUniqueId, and invoiceNumber. Returns paymentLogId, createdOn, gatewayId, gatewayName, reference, paymentMethod, and status. - **list_all_billsby_add_ons** — Get a list of all add-ons for the company in Billsby. Requires company_domain. Returns addonId, name, description, and hasActiveLinkedPlans for each add-on. - **get_single_billsby_add_on_by_id** — Get details of a specific add-on in Billsby using companyDomain and id. Returns addonId, name, displayName, description, pricingModelType, featureTags, linked plans with planId and planName, and priceModels with frequency, currency, and tiered pricing. - **list_all_billsby_allowances** — Get a list of all allowances for the company in Billsby using company_domain. Returns allowanceId, name, description, and hasActiveLinkedPlans for each allowance. - **get_single_billsby_allowance_by_id** — Get allowance details by allowanceId in Billsby using companyDomain. Returns allowanceId, name, displayName, description, pricingModelType, counter info, featureTags, linked plans, and priceModels. - **list_all_billsby_subscription_add_ons** — Get add-ons for a specific subscription in Billsby using company_domain and id. Returns add-on id, name, isForced (optional or forced), status (active or not), and quantity (units if unit based). - **list_all_billsby_subscription_allowances** — Get allowances for a specific subscription in Billsby using company_domain and id. Returns id, name, isForced, status, usage, and includedUnits for each allowance. - **list_all_billsby_products** — List products for companyDomain in Billsby. Returns productId, name, visibility, billingCurrency, displayName, description, typeOfProduct, hasPlans, shipping and billing address requirements, marketing consent, numberOfPlans, alertEmail, and custom fields. - **get_single_billsby_product_by_id** — Get details of a specific product in Billsby using company_domain and id. Returns productId, name, visibility, billingCurrency, displayName, description, typeOfProduct, hasPlans, numberOfPlans, and various address and consent requirements. - **create_a_billsby_product** — Create a new product for your company in Billsby with company_domain. Returns productId, name, visibility, billingCurrency, displayName, description, typeOfProduct, hasPlans, isShippingAddressRequired, isShippingAddressValidationRequired, isBillingAddressValidationRequired, isAdditionalEmailRequired, isPhoneNumberRequired, isMarketingConsentRequired, numberOfPlans, and alertEmail. - **update_a_billsby_product_by_id** — Update product for your company in Billsby using company_domain and id. Returns productId, name, visibility, billingCurrency, displayName, description, typeOfProduct, hasPlans, isShippingAddressRequired, isShippingAddressValidationRequired, isBillingAddressValidationRequired, isAdditionalEmailRequired, isPhoneNumberRequired, isMarketingConsentRequired, numberOfPlans, and alertEmail. - **list_all_billsby_plans** — Get a list of plans for product_id in Billsby. Returns planId, name, displayName, description, pricingModelType, productId, cycles with cycleId and pricingModel details, visibility, featureTags, redirectUrl, hasActiveSubscription, and alertEmail. - **create_a_billsby_plan** — Create a new plan for a specific product in Billsby using company_domain and product_id. Returns planId, name, description, displayName, pricingModelType, productId, cycles with cycleId and pricing details, visibility, featureTags, redirectUrl, hasActiveSubscription, and alertEmail. - **update_a_billsby_plan_by_id** — Update a plan and cycle for your company in Billsby using company_domain, product_id, and id. Returns success status indicating the update result. - **create_a_billsby_cycle** — Create a cycle for a specific plan in Billsby using company_domain, product_id, and plan_id. Returns cycleId, planId, and pricingModel details including frequency, freeTrial, contractTerm, setupFeePrice, freeQuantity, billingDateType, fixedBillingDateDay, and proRateOption. - **list_all_billsby_subscriptions** — List subscriptions for companyDomain in Billsby. Returns subscriptionId, subscriptionUniqueID, customerId, customerUniqueId, customerEmail, customerFullname, planId, planName, productId, productName, createdOn, status, and isInFreeTrial fields. - **get_single_billsby_subscription_by_id** — Get subscription details by id and company_domain in Billsby. Returns fields including customerEmail, customerFullname, planName, productName, status, nextBillingAmountFormatted, nextBillingDate, and totalRevenueFormatted. - **create_a_billsby_subscription** — Create a new subscription and customer in Billsby with companyDomain, firstName, lastName, email, cycleId, Units, address, and cardDetails. Returns customerUniqueId and subscriptionUniqueId. - **billsby_subscriptions_change_plan** — Change the plan of a subscription in Billsby using company_domain and id. Requires planId, cycleId, customerUniqueId. Returns the result of the plan change operation. - **billsby_subscriptions_update_next_renewal_date** — Update next renewal date for a subscription in Billsby using company_domain and id. Returns an empty response on success. - **list_all_billsby_customer_subscriptions** — Get a list of subscriptions for a customer in Billsby using companyDomain and customerUniqueId. Returns subscriptionId, productId, productName, planId, planName, status, currency, revenue, nextBilling, createdOn, and units. - **update_a_billsby_customer_subscription_by_id** — Add a subscription to an existing customer in Billsby using companyDomain and id. Returns customerUniqueId and subscriptionUniqueId. Customer must not have other plans associated. - **delete_a_billsby_customer_subscription_by_id** — Cancel a subscription using subscriptionUniqueId and customerUniqueId in Billsby. Returns cancellation result. - **get_single_billsby_counter_value_by_id** — Get the current usage and last updated timestamp of a specific counter for a subscription in Billsby. Requires company_domain, subscription_unique_id, and id. - **update_a_billsby_counter_value_by_id** — Update counter value for a subscription in Billsby using companyDomain, subscriptionUniqueId, and counterId. Specify operationType (Increment, Decrement, Set) and value. Note: updates are queued and may not reflect instantly. - **create_a_billsby_one_time_charge** — Create a one-time charge for a specific customer in Billsby using companyDomain and customerUniqueId. The response returns true if the charge is successfully applied. - **update_a_billsby_clear_customer_datum_by_id** — Clear personal data for a customer in Billsby using companyDomain and id. Returns fields including companyCurrency, totalAmountPaid, averageAmountPerMonth, cardStatus, customerTaxRegNumber, customerUniqueId, firstName, lastName, billingAddress, email, additionalEmail, phoneNumberDialCountry, phoneNumberDialCode, phoneNumber, isMarketingConsentGiven, createdOn, uniqueId, and status with personal details replaced by 'gdpr'. - **get_single_billsby_subscription_shipping_address_by_id** — Get shipping address for a subscription in Billsby using company_domain and id. Returns addressLine1, addressLine2, state, city, country, and postCode fields. - **update_a_billsby_subscription_shipping_address_by_id** — Update subscription shipping address using company_domain and id. Returns success status indicating the update result. - **update_a_billsby_payment_card_token_by_id** — Update payment card token for a customer in Billsby using companyDomain and customerUniqueId. Returns updated payment card details including fullName, paymentCardtoken, expiryMonth, expiryYear, cardType, and last4Digits. - **get_single_billsby_payment_details_request_by_id** — Get a request to update payment details for a customer in Billsby using company_domain and customer_unique_id. Returns a success message if the request was sent successfully. - **list_all_billsby_customer_feature_tags** — Get all feature tags associated with a customer in Billsby using company_domain and id. Returns an array of feature tag strings including custom and subscribed plan tags. - **list_all_billsby_event_logs** — Get event logs for a subscription in Billsby using companyDomain and subscriptionUniqueId. Returns subscriptionEventLogId, type, createdOn, and eventData fields in the response. - **update_a_billsby_plan_order_by_id** — Update the order of plans for product_id in Billsby. Requires company_domain and product_id. Returns success status indicating the plans' new display order. - **list_all_billsby_subscription_feature_tags** — Get feature tags for a subscription in Billsby using company_domain and id. Returns subscriptionFeatureTags, the custom feature tags associated with the subscription but not the plan. - **create_a_billsby_subscription_feature_tag** — Add feature tags to subscriptions using companyDomain and subscriptionUniqueIds. Returns the result of the operation including success status. - **delete_a_billsby_subscription_feature_tag_by_id** — Delete a custom feature tag by tagname from subscriptions in Billsby. Requires company_domain and id. Optionally specify subsId to target a specific subscription. - **get_single_billsby_subscription_feature_tag_by_id** — Get feature tags split by plan and custom tags for a subscription in Billsby. Requires company_domain and id. Returns planFeatureTags (tags from the plan) and subscriptionFeatureTags (custom tags for the subscription). - **list_all_billsby_company_credit_notes** — Get a list of all company credit notes in Billsby using company_domain, page, and pageSize. Returns creditNoteId, creditNoteUniqueId, customerId, customerUniqueId, customerFullName, createdOn, amount, status, and currency. - **billsby_company_credit_notes_reattempt_credit_note_payment** — Reattempt a failed credit note payment for a specific credit note in Billsby using companyDomain and id. Returns success status indicating the payment reattempt result. - **list_all_billsby_customer_credit_notes** — Get customer credit notes for companyDomain and customerUniqueId in Billsby. Returns invoiceId, createdOn, invoiceNumber, amount, currency, linkedTransactionsCount, status, and paymentGatewayDisplayName. - **list_all_billsby_customer_invoices** — Get invoices for a specific customer in Billsby using company_domain and customer_unique_id. Returns invoiceId, createdOn, invoiceNumber, amount, refundableAmount, formattedAmount, currency, linkedTransactionsCount, and status. ## How it works 1. **Link your customer's Billsby account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Billsby.** The Proxy API is a 1-to-1 mapping of the Billsby API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Sync subscription data into your CRM or revenue platform** — Automatically map Billsby customers, subscriptions, and invoice history into your CRM so sales and RevOps teams see real-time MRR, plan tier, and churn status without switching tools. Truto's Unified Subscription Management API normalizes customer and invoice data across billing providers. - **Embed billing operations into your helpdesk or customer success tool** — Let support agents view invoice history, issue refunds, reattempt failed payments, or change subscription plans directly from your application's UI — no need to grant full Billsby admin access to every team member. - **Automate usage-based billing from your platform** — If your product tracks consumption metrics like API calls, messages sent, or storage used, push those values into Billsby's usage counters so your customers get accurate, itemized invoices at the end of each billing cycle without manual intervention. - **Drive lifecycle marketing from subscription events** — Pull event logs and subscription state changes from Billsby to trigger dunning sequences on failed payments, win-back campaigns on cancellations, or upsell flows when customers approach plan limits — all orchestrated from your marketing automation platform. - **Gate product features based on active subscription entitlements** — Use Billsby's feature tags to dynamically control which capabilities your end users can access. When a customer upgrades or downgrades in Billsby, your product analytics or feature-flagging tool instantly reflects the change. ## What you can build - **In-app billing sidebar for support agents** — Display a customer's invoices, subscription status, and payment history in a sidebar widget, with action buttons to refund an invoice, reattempt payment, mark an invoice as paid offline, or write it off — all powered by Billsby's invoice and subscription endpoints. - **Real-time usage counter sync** — Push consumption data from your platform into Billsby counters on an hourly or daily cadence using increment, decrement, or set operations so usage-based charges are always accurate. - **Automated plan change workflows** — Let your end users trigger subscription upgrades, downgrades, or plan swaps from within your product, calling Billsby's change-plan and update-subscription endpoints without redirecting to the Billsby dashboard. - **Feature-tag-driven access control** — Sync customer and subscription feature tags from Billsby into your feature flagging system to instantly enable or disable product capabilities based on the customer's active plan. - **GDPR-compliant PII erasure pipeline** — Orchestrate automated data deletion requests by calling Billsby's clear-customer-data endpoint to replace PII with anonymized values, keeping your compliance workflow seamless across all connected billing providers. - **Credit note and refund reconciliation dashboard** — Aggregate company and customer credit notes alongside invoice and payment data from Billsby into a unified finance view, enabling your users to reconcile outstanding credits and reattempt credit note payments without leaving your app. ## FAQs ### What authentication method does the Billsby integration use? Billsby uses API key authentication. Your end users provide their Billsby API key when connecting their account through Truto's auth flow. Truto securely stores and manages the credential so you never handle raw keys directly. ### Which Billsby resources are covered by Truto's Unified Subscription Management API? The Unified Subscription Management API maps Billsby's Customers and Invoices into a standardized schema. This means you can read and write customer and invoice data using the same unified endpoints you'd use for any other subscription platform Truto supports. ### Can I access Billsby-specific endpoints that aren't part of the Unified API? Yes. Beyond the unified Customers and Invoices resources, Truto exposes Billsby-native proxy endpoints for subscriptions, products, plans, cycles, add-ons, allowances, counters, feature tags, credit notes, payments, event logs, shipping addresses, one-time charges, payment card tokens, and GDPR data clearing — over 50 operations in total. ### Does Truto handle pagination for Billsby list endpoints? Yes. Truto automatically manages pagination across all list endpoints — customers, invoices, subscriptions, products, plans, payments, event logs, and more — so you receive complete result sets without implementing pagination logic yourself. ### Can I perform write operations like refunds and plan changes through the integration? Absolutely. The integration supports full write operations including creating and updating customers, creating subscriptions, changing plans, refunding invoices, reattempting payments, marking invoices as paid offline or written off, updating counter values, creating one-time charges, and managing subscription feature tags. ### How do I push usage data into Billsby for metered billing? Use the update_a_billsby_counter_value_by_id endpoint to increment, decrement, or set counter values for a given subscription. This lets you push consumption metrics from your platform into Billsby on any cadence — hourly, daily, or event-driven — so invoices reflect actual usage. ## Related reading - [Connect Billsby to ChatGPT: Automate Subscription Lifecycle & Plans](https://truto.one/blog/connect-billsby-to-chatgpt-automate-subscription-lifecycle-plans/) — A complete engineering guide to connecting Billsby to ChatGPT using an MCP server. Learn how to automate subscription management, invoices, and plan changes. - [Connect Billsby to Claude: Automate Invoices & Subscriptions via MCP](https://truto.one/blog/connect-billsby-to-claude-manage-invoices-payment-reattempts/) — Learn how to connect Billsby to Claude using a managed MCP server. Execute complex billing workflows, refund invoices, and manage subscriptions via chat. - [Connect Billsby to AI Agents: Sync Customer Profiles & Usage Data](https://truto.one/blog/connect-billsby-to-ai-agents-sync-customer-profiles-usage-data/) — Learn how to connect Billsby to AI agents using Truto. Generate AI-ready tools, bind them to LangChain or LangGraph, and automate complex billing workflows.