API Reference

Lifecycle of an invoice

The invoice lifecycle is as follows:

This guide will go 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.

1. Creating a Draft

If an invoice is created and saved as draft, or if it comes in through the email inbox it will be in the DRAFT state.

What needs to be set to get in this state?

CreatorEntityId

The Creator Entity is the entity that created the invoice.

PayerId

The payer is the entity that is paying the invoice.

1
// Example
2
{
3
  status: 'DRAFT',
4
  creatorEntityId: 'ent_123456',
5
  payerId: 'ent_123456',
6
}

All other information is optional at this point, and the invoice can be updated at any time with partial information as you get it.

2. Getting ready for approval

An invoice that has all information required to be approved can be moved to the NEW state.

What needs to be set to get in this state?

Vendor ID

The vendor is the Entity that is receiving the payment for the invoice. The vendor needs to be created and have a valid profile.

Amount and Currency

The amount is the total amount of the invoice. This is the amount that will be paid to the vendor. The currency is the currency that the invoice is in, e.g. USD.

Invoice Date

The invoiceDate is the date that the invoice was issued.

Due Date

The dueDate is the date that the invoice is due.

Payment Source ID

This is the payment method for the payer (funding source)

1
// Example
2
{
3
  status: 'NEW',
4
  payerId: 'ent_123456',
5
  creatorEntityId: 'ent_123456',
6
  vendorId: 'ent_987654',
7
  amount: 1000,
8
  currency: 'USD',
9
  invoiceDate: '2021-01-01',
10
  dueDate: '2021-01-15',
11
  paymentSourceId: 'pm_123456',
12
}

3. Getting approvals

If the entity has an approval policy set, the invoice will need to be approved by all relevant parties to move to the APPROVED state.

When the invoice is created, a snapshot of the approval policy will be saved to the invoice. This means that any changes to the policy in the future will not reflect on previously created invoices. A list of approvers will be created on the invoice. An approver can be an individual entity user or a list of roles.

1
// Example Approvers list on an invoice
2
{
3
  ...
4
  approvers: [{
5
    roles: ['approver', 'controller'],
6
    action: 'NONE'
7
  },{
8
    userId: 'user_123456',
9
    action: 'NONE'
10
  }]
11
}

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 the example above, any user with the role approver or controller can approver as the first approver, but only user_123456 can be the second approver.

A user can only fill one approval, and currently approver order is not enforced.

If roles are provided, you can update the approvers list by providing a userId for a user that is in the appropriate role. Once the userId is set, only that user can approve the invoice, and it cannot 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 will automatically move to the APPROVED status. If the invoice already has a deductionDate set, it will move to the SCHEDULED state.

4. Scheduling the payment

Once all approvers have approved the invoice, you can schedule the payment.

What needs to be set to get in this state?

paymentDestinationId

This is the payment method for the vendor (disbursement method)

Deduction Date

This is the date funds will be triggered to be moved

1
// Example
2
{
3
  status: 'SCHEDULED',
4
  payerId: 'ent_123456',
5
  creatorEntityId: 'ent_123456',
6
  vendorId: 'ent_987654',
7
  amount: 1000,
8
  currency: 'USD',
9
  invoiceDate: '2021-01-01',
10
  dueDate: '2021-01-15',
11
  deductionDate: '2021-01-13',
12
  paymentSourceId: 'pm_123456',
13
  paymentDestinationId: 'pm_987654'
14
}

5. Pending

On the deductionDate, at or before 1PM EST, the payment will be triggered and the invoice will be in the PENDING state. This means that the invoice amount and any applicable fees will be deducted from the payer’s account and sent to the vendor.

No action is required, this is an automatic function.

6. Paid

When the invoice amount is received by the vendor, the invoice will be set to the PAID state.