canonical: https://jentic.com/apis/billsby.com/billsby-main

# Billsby API

Jentic publishes the only available OpenAPI specification for Billsby API, keeping it validated and agent-ready. The Billsby API is the public interface to the Billsby subscription billing platform, exposing 58 endpoints to manage customers, subscriptions, invoices, credit notes, products, plans, add-ons, allowances, and custom fields. It supports the full subscription lifecycle: creating customers and subscriptions, changing plans, refunding or writing off invoices, tracking counters and feature tags, and retrieving event logs. The base URL is templated by company domain, and authentication is by API key in the apikey header.

## For AI agents

Run a full subscription billing lifecycle - customers, plans, invoices, refunds, and add-ons - through the Billsby subscription billing platform.

## Scope

Does not handle card processing, sales-tax compliance, or general ledger accounting - use for subscription billing lifecycle, invoices, plans, and metered usage only.

## Capabilities

- Manage subscribers end-to-end: create customers, attach subscriptions, change plans, and cancel
- Charge a one-time fee on top of a subscription via POST `/customers/{customerId}/charge`
- Refund, reattempt, write off, or mark invoices as paid offline for accounts-receivable workflows
- Operate metered subscriptions by reading and updating counters per subscription
- Manage add-ons, allowances, and custom fields that sit on top of base plans
- Issue feature-tag updates to gate product capabilities by subscription
- Honour GDPR data clearance requests via PUT `/customers/{customerId}/gdpr`

## Use cases

### SaaS Subscription Lifecycle Automation

SaaS businesses need an end-to-end subscription engine - sign-up, plan upgrades, renewals, cancellations. The Billsby API exposes POST /subscriptions to create a new customer with subscription, PUT `/subscriptions/{subscriptionId}/changeplan` for upgrades, and DELETE `/subscriptions/{subscriptionId}` to cancel. Combined with /invoices and /creditnotes, it covers the full revenue cycle without a separate invoicing tool. Setup is typically three to five days for a first-time integration.

Example prompt: Create a new customer with a subscription on plan ID 1234 via POST /subscriptions, then change the plan to 5678 a week later via PUT `/subscriptions/{subscriptionId}/changeplan.`

### Metered Usage Billing

Usage-based pricing requires tracking counters per subscriber, with billing reflecting accumulated usage. The Billsby API exposes GET and POST on `/subscriptions/{subscriptionId}/counter` for reading and updating counters, and /allowances for plan-level inclusion limits. Together these support the standard pattern: increment the counter as usage accrues, and Billsby reflects the overage on the next invoice. Setup is typically two days plus testing.

Example prompt: For subscription ID 4567, increment the counter by 250 via POST `/subscriptions/{subscriptionId}/counter`, then verify via GET that the new value is reflected.

### Accounts Receivable and Refunds

Finance teams need to refund overcharged invoices, reattempt failed payments, and reconcile invoices paid offline. The Billsby API supports POST `/invoices/{invoiceId}/refund`, PUT `/invoices/{invoiceId}/reattempt`, PUT `/invoices/{invoiceId}/paidoffline`, and PUT `/invoices/{invoiceId}/writeoff` in one place, which avoids spreading these flows across multiple tools. Setup is one to two days for a finance ops integration.

Example prompt: Refund invoice ID 88991 in full via POST `/invoices/{invoiceId}/refund`, then verify via GET `/invoices/{invoiceId}` that the status reflects the refund.

### AI Agent Subscription Manager via Jentic

A customer-success AI assistant can change plans, refund invoices, and look up event logs from natural-language requests routed through Jentic. The Billsby API key sits in your Jentic One instance, so the agent never touches the raw secret. Search-load-execute through Jentic gets the agent live in under an hour, versus several days for direct integration.

