Statuses
Every change sends
invoice.updated. Read status off the invoice.
What an invoice tells you
total,amountPaidandamountDue.amountDue = total − amountPaid − amountCredited − balanceApplied, so credit notes and the customer’s balance both lower what is left to collect.lines, one per fee, usage charge, proration or setup fee, each with its own tax.hostedUrl, the page where the customer sees and pays it, andinvoicePdfUrl.billingReason:subscription_create,subscription_cycle,subscription_update,subscription_threshold,manualorcredit_purchase.payment, the latest payment attempt, with why it failed when it did.
GET /invoices?subscriptionId=sub_….
Invoice numbers
Invoices are numbered in one unbroken sequence (such asINK-0001, INK-0002), as Nigerian tax rules require. Set the prefix under Billing settings → Invoicing. Credit notes have their own sequence.
VAT
Turn VAT on under Billing settings → Tax once your business is VAT registered. You never type a rate: Bouclay knows the rate for your country (7.5% in Nigeria) and applies it by each product’s tax category.- VAT included or added on top. By default your prices include VAT, as most Nigerian prices do: a ₦10,000 price stays ₦10,000 to the customer, and the invoice shows ₦9,302.33 plus ₦697.67 VAT. Choose “added on top” instead and ₦10,000 becomes ₦10,750. Set it for your business, or per price.
- Tax categories. Each product is
standard,zero_rated(0% VAT) orexempt(no VAT). - Exports. Sales to customers whose billing address is outside your country are zero-rated, and the invoice says so.
- On the invoice. A registered business’s invoices are titled “Tax invoice” and show your TIN and the customer’s.
- Frozen rates. The rate is saved on each line, so a later rate change never rewrites an issued invoice.
One-off invoices
Bill something outside a subscription, such as an onboarding fee or extra work, withPOST /invoices. It takes collectionMode, daysUntilDue and reference like a subscription does.
Selling to businesses
Paying by invoice
A subscription withcollectionMode: manual sends each invoice to pay by bank transfer or on its hosted page, instead of charging a card. It starts active straight away, and the customer uses what they bought while the invoice is open. An invoice still unpaid a day after it is due turns the subscription past_due, the customer gets reminders, and it is suspended or ended as your failed-payment settings say. Paying the invoice, wherever it is paid, brings it back.
Payment terms
A manual invoice is due 7 days after it is issued, unless you change the default under Billing settings → Invoicing → Payment terms (0 to 365 days, 0 being due on receipt). A subscription can have its own withdaysUntilDue, and PATCH /subscriptions/{id} changes it for the invoices that follow.
Purchase order numbers
Many companies only pay an invoice that quotes their purchase order. Send it asreference (up to 100 characters) on the subscription, and every invoice prints it as “Your reference” on the PDF, the hosted page and the emails.
Your bank details on the invoice
Set the account customers pay into under Billing settings → Invoicing → Pay by bank transfer. Every manual invoice still to be paid shows it on its PDF, hosted page and emails. When the transfer lands, record it withPOST /invoices/{id}/payments. See Payments taken at the desk.
Who gets the invoices
Invoices go to the customer’semail. Add up to 5 more addresses, such as the finance team, with billingEmails on the customer. Customers can change these themselves in the portal.
Writing off and voiding
POST /invoices/{id}/mark-uncollectiblewrites an open invoice off as bad debt. The customer can still pay it later throughhostedUrl.POST /invoices/{id}/voidcancels an open or uncollectible invoice for good. It can’t be paid after that.
past_due subscription becomes active again, and a suspended one becomes an ordinary pause for you to resume or cancel. Neither cancels the subscription.