API Reference

Invoice Lifecycle

Invoices in AR follow a linear lifecycle through the following states:

Draft
Awaiting Payment
Payment processing
Paid

1. Creating a Draft

An invoice object can be created via the React component provided in Mercoa’s component library, or via the Mercoa API.

When an invoice is created, it is assigned the DRAFT state. In this state, a vendor can:

Freely edit and save the invoice
Preview the invoice PDF and payor-facing payment portal
Send the invoice to proceed to the next stage

What must be set to get into this state?

Invoice Date
Due Date
Total Amount

2. Sending the Invoice and Awaiting Payment

When a vendor sends the invoice to their customer, it is assigned the AWAITING_PAYMENT state.

Upon the invoice reaching this state, Mercoa will send an email to the specified customer with a payment portal that the customer can use to pay the invoice.

What must be set to get into this state?

Customer
Name
Email
Invoice Date
Due Date
Invoice Number
Total Amount
Payment Destination Method

Optional Fields

These fields exist on the invoice object as well, but are not required to send an invoice:

Payment Source Method
- The vendor can provide the payer’s bank details if known, but the payer can use the Mercoa payment portal to input their own bank details.
Internal Notes
- Vendors can optionally store unstructured text in a note-to-self field.

Payment Processing

After the customer pays the invoice via the payment portal, the invoice is assigned the PAYMENT_PROCESSING state. The invoice will remain in this state until the funds settle via ACH.

Paid

The invoice reaches this state once the vendor receives the invoice amount.