Example prompt: Search Jentic for 'cancel a Billsby subscription', load the DELETE `/subscriptions/{subscriptionId}` schema, and execute it for the customer's subscription ID.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/subscriptions` | Create a customer with a new subscription |
| DELETE | `/subscriptions/{subscriptionId}` | Cancel a subscription |
| PUT | `/subscriptions/{subscriptionId}/changeplan` | Change a subscription's plan |
| POST | `/customers/{customerId}/charge` | Create a one-time charge on a customer |
| POST | `/invoices/{invoiceId}/refund` | Refund an invoice |
| PUT | `/invoices/{invoiceId}/reattempt` | Reattempt payment on a failed invoice |
| POST | `/subscriptions/{subscriptionId}/counter` | Update a metered usage counter |
| GET | `/subscriptions/{subscriptionId}/eventlogs` | Retrieve a subscription's event log |

## Key resources

- **Customers** — Create, list, update, and delete customers, plus payment-detail and GDPR operations
- **Subscriptions** — Create, list, change-plan, cancel, and update renewal dates for subscriptions; manage feature tags and event logs
- **Invoices** — List and retrieve invoices, plus refund, reattempt, write off, and mark paid-offline
- **Credit Notes** — List and reattempt company and customer credit notes
- **Products** — Create and manage products, plans, and pricing cycles
- **AddOns** — List add-ons and allowances on plans and subscriptions
- **CustomFields** — Create and update custom fields and customer responses

## Why Jentic

- **Setup:** Wiring the Billsby API by hand means attaching your API key to every call, resolving your companyDomain into the base path, and building each subscription, customer, and invoice path yourself. Through Jentic you install once, import Billsby from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Billsby puts the subscription, customer, and invoice ids in the URL path (`/subscriptions/{subscriptionId}/changeplan`, `/invoices/{invoiceId}/refund`), so a rule can pin your agent to one subscription or one invoice. You choose the operations it may call, so cancelling a subscription or refunding an invoice is not included unless you add them.
- **Credential handling:** Your Billsby API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'cancel a Billsby subscription' or 'refund an invoice', and Jentic returns the matching Billsby operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global payments and subscription billing platform
- **Recurly** — Subscription billing platform with comparable lifecycle features
- **Paddle** — Merchant-of-record subscription billing platform
- **Chargify (Maxio)** — Subscription billing with strong support for B2B SaaS metering

## FAQ

### Why is there no official OpenAPI spec for Billsby API?

Billsby does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Billsby API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Billsby API use?

The Billsby API uses an API key passed in the apikey header. You generate the key in the Billsby admin under Settings > Configuration > API keys and webhooks. When called via Jentic, the key is held in your Jentic One instance so the raw apikey value never reaches the agent's context.

### Can I change a customer's plan through the Billsby API?

Yes. PUT `/subscriptions/{subscriptionId}/changeplan` moves an existing subscription to a different plan, and PUT `/subscriptions/{subscriptionId}/renewaldate` adjusts the next renewal date. These two endpoints cover most upgrade and downgrade flows without needing to recreate the subscription.

### What are the rate limits for the Billsby API?

The OpenAPI spec does not declare explicit numeric rate limits. Billsby's standard practice is to throttle abusive callers and return 429 responses when limits are exceeded. The Jentic SDK retries on 429 with back-off, so high-volume jobs do not have to handle this manually.

### How do I refund an invoice through Jentic?

Search Jentic for 'refund a Billsby invoice', which surfaces POST `/invoices/{invoiceId}/refund.` Load the schema, supply the invoice ID and refund amount, and execute. The Python flow is: pip install jentic, then await client.search, await client.load, await client.execute.

### Does the Billsby API support metered or usage-based billing?

Yes. GET and POST on `/subscriptions/{subscriptionId}/counter` let you read and update usage counters per subscription, and /allowances exposes the plan-level inclusions that determine when overage billing applies.

### Can I limit what my agent is allowed to do with the Billsby API?

Yes. Because you run Jentic One yourself, your own rules decide which Billsby operations and which stored API key the agent may use, so operations like DELETE `/subscriptions/{subscriptionId}` to cancel or POST `/invoices/{invoiceId}/refund` are only available if you add them. Since Billsby puts the subscription and invoice ids in the URL path, such as PUT `/subscriptions/{subscriptionId}/changeplan` and `/invoices/{invoiceId}/refund`, a rule can pin the agent to a single subscription or invoice. Everything you do not explicitly allow stays off, and the agent calls only the endpoints you have scoped for it.