Billing & payments

Billing of what was sold: one-off invoices, recurring billing runs, the payments recorded against them — taken online through a payment gateway or entered by hand — and the credit, credit-note and dunning workflows around them.

Core objects

Invoices & invoice lines — the bill, with a status lifecycle, line items, overdue tracking and statistics.
Payments — amounts received, applied against invoices, with refunds.
Billing schedules — recurring billing definitions with their own lifecycle (activate, pause).
Credit notes — issued, applied and voided against invoices.
Credit checks & credit holds — the exposure gate in front of quotes and orders. Separate from credit notes.
Dunning — configurable overdue-reminder policy and run history.
Ledger accounts — the customers, suppliers and partners you bill and pay, carrying credit limit, credit days and payment terms.

What you can do

Create, update and void invoices; add and edit invoice lines; send an invoice; and record a payment directly against one. Voiding stops once money has been collected: an invoice with any payment recorded against it — including a partially paid one — is refused, as are invoices already paid, cancelled or voided. To get past that, refund the payment: a refund reverses the amount back off the invoice, and once nothing is paid the invoice can be voided. Otherwise leave the invoice standing and settle it with a credit note. Note that the web app still offers Void on a partially paid invoice and reports the refusal as a generic failure, so the reason is not shown on screen.
View invoice statistics and overdue invoices.
Record payments, and cancel, clear or refund them.
Take payment online through a payment gateway (Razorpay), with provider webhooks.
Run recurring billing — trigger a billing run or preview what it would bill.
Manage credit notes (create, issue, apply, void).
Run credit checks, place and release credit holds, and process credit overrides.
Configure dunning and run it, and read dunning history per invoice through the API.

Sending, printing and downloading an invoice

Send is a status action: it moves a draft or pending invoice to sent. It does not itself email the customer, so pair it with however you deliver documents. Overdue tracking and dunning work from the due date and the outstanding balance rather than from this status, so an invoice you never marked as sent still appears as overdue once it is past due.

The invoice screen’s Print and Download PDF both render a clean, self-contained invoice — a bill-to panel, invoice and due dates, the line table and the totals — and hand it to the browser’s print dialog with the application shell hidden. “Download PDF” is the same pipeline through Save as PDF, so what the customer receives is exactly what you see on screen, in black on white, regardless of your theme. One thing to check before you send it: the header prints the fixed name “WorkSquares” rather than your own company name, address or tax registration.

Taking payment online

Online payment runs through the WorkSquares suite’s shared payments component, which owns the provider client and the webhook signature checking so that every product handles money the same way. Razorpay is the supported provider today. Credentials resolve per company from an active Payment integration connector — key id, key secret and webhook secret — and fall back to environment configuration if no connector is set up, so each tenant can collect into its own merchant account without any code change.

Creating a payment link. POST /payments/checkout returns a hosted payment link for an invoice, or for a sales order’s open invoice if you pass the order instead — in which case CPQ picks the most recent invoice on that order that is neither cancelled nor paid and still carries a balance. An invoice with nothing outstanding is refused rather than charged. You get back the payment URL, the provider’s link id, the amount and currency, and the invoice it belongs to; pass a callback_url and the customer returns to your page after paying. Checkout is permission-guarded like any other write in CPQ. It is an API capability today: nothing shipped calls it. The browser storefront shows Pay Now, Pay Overdue and Pay All Outstanding buttons, but none of them has a handler behind it, so clicking them does nothing. The Customer Portal Android app has no card checkout either, though a customer can record a payment they have already made against an invoice. Payment links are therefore created from your own storefront or integration.

Receiving the result. POST /payments/webhook/:provider takes the provider’s callback. It is the one billing endpoint that carries no login — payment providers cannot hold a session — so it is gated on the signature instead: the HMAC is verified over the exact bytes received (the raw body is preserved before any JSON re-serialisation could change them) and compared in constant time. A missing or unverifiable signature is rejected outright. CPQ reads the company from the metadata it attached at checkout so that it verifies against that company’s webhook secret; a forged company id still has to produce a valid signature for that company’s secret, and nothing is written until it does.

What happens to the money

The details below are the ones that decide whether your ledger stays right when a gateway does something unhelpful.

Currencies convert properly. Gateways transact in the smallest currency unit, and that unit is not always a hundredth. CPQ converts using the decimal count for the actual currency — two places for most, none for yen or won, three for dinar-style currencies — in both directions, so a ¥500 invoice is charged ¥500 rather than ¥5.

A capture in the wrong currency is never applied. If the captured currency does not match the invoice currency, the payment is not recorded at all and the webhook is acknowledged with the reason. Applying a foreign-currency amount at face value against the balance would silently misstate the invoice, and no redelivery of the same event could fix it.

A capture is recorded once. Provider payment ids are unique per company for gateway payments, enforced by a database index rather than only by a lookup, so two deliveries of the same event racing each other cannot both create a payment. The second one is recognised as already processed and acknowledged. The uniqueness rule is deliberately scoped to gateway payments: manually entered references such as cheque numbers may legitimately repeat.

The capture commits as one unit. The payment row, the invoice’s paid amount and balance, and the sales order’s payment status are written in a single transaction against the locked invoice — so the order can never say paid while the invoice disagrees. The account the payment is booked to is read from the locked invoice, never from the webhook payload.

Acknowledge or retry is decided deliberately. A verified webhook CPQ cannot apply is answered with success and an explicit reason — event type not handled, payment carrying no CPQ invoice reference, currency mismatch, already processed — so the provider stops retrying something no retry can fix. A transient failure such as a database problem returns an error instead, so the provider retries and the capture is not lost.

Overpayment is kept, not dropped. If a customer pays more than the balance — two links paid, a rounding difference — the full captured amount is recorded as the payment, only the outstanding balance settles the invoice, and the excess is written in the same transaction as an issued on-account credit note for the customer, annotated with the invoice and the provider payment it came from. You then apply that credit to another invoice like any other credit note.

A capture recorded this way raises a payment.received event, so workflows and webhook subscriptions can act on it — notify the account owner, kick off fulfilment, push to a downstream system.

Recording payments by hand

Not every payment arrives through a gateway. Payments can be entered directly, against an invoice, from the payments screens or from the invoice itself.

A manually entered payment may not exceed the invoice’s outstanding balance — the overpayment allowance exists only for genuine gateway captures. Entry takes a lock on the invoice, so two people recording a payment at the same moment cannot both apply it.

Payments then move through three actions. Clear completes a payment that was sitting pending — for instance one a customer submitted through the portal for verification — and applies it to the invoice at that point. Cancel is for a pending payment that will never arrive and marks it failed. Refund applies to a completed payment: it reverses the amount (in full or in part) back off the invoice and marks the payment refunded, all in one transaction, which is what unlocks voiding an invoice that had been paid. A refund is a bookkeeping reversal — it does not instruct the gateway to return the money, so issue the refund at the provider as well.

Credit management

Credit management is the gate in front of the sale, and it is a different thing from credit notes: a credit note gives money back on an invoice already raised, while a credit check and a credit hold decide whether a customer is allowed to take on more exposure in the first place.

The customer’s credit limit, credit days and payment terms live on their ledger account. Exposure is measured as the balance outstanding on their unpaid invoices — draft, sent, viewed, partially paid, overdue, disputed or pending — plus the full value of their open orders, so a big open order counts against the limit before it is billed. One edge is worth knowing: an order that has already been invoiced is still counted alongside its invoice.

Credit checks

A credit check snapshots the limit, the exposure and the available credit at the moment it runs, scores the account for risk, and returns one of three outcomes.

Exposure is what the customer already owes you: every open sales order — pending, confirmed, in production or shipped — plus the outstanding balance on every invoice that is not settled. An invoice counts while it is draft, sent, viewed, part-paid, overdue, disputed or pending; paid, void and cancelled invoices do not. Part-paid invoices count for the balance still outstanding, not the original total.

Outcome	Reached when	What happens next
Approved	Available credit covers the requested amount	The quote submits or the order confirms
Needs approval	Available credit falls short by 20% of the request or less — or the customer is on a soft hold when the check runs	Request an override; a manager approves or rejects it
Rejected	Available credit falls short by more than 20% of the request, or the customer is on a hard hold	Blocked until the exposure is reduced or the hold is released

The arithmetic is fixed and predictable: available credit covering the request approves, a shortfall of 20% or less of the requested amount goes to manual review, and a bigger shortfall than that is rejected.

