API Information Hub | Mocha QuickBill Developer

APIv1

API Information Hub

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.

Overview

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.

How the pieces fit together

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

Build in this order

Accounts are already there, so read them and then create your products and customers — an invoice cannot be raised without both. Payments only exist once there is an invoice to settle. For recurring billing, the chain is longer: components, then a plan built from them, then the plan attached to a product, then a subscription that puts a customer on it.

Accounts

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.

You do not create them

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.

Full accounting is a separate product

These accounts are a feature of Mocha's accounting product. If you purchase it later you get the whole thing — your own chart of accounts, ledgers and reporting. Until then the defaults are all you need, and four small read endpoints are exposed for exactly one reason: so you can create a product and record a payment without owning the accounting product.

Which account goes where

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

Read the ids, never hard-code them

Account ids differ from one tenant to the next, so a value that works in your tenant will be wrong in your customer's. Fetch the list at runtime, show the names, and send back the id your user picked.

Expense accounts are filtered by product type

An inventory product's stock is held until it sells, so its cost belongs in cost of goods sold — and that is all the expense list offers for it. A service or non-inventory good holds nothing, so its cost can go to any expense account. Ask for the list with the type you are about to create.

The four endpoints and their responses are in Accounts.

Products

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.

The type decides what else you send

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.

What a product carries

A name and an optional SKU you can reference it by.
A description, and tags you can group and filter by.
Account ids that decide where the money is posted when the product is sold — which ones depends on the type.
Pricing fields, which the server fills with defaults if you do not send them. An invoice line carries its own rate, so the price on the product is not what gets billed.

An expense account is always mandatory

Whatever the type, 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.

Customers

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.

What a customer carries

Contact details — display name, email and phone — used when an invoice is emailed out.
Optional contact persons for organisations with more than one billing contact.
Custom fields, so you can carry your own identifiers alongside ours.

One customer, many addresses

A customer carries a billing address and a shipping address. Both are copied onto every invoice you raise for them, so save them once here rather than asking for them again at invoice time.

See Create a Customer for the request and response.

Invoices

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.

What an invoice carries

The customer it is issued to, and the line items being billed.
Dates — issue date, due date, and payment terms.
Totals, taxes and any discount applied.
A status that moves as the invoice is sent, paid or voided.

Void rather than delete

Once an invoice has been sent, voiding it keeps the record and its number intact for your audit trail. Deleting removes it outright — only do that for invoices raised in error.

Invoice numbers are handed to you

Do not invent your own 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.

Payments

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.

What a payment carries

The customer the money came from.
The account it was deposited into — your bank or cash account. This is what puts the money on your books.
How it was paid, and the date it was received.
Its own reference number, separate from any invoice number.
A list of what it is applied to — one entry per invoice, each with the amount going to it.

One payment can settle several invoices

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.

What it does to the invoice

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.

A part-paid invoice still reads as open

An invoice's 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.

Read the invoice back to confirm

The payment call returns an acknowledgement, not the updated invoice — no balance, no new status. If your application shows whether an invoice is paid, fetch the invoice again after recording the payment rather than assuming it went to zero.

Two numbers, two sequences

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.

Both numbers are handed to you

Neither sequence is yours to invent. Invoice numbers come from one endpoint and payment references from another — call the right one, use what it returns, and the numbering stays consistent with what your accountant sees in the web app. The two endpoints wrap their answer differently, so read each one's response as documented rather than sharing a helper.

Two lookups before you record one

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.

Both are per tenant

Read the two lists at runtime and send the ids your user picked. A value that works in your own tenant is not guaranteed to mean the same thing in your customer's.

See Receive a Payment for the request and response.

Pricing Components

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.

One component, many plans

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.

A component has no dates of its own

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 same component can run for different dates on two plans

Put your setup fee on a monthly plan for its first month, and on a yearly plan for its first three — same component, two different windows. That is why the dates are not stored on the component itself.

The component's window has to sit inside the plan's

A component cannot start before its plan starts, or run on after the plan ends.

The fields, rules and error cases are in Pricing Components.

Pricing Plans

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.

What a plan carries

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 is attached to a product

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.

Attaching replaces, it does not add

Setting a product's plans replaces whatever was there. Always send the full list the product should end up on.

See Pricing Plans and Attach Plans to a Product.

Subscriptions

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.

What you send, and what the service works out

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.

Trials

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.

Changing the plan mid-term

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.

Preview before you commit

A read-only call tells you what a plan change will cost before you make it, using the same rules — so what you show the customer is what they will be charged.

Ending one

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.

Invoices yes, payments no

Subscriptions raise invoices but never record a payment. Collecting the money is a separate step — Receive a Payment or your own gateway.

Every endpoint, field and behaviour is in Subscriptions.

Authentication Methods

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.

Tips

Always use HTTPS to prevent token leakage.
Rotate keys periodically.
Use different keys for different applications and teams.

Security Guidelines

Mandatory and recommended practices.

We take API security seriously. Here are our mandatory and recommended practices:

All endpoints use TLS (HTTPS) only.
API requests are authenticated and auditable.
Sensitive data (e.g. PAN, GST, email) is encrypted at rest and masked in logs.

API Changelog

What changed and when.

Track all recent updates via our Developer Changelog:

New endpoints — notification for newly released endpoints.
Backend and documentation updates.
Breaking changes — advance warning for structural changes.

Start here

Getting Started

Authentication, base URL and your first request.

Reference

API Docs

Every endpoint with its fields, examples and responses.

Invoicing

Subscription Billing

Invoice Templates

Powerful Invoicing for Modern Businesses