Invoicing

Mercury's Accounts Receivable API lets you raise invoices from your own systems, collect by card or ACH debit, and know when each one is paid.

For working code, see the Invoice your customers recipe. For every field, parameter, and response, see our Accounts Receivable API reference.

What You Can Build

• Raise Invoices Directly from Your System: Turn a CRM update, a billing event, or metered usage into an invoice.
• Act on Payment Status: Read invoice status to release an order, unlock software access when a payment lands, or flag overdue accounts.
• Real-Time Reporting: List invoices and customers for timely and accurate revenue reporting. Download a PDF copy of each invoice for your internal records.

Capabilities

• Supported: Mercury handles it.
• Client-Side: The endpoints exist and the logic runs in your code.
• Not Available Today: There is no API route for this today. Please submit feedback on ways we can improve to [email protected].

Invoices

Payments and Reconciliation

The API enables payment methods on an invoice and reports what arrives. It does not process payments. Your customer completes payment through Mercury's hosted invoice experience.

Customers

Before You Start

Send Your First Invoice

Review the Invoice your customers recipe for example formatting of each request.

1. Find the Account Where Payments Land: GET /accounts. Note the id of a checking or savings account. You send it as destinationAccountId on every invoice.
2. Look for the Customer: GET /ar/customers. The list takes pagination parameters only, so match on email in your own code.
3. Create the Customer if None Matched: POST /ar/customers with name and email. The response carries the customer's id, which you send as customerId on the invoice. Review results before adding a new customer to prevent duplicate records.
4. Create the Invoice: POST /ar/invoices with required fields. We will email the invoice immediately unless you set sendEmailOption to DontSend.
5. Verify the Invoice Status: GET /ar/invoices/{invoiceId} and check status.

Common Workflows

Best practices for when you need to send a large volume of invoices, bill customers on a recurring cadence, and reconcile incoming payments.

Invoice Many Customers

• One Invoice Per Request: Issue one API request per customer using a client-side loop when creating invoices in bulk. Send them one at a time rather than firing the whole run in parallel, and back off when a create fails.
• Set Your Own invoiceNumber to Guard Retries: Pass your own invoiceNumber to safely retry requests. Reusing an existing number triggers an error instead of creating a second invoice. If left blank, Mercury auto-generates a number, which can create duplicates if a retry occurs.
• Keep Invoices Distinct for Clean Reconciliation: For bank transfers to the virtual account, Mercury matches incoming payments to open invoices by customer and exact amount (see Confirm Payment and Reconcile). Two open invoices for the same customer and amount look identical when payment arrives, so track the status of every request and avoid creating duplicates.

Bill on a Recurring Schedule

To set up recurring billing, schedule your system to send invoices automatically on a set cadence. Give each invoice a unique, date-based invoice number to prevent duplicate invoices from being sent.

• Schedule the Trigger: Set a local cron job or background worker to start batch processing at every billing interval.
• Process Requests Sequentially: Execute your loop to issue one POST /ar/invoices call per customer per cycle, sending one request at a time rather than the whole cycle at once.
• Assign Period-Based IDs: Set a unique invoiceNumber for each billing cycle (e.g., INV-2026-08-CUST123) so your system can check for existing records before attempting a retry.

Invoices created via your scheduler are individual, standalone records. As they carry no series ID, they will not appear under Invoicing > Recurring in the Mercury dashboard. You must track and display recurring billing schedules within your own application.

Correct an Invoice After Sending

POST /ar/invoices/{invoiceId} overwrites the entire invoice object rather than patching specific fields. You can update an invoice only while its status is Unpaid.

1. Read State: GET /ar/invoices/{invoiceId}.
2. Execute Changes: The update overwrites the whole invoice, so send every field you want to keep. Omitting a required field returns an error, and omitting an optional field sets it to null.
3. Request Body: Include invoiceNumber (required). customerId and destinationAccountId are not part of this call and are ignored if sent.

To void an invoice instead of changing it, call POST /ar/invoices/{invoiceId}/cancel. Cancellation works on unpaid invoices only and cannot be undone.

Confirm Payment and Reconcile

Track payment status by polling GET /ar/invoices and reading the status field (Unpaid, Processing, Paid, or Cancelled). While you can listen to transaction webhooks to detect incoming payments, polling GET /ar/invoices confirms when an invoice's status officially updates.

Invoices transition to Paid strictly from an Unpaid state. Virtual account bank transfers trigger automatic reconciliation to Paid on an exact amount match, so a short payment or an overpayment does not reconcile. Alternative payment rails (Card, ACH debit) and manual status updates settle through their own pipelines and bypass virtual account auto-matching.

Virtual Account Numbers Belong to the Customer, Not the Invoice: Setting useRealAccountNumber: false shares one account number across all of that customer's invoices, so never use it as a payment-matching key. Reconcile incoming payments using transaction records from GET /transactions.

Payer Reference (externalMemo): Read the externalMemo field via GET /transaction/{transactionId} (it lives on the transaction, not the invoice). It applies to incoming payments and is often omitted by sending banks, so your reconciliation workflow must treat this field as optional.

Objects and Endpoints

Parameters and response schemas are in Accounts Receivable. For the base URL and the auth header, see Getting Started.