A risk score is stamped on every check alongside that decision, starting from a baseline and rising with credit utilisation (above 50%, 70% and 90% of the limit) and with any of that customer’s checks rejected or sent for approval in the last 90 days. Thresholds are written against it — 90 or above would reject outright, above 70 would force manual review even where credit covers the request — but those inputs cap the calculated score at 55, so the score never changes an outcome on its own. Read it as background on the record, not as a gate. A check refused for a hard hold is stamped 100.

Checks are not duplicated. One quote or order carries one live check: a check still pending or awaiting approval is returned as-is rather than re-run, and an approved check is reused — it stays approved even if the document’s total has moved since. When a check comes back rejected or needing approval and the account has no hold yet, a soft hold is raised automatically so the account is visibly flagged.

An override is a two-step request: the salesperson requests it with a reason (and optionally an expiry), and someone with approval rights processes it. Approving marks the check approved, releases any soft holds on that customer and updates the document the check belongs to. Rejecting requires a reason and leaves the block standing — though if the customer’s limit is later raised, or their exposure falls far enough to cover the amount, the next check runs fresh instead of repeating the old refusal.

Credit holds

A hold is placed on the customer, not on a document, and comes in two strengths. A hard hold is a real block: a credit check that looks for holds is refused outright with the hold reason, and quote submission is refused with it too, until the hold is released. A soft hold lets work continue but turns an otherwise-approved check into needs-approval, so a human has to agree — at order confirmation rather than at quote submission. Holds carry a reason — overdue payment, risk, or a manual decision — and an optional amount, and are released explicitly with a note.

Where the gate bites is at quote submission and at order confirmation; building a draft quote is not blocked, although the quote form itself refuses to create one for a hard-held customer (see Credit on a quote). Submitting a quote for a customer on a hard hold is refused with the hold reason, and a failing credit check blocks the submission and points the user at the credit check to request an override. A soft hold escalates the check to needs-approval at submission, so a soft-held customer does not submit unattended even with headroom to spare.

Both strengths bite again at order confirmation. Confirmation reuses the quote’s approved credit check rather than running a new one, but it re-reads the customer’s holds before it accepts that reuse — so a hold placed after the check was approved still stops the order: a hard hold rejects it, a soft hold sends it for approval. A hold takes effect from the moment you place it, wherever the customer is in the flow.

Skipping the gate needs authority, not just edit rights. Order confirmation accepts two override flags — one skips the credit check entirely, the other confirms past a rejected or held check. Using either requires the approve right on credit checks, the same right that governs the override workflow they short-cut; being able to edit the order is not enough. Every use, and every refusal, is recorded against the user who attempted it. Confirming an order normally is unaffected.

Credit checks, credit holds and credit notes each have their own list, detail and form screens under Credit. When you raise a credit check — and on contract amendment and renewal forms — the customer’s credit position is shown alongside it: the limit, what is used, what is available, the risk score and any active holds.

Billing schedules and the billing run

A billing schedule is a recurring bill definition attached to a customer and, usually, to a quote, order, contract or subscription. It carries a frequency — one-time, weekly, fortnightly, monthly, quarterly, half-yearly or annually — a start date, an optional end date, the next billing date and the total to be billed. Its lines are what become invoice lines, and they can be triggered by date, by milestone, by percentage or manually. A schedule moves through draft, active, paused, completed and cancelled; only an active schedule bills.

The billing run finds every active schedule whose next billing date has arrived and turns each one into an invoice. The invoice is created as a draft, dated at the start of the billing period, due 30 days later, linked back to the schedule and to the subscription or contract behind it, with one invoice line per schedule line. The schedule’s next billing date then advances by its frequency, and a schedule whose next date would fall past its end date is marked completed. A one-time schedule bills exactly once: it has no next date to advance to, so it is marked completed as soon as its invoice is raised, and a second attempt to bill it is refused however its status got back to active. Each schedule is billed independently, so one bad schedule does not stop the run — failures come back listed against the schedule that caused them. Because the output is a draft, you review and send the invoices after the run.

Preview before you bill. The billing run screen shows exactly which schedules are due, for which customers, for how much, and the total — without creating anything. Run it, and the same screen reports the invoices generated, the total billed and any schedules that failed.

The run also happens on its own: a daily job sweeps every company with schedules due (2:00 AM UTC by default, and both the schedule and whether it runs at all are configurable). The manual trigger is the same operation, so use it to catch up or to bill early.

Dunning

