How the Mocha QuickBill data model fits together, and the cross-cutting rules that apply to every endpoint — before you go looking up a specific one.
What this hub is for.
Welcome to the API Information Hub — your central resource for understanding and leveraging our platform's APIs. This hub is designed for developers, technical architects, and integration partners who are building robust, secure, and scalable applications on top of our services.
The sections below explain everything the API works with — Accounts, Products, Customers, Invoices, Payments, and the pricing components, plans and subscriptions behind recurring billing — and how they depend on each other. Read this first; the API Docs then cover each endpoint in detail.
| Resource | What it is | Depends on |
|---|---|---|
| Account | Where money is booked — income, expense or bank. A default set comes with your tenant. | — |
| Product | Something you sell — a physical item or a service. | An income account and an expense account |
| Customer | The business or person you bill. | — |
| Invoice | A request for payment, made up of line items. | A customer and one or more products |
| Payment | Money received against an invoice. | An invoice and a bank account |
| Pricing component | A reusable piece of pricing — a named amount you can put on any number of plans. | — |
| Pricing plan | What a customer is billed on. Built out of components, and attached to a product. | One or more pricing components |
| Subscription | A customer put on a plan for a product, billed every cycle. | A customer, a product and a plan attached to it |
Where the money gets booked.
An account is a bucket the money is booked into. A sale posts to an income account, a cost to an expense account, stock value sits in an inventory account, and money you receive lands in a bank account. This is how QuickBill keeps your accounting tracked without you doing anything about it.
Every tenant starts with a default set of accounts, ready to use. There is nothing to set up, and no endpoint to create or edit one — you only read the list and pick from it.
| Kind | Used by | Example names |
|---|---|---|
| Income | A product's revenue account — where a sale of it is booked. | Sale of Product Income, Service Income |
| Expense | A product's expense account — where its cost is booked. Which ones are eligible depends on the product's type. | Supplies & Materials - COGS, Advertising |
| Inventory | An inventory product's stock value. Only needed when the product's type is inventory. | Inventory Asset |
| Bank | The account a payment is deposited into. | Checking, Savings, Undeposited Funds |
The four endpoints and their responses are in Accounts.
What you sell and bill for.
A product is anything you put on an invoice line item. Its type says what kind it is — inventory for something you hold stock of, non_inventory for a good you do not track, and service for work you deliver.
| type | Also required |
|---|---|
inventory | A quantity, an inventory account, an expense account and an income account. |
non_inventory | An expense account. An income account is optional, and there is no quantity to send. |
service | An expense account. An income account is optional, and there is no quantity to send. |
expense_account has to be set. An inventory product needs three more on top — a quantity, an inventory account and an income account. Read the available ids from Accounts.See Create a Product for the request and response.
Who your invoices are issued to.
A customer is the business or person you bill. Every invoice is issued against exactly one customer, so the customer record has to exist before you can raise an invoice.
See Create a Customer for the request and response.
Billing a customer for products.
An invoice brings a customer and one or more products together into a request for payment. Each line item points at a product and carries a quantity and a price, which can override the product's default.
INV- numbers. A dedicated endpoint returns the next one in the sequence — call it, then use the value it gives you when you create the invoice. The format varies between accounts, so treat what you get back as an opaque string.See Create an Invoice for the request and response.
Settling what is owed.
A payment records money received from a customer and applies it to the invoices it settles. It is the last step in the chain: products go on an invoice, the invoice goes to a customer, and the payment closes it out.
A payment is not tied to a single invoice. When a customer sends one amount covering three invoices, you record one payment and split it across all three in the same call — you do not record it three times. Each entry names the invoice and the amount applied to it, and those amounts have to add up to what the customer actually sent.
Applying a payment reduces the invoice's balance. Pay the full balance and the invoice is settled; pay less and the remainder stays outstanding, so you can record the rest later against the same invoice. The customer's own open_balance moves with it, so you can show what a customer owes without adding up their invoices yourself.
status does not move when part of it is paid — it stays open until it is settled. To show whether money has come in, compare balance against amount instead of reading the status.Payments carry their own PMT- reference, which is not the same thing as the INV- number on the invoice being paid. One payment covering three invoices has a single payment reference and three invoice numbers behind it. Keep the two apart in your own records.
| What you need | Where it comes from |
|---|---|
| The account the money lands in | One of your bank accounts — Accounts. |
| How the money was paid | Cash, cheque, card and so on — Payment Methods. |
See Receive a Payment for the request and response.
Reusable pieces of pricing.
A pricing component is a named amount — a setup fee, a service charge, a discount. On its own it does nothing. It becomes real once you put it on a pricing plan.
A component is reusable. Create it once and put it on as many plans as you like — you do not create a separate setup fee for every plan that charges one. Change the component and every plan holding it reflects the change.
The dates live on the plan, not on the component. When you add a component to a plan you give it a start_date and an optional end_date — that is how long it is charged on that plan.
The fields, rules and error cases are in Pricing Components.
What a customer is actually billed on.
A plan is a bundle of components with a life span. It is what a subscription charges against.
| Part | What it does |
|---|---|
| Components | One or more pricing components, each with its own start and end date on this plan. |
| Effective and expiration dates | When the plan itself starts and stops. Leave the expiration out and it runs on with no end. |
| Price | Worked out from the components the plan holds. You never send it — it comes back on every response. |
A plan on its own is not sellable. You attach it to a product, and a product can be on several plans at once — monthly and yearly, say. That is the list a subscription picks from.
See Pricing Plans and Attach Plans to a Product.
Recurring billing on a plan.
A subscription puts a customer on one of a product's plans and bills them every cycle — monthly or yearly. It is the recurring counterpart to raising invoices by hand.
You send ids only — the customer, the product, the plan and the billing cycle. The price, the current plan, whether a change is an upgrade or a downgrade, and whether it applies now or at the next renewal are all resolved for you.
A subscription can start with a trial. Nothing is charged during it, and nothing is charged before the start date if you dated the subscription into the future.
| Change | When it lands |
|---|---|
| Upgrade | Straight away. Charge the mid-term difference by asking for proration, or leave it and it is not charged. |
| Downgrade | At the next renewal — never straight away, so a customer never loses paid-for time. |
| Either, during a trial | Straight away, and nothing is charged. |
Cancel immediately, or let the subscription run to the end of the term the customer has already paid for. Either way renewal invoices stop, and a cancellation can be reversed if it was a mistake.
Every endpoint, field and behaviour is in Subscriptions.
API key based authentication.
We support API key based authentication. Use a unique key per environment. API keys must be kept confidential and should not be exposed in frontend code.
The exact headers and a worked example are covered in Getting Started → Authentication.
Mandatory and recommended practices.
We take API security seriously. Here are our mandatory and recommended practices:
What changed and when.
Track all recent updates via our Developer Changelog: