API Information Hub

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 the four core things the API works with — Products, Customers, Invoices and Payments — and how they depend on each other. Read this first; the API Docs then cover each endpoint in detail.

How the pieces fit together

ResourceWhat it isDepends on
ProductSomething you sell — a physical item or a service.Ledger accounts
CustomerThe business or person you bill.—
InvoiceA request for payment, made up of line items.A customer and one or more products
PaymentMoney received against an invoice.An invoice

Build in this order

Products and customers come first — an invoice cannot be raised without both. Payments only exist once there is an invoice to settle.

Products

What you sell and bill for.

A product is anything you put on an invoice line item. For now every product is a service you deliver — service is the only type the API supports.

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.
  • Three ledger account ids — revenue, expense and inventory — that decide where the money is posted when the product is sold.
  • 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.

The three account ids are mandatory

revenue_account, expense_account and inventory_account must be set on a product. An invoice cannot be created against a product that is missing them.

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.

See Receive a Payment for the request and response.

Still to be confirmed

  • Which payment methods are available, and what each one means.
  • Where the deposit account ids come from — there is no accounts endpoint documented yet.
  • Refunds and reversing a payment recorded in error.

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.