Dunning is the escalation ladder for invoices that go past due. You configure one schedule per company, made of numbered steps; each step says how many days after the due date it applies and what to do at that point. Overdue invoices are matched to the next step they have not had yet, and only once they are old enough for it.

The steps you can build a ladder from are retry payment, send reminder, send warning, suspend subscription and cancel subscription. Suspend and cancel act on the subscription behind the invoice through the normal subscription lifecycle, so the state change is validated like any other and raises the usual events; on an invoice with no subscription behind it they are skipped. Because subscription status transitions do not currently complete (see Subscriptions), those two steps record a failed attempt instead of moving the subscription. Every attempt is recorded with its step, action, date and result.

Retry payment does not charge a stored card: CPQ holds no card or mandate. It asks the gateway for a fresh hosted payment link covering the outstanding balance and tries to email that link to the customer. Money is never booked by the step itself — it is booked only when the provider’s signed webhook reports the capture.

Delivery needs two things in place. The three steps that send email — the retry link, the reminder and the warning — address the invoice’s account: its primary active contact plus the address on the account record itself. Each also needs an active email template carrying the code it looks for (DUNNING_PAYMENT_RETRY, DUNNING_REMINDER, DUNNING_WARNING). Those templates are not created for you: CPQ ships them as a seed an administrator applies deliberately, because applying it turns on customer-facing email for every tenant running dunning. Until the templates exist and the account has a billable address, the step records as failed and nothing is sent. Retry payment checks both before it asks the gateway for anything, so a ladder that cannot deliver does not leave a trail of abandoned payment links; when it can, the link is emailed and written onto the attempt, where the dunning-history API can retrieve it. There is no per-invoice dunning history screen in the web app yet.

Dunning runs on demand, from the dunning screen or the API. There is no automatic dunning sweep, so trigger it on your own schedule.

Tax on invoices

Tax is calculated by a pluggable engine. The built-in engine uses the tax codes, jurisdictions and rates you maintain in CPQ; Avalara and Vertex can be used instead by configuring a tax-engine connector for the company, after which they are picked up automatically. The provider in force is cached briefly per company, so a configuration change takes effect within a few minutes.

Beyond calculating tax for a quote or an invoice, the tax API validates a shipping address against the provider, commits a transaction to the provider once the document is final, voids a committed transaction if the document is cancelled, and tests the connection so you can verify credentials before you rely on them. If an external provider is configured but fails while a line is being priced, the pricing waterfall falls back to the tax rate sent on the request — it does not re-run CPQ’s own tax tables — so a request that carried no rate leaves the line untaxed. Send a fallback rate alongside the address if you price through an external provider.

Tax codes, jurisdictions and rates are maintained by administrators — see Products & pricing.

Ledger accounts

Customers, suppliers and partners are all held in one ledger-account master, which is why a customer record in CPQ carries more than contact details: tax registration (GSTIN, PAN, TAN), bank details, an opening balance, a default currency and price book, and the financial terms the rest of billing reads — credit limit, credit days and payment terms. Set a customer’s credit limit and terms on the customer record and credit management picks them up from there. The API can list the ledger accounts as a whole or narrowed to customers or to suppliers.

This is a party master, not a general ledger. Double-entry journals, trial balance and financial statements are the job of Accounts, which is the ledger of record for the suite.

In the customer portal

The customer portal you can put in front of a customer today is the Customer Portal Android app. Signed in, a customer sees their own invoices with a billing summary — total due, overdue amount and total paid — searches them by number, filters them by status, opens one for its lines and the payments recorded against it, and downloads the PDF. A customer can also submit a payment against an invoice: it is recorded pending, for your finance team to verify, and does not settle the invoice on its own.

The browser storefront has an invoice screen of its own, including a Raise dispute control, but it is not usable: its invoice list, its totals and the dispute itself are written against columns the current database does not have, so each returns an error rather than a result. Nothing moves an invoice to disputed from the portal — see Portals.

Revenue recognition

Recognising the revenue behind these invoices is a module of its own, aligned to ASC 606 / IFRS 15: recognition rules, revenue schedules, multi-element allocations, deferred revenue and revenue journal entries. Period close and reconciliation exist but do not run against the current database. See Revenue recognition.

Connects to

Subscriptions — recurring charges are billed through billing schedules and the billing run.
Orders & contracts — orders and contracts lead to the invoices billed here.
Quotes & approvals — credit checks and holds gate quote submission.
Accounts — invoices and payments feed the financial ledger of record.