The invoice lifecycle is as follows:
This guide goes through the minimum required data to get an invoice through the complete lifecycle. If you are using the Mercoa embed or React component, all these steps are automatically handled for you.
If an invoice is created and saved as draft, or if it comes in through the email inbox it’s in the DRAFT state.
The Creator Entity is the entity that created the invoice.
The payer is the entity that’s paying the invoice.
All other information is optional at this point, and the invoice can be updated at any time with partial information as you get it.
An invoice that has all information required to be approved can be moved to the NEW state.
The vendor is the Entity that’s receiving the payment for the invoice. The vendor needs to be created and have a valid profile.
The amount is the total amount of the invoice. This is the amount that’s paid to the vendor. The currency is the currency that the invoice is in, e.g. USD.
The invoiceDate is the date that the invoice was issued.
The dueDate is the date that the invoice is due.
This is the payment method for the payer (funding source)
Once an invoice is in the NEW state, the amount, currency, dueDate, payerId and vendorId can’t be
changed.
If the entity has an approval policy set, the invoice needs to be approved by all relevant parties to move to the APPROVED state.
If the entity does NOT have an approval policy set, the invoice automatically
moves into the APPROVED state and isn’t in the NEW state.
When the invoice is created, a snapshot of the approval policy is saved to the invoice. This means that any changes to the policy in the future don’t reflect on previously created invoices.
A list of approvers is created on the invoice. An approver can be an individual entity user or a list of roles.
If an approver is a specific user, only that user can fill that approval. Otherwise, any user with an appropriate role can fill an approval.
In this example, any user with the role approver or controller can approve as the first approver, but only user_123456 can be the second approver.
A user can only fill one approval, and approver order is not enforced.
If roles are provided, you can update the approvers list by providing a userId for a user that’s in the appropriate role. Once the userId is set, only that user can approve the invoice, and it can’t be changed.
To add an approval to the invoice, use the approve endpoint. You can pass in an optional text field if the user wants to add a comment with their approval.
Once all approvals are complete, the invoice automatically moves to the APPROVED status. If the invoice already has a deductionDate set, it moves to the SCHEDULED state.
Approvals and Rejections create a comment on the invoice. You can use this to show a list of comments and approvals, as the comments have the approver details as part of the response.
Once all approvers have approved the invoice, you can schedule the payment.
This is the payment method for the vendor (disbursement method).
This is the date funds are triggered to be moved.
On the deductionDate, at or before 1 PM Pacific Standard Time (PST) (4 PM Eastern Standard Time (EST)), the payment triggers, and the invoice is in the PENDING state. This means that the invoice amount and any applicable fees are deducted from the payer’s account and sent to the vendor.
No action is required, this is an automatic function.
If the deductionDate is past 1 PM PST (4 PM EST) or if the date is a bank holiday or weekend, the payment triggers the next business day.
If you are using your own payment rails, you are responsible for moving funds from the payer to the vendor when the
invoice is set to the PENDING state. You can use webhooks to listen for this event.
When the invoice amount is received by the vendor, the invoice is set to the PAID state.
If you are using custom payment rails, you are responsible for moving the invoice into this state once the funds have settled.
For invoices paid via mailed or printed checks, you have the ability to void the check if needed. This is useful in cases where:
PAID statusFAILEDFAILEDFAILEDTo void a check programmatically, update the invoice status to FAILED. This will also update the transaction status to FAILED and all other invoices associated with the same transaction to FAILED.
PAID status without re-scheduling the paymentPAID → FAILEDCOMPLETED → FAILEDFAILED