Invoice reference

An invoice is a document you issue, hand to a customer, and wait to be paid. Wajub stores the lines, computes the totals, hosts the page the customer pays on, and records what has been settled. It does not chase anybody and it does not debit anything: the whole product is a document with a public URL and a running balance. Billing & subscriptions walks through that cycle. This page is the reference for the object itself.

Invoicing is a live-mode product gated on your plan. A sandbox key gets 403 This feature is only available in live mode., a plan without the feature gets 403 Invoicing is not available on your plan., and a plan with a lifetime cap gets 403 You have reached the maximum number of invoices for your plan. once you hit it. Only documents of type invoice count toward that cap.

The eight calls

Everything the API does with invoices is here. There is no PDF endpoint, no email endpoint, and no endpoint that charges a customer.

{id} is the id the API returns, the inv_ string. The internal UUID is accepted too, but nothing ever shows it to you, so use the inv_ one.

The invoice object

This is what every call returns. items is present whenever the invoice was loaded with its lines, which is all eight of them.

invoice_number is generated per team and resets every month: INV-, the year and month, then a four-digit counter. status is one of draft, sent, viewed, partial, paid, overdue, cancelled or refunded; the transitions between them and the webhooks they emit are on Billing & subscriptions.

Two fields are computed rather than stored. amount_due is always total minus amount_paid, floored at zero, so it never goes negative on an overpayment. amount_paid only moves through mark-paid or through a payment made on the hosted page.

Creating one

customer_name, items, invoice_date and currency are the four required fields. Everything else is optional, and the invoice is always created as draft whatever you send.

Each entry in items is its own object.

curl https://api.wajub.com/invoices \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Traoré & Fils",
    "customer_email": "amina@example.cm",
    "invoice_date": "2026-09-12",
    "payment_terms_days": 30,
    "currency": "XAF",
    "items": [
      { "name": "Consulting service", "quantity": 2, "unit_price": 150000, "tax_rate": 19.25 },
      { "name": "Onboarding", "quantity": 1, "unit_price": 100000, "discount_type": "percentage", "discount_value": 10 }
    ]
  }'

Creation is the only invoice call that honours Idempotency-Key. Replaying a create with the same key returns the first invoice instead of issuing a second one; replaying a send or a mark-paid runs again.

Amounts are whole numbers

Every money column on an invoice and on its lines is an integer. unit_price, subtotal, discount_amount, tax_amount, total and amount_paid all hold whole units of the currency, and there is no minor unit to fall back on: 150000 means one hundred and fifty thousand francs, not fifteen hundred.

How a line is computed

The line does its own arithmetic on every save, in this order. You send the first four values; the other four are computed and returned.

subtotal        = quantity × unit_price
discount_amount = discount_type = percentage  →  subtotal × discount_value / 100
                  discount_type = fixed       →  discount_value
                  otherwise                   →  0
taxable         = subtotal − discount_amount
tax_amount      = taxable × tax_rate / 100
total           = taxable + tax_amount

Tax is exclusive: it is added on top of the line, never carved out of it. And it is computed after the discount, so a 10% discount on a taxed line lowers the tax with it.

The invoice then sums the lines.

subtotal   = Σ (quantity × unit_price)
tax_amount = Σ line tax_amount
total      = subtotal + tax_amount
amount_due = max(0, total − amount_paid)

There is no invoice-wide discount

Discounts are per line. The create call also accepts has_global_discount, global_discount_type and global_discount_value, and those three do nothing at all: they are validated, then dropped before the write because no column carries them. They return no error either, so an invoice sent with a 15% global discount is stored at full price and looks like it worked.

Quotes and estimates

document_type accepts quote and estimate, and the document is created.

Paying in instalments

Set payment_type to split or milestone and pass the schedule. The hosted page then charges one entry at a time instead of the full balance.

The customer opens the invoice and sees the first entry that is not yet paid, charged at its amount capped by the remaining amount_due. When it settles, Wajub writes status: "paid", a paid_at and the transaction_uid back onto that entry, adds the amount to amount_paid, and moves the invoice to partial. The next visit offers the next entry. The invoice turns paid when amount_paid reaches the total, and once every entry is settled with a balance still outstanding the page falls back to charging the remainder in one go.

Listing

GET /invoices returns your live invoices, newest first, twenty-five at a time.

curl -G https://api.wajub.com/invoices \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -d status=overdue \
  -d customer_id=9d1f0c7a-4b2e-4f61-9d3a-7c8e5b21a940

The list is cursor-paginated on the default sort. Ask for a custom sort_by or sort_dir and it falls back to page numbers, because a cursor needs a stable order to walk.

Correcting an invoice

PUT /invoices/{id} replaces the document rather than patching it. customer_name, items, invoice_date and currency are required on every call, so send the whole invoice back with your change applied, not the change alone. The lines you send replace the previous ones outright: the old rows are deleted and recreated, which means every items[].id changes.

recurring_interval can be changed on update; the recurring_frequency alias accepted at creation is not, so use recurring_interval everywhere. Deleting is a soft delete: the row stays, the invoice number stays taken, and nothing returns it to you again.

Recording a payment you collected elsewhere

mark-paid is for money that arrived outside Wajub, in cash or by bank transfer. It moves the balance; it does not create a transaction and it does not settle anything.

An amount below the total adds to amount_paid and sets the status to partial. Call it again for the next instalment: the amounts accumulate, and the invoice flips to paid with a paid_at the moment they reach the total.

curl https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/mark-paid \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 178875, "payment_date": "2026-09-20" }'

A cancelled or refunded invoice refuses the call with 400 This invoice cannot be marked as paid.

Cancelling

POST /invoices/{id}/cancel sets the status to cancelled, stamps cancelled_at, and closes the public page. It accepts a reason and does not store it. Anything already paid, cancelled or refunded answers 400 This invoice cannot be cancelled.

Cancelling is the only exit for an invoice that has been partially paid, since editing and deleting are both closed by then. It does not refund what was collected: use refunds on the underlying payment for that.