Mercoa Changelog

API/SDK: 0.4.7

Jul 16, 2024


API/SDK: 0.4.6 -- React: 0.0.47

Jul 10, 2024


  • Added minAmount and maxAmount to custom payment method schemas
  • Added ability to override fees on invoices that use custom payment methods. See documentation for more details.
  • Added new calculatePaymentTiming endpoint to calculate the payment timing for an invoice. See documentation for more details.


BREAKING: renamed method fees.calculate to calculate.fee to match the new endpoint structure


  • Various bugfixes
  • Uses new calculatePaymentTiming endpoint to display payment timing information on invoices
  • Full customization of payment timing and fee components

API/SDK: 0.4.5

Jul 7, 2024
  • All entity endpoints now support using the foreignId as the entityId in the path. This will allow you to use your own IDs for entities instead of the Mercoa generated IDs.
  • Experimental support for entityGroups. Entity groups allow you to group entities together and query invoices/metrics across the group. See the documentation for more details.

API/SDK: 0.4.4 - React: 0.0.46

Jul 2, 2024



  • Fees are now displayed to the user
  • Available balance is now shown on custom payment methods
  • Payment Methods added inline in the invoice details form no longer use a popup

API/SDK: 0.4.2 - React: 0.0.43

Jun 20, 2024


  • ApprovalPolicy now returns createdAt and updatedAt fields.
  • CustomPaymentMethodSchema now accepts an estimatedProcessingTime field. This field is used to display an estimated processing time for a payment method on the invoice details page.


  • <ReceivableDetails /> now shows real time previews of the PDF and Payment Portal.
  • <PayableDetails /> now supports payment timing information.

API/SDK: 0.4.1

Jun 18, 2024

Webhooks types are now included in the Mercoa SDK and Docs. See the webhooks documentation for more details.

API/SDK: 0.4.0

Jun 13, 2024



  • Added roundedCorners option to organization colorScheme options. This lets you control the border-radius of Mercoa React/iFrame components.
  • Added accountId to counterparties endpoint. This lets you specify the account ID the vendor has on file for a customer.
  • Added isNetworkPayee and isNetworkPayer to entities endpoint. This lets you mark an entity as available to any customer on your platform.

API/SDK: v0.3.39

Jun 4, 2024

API Changes:

API/SDK: v0.3.37

May 31, 2024

API Changes:

  • Added find users endpoint to filter and find users in an entity.
  • Added entity customization endpoint to customize the available payment methods and metadata fields for an entity. This lets you turn off payment methods like ACH or checks for individual entities, and hide metadata fields that are not relevant to an entity.
  • Added ability to set a custom ACH entry description for an invoice. This will show up on the payor's and vendor's bank statement as the description for the ACH entry. See documentation for more details.

API/SDK: v0.3.36

May 27, 2024


  • OCR requests now take the entityId and vendorNetwork as body parameters instead of a query parameters.

API/SDK/React: v0.3.35

May 22, 2024

API Changes:

  • Added invoice metadata validation rules. See documentation for more details.

React Component Changes:


  • The <InvoiceInbox /> component has been renamed to <Payables />
  • The <InvoiceTable /> component has been renamed to <PayablesTable />
  • The <InvoiceDetails /> component has been renamed to <PayableDetails />


  • Approvals component now has two states, one for editing and one for viewing the policy.
  • Added excludePayables and excludeReceivables filters to the <InvoiceMetrics /> component.
  • Added new <Receivables /> component to display receivables for an entity. This component is similar to the <Payables /> component, but displays receivables instead of payables.
  • Added new <ReceivableDetails /> component to create and display details for a receivable.

API/SDK/React: v0.3.34

May 13, 2024

API Changes:

API/SDK/React: v0.3.33

May 2, 2024

SDK Changes:

API Changes:

  • Added getSourceEmail endpoint to return the source email that created an invoice.
  • Added externalAccountingSystem to organization response.

React Components:

  • Removed multiple dependencies to reduce bundle size
  • Added more <InvoiceDetails /> customization options, including the ability to choose which side the document preview shows up
  • Added ability to toggle between the invoice document and the source email for the invoice

API/SDK/React: v0.3.32

Apr 23, 2024

API Changes:

  • Added invoiceMetrics to the /findCounterparties endpoint. This will return the total amount/count of invoices for a counterparty, as well as total/count grouped by invoice status.

API/SDK/React: v0.3.29

Apr 19, 2024

API Changes:

  • The search parameter on the /invoices, /entity/{entityId}/invoices, and /invoice-metrics endpoints now searches by vendor, invoice number, and amount!
  • Added metadata parameter to the /invoices and /entity/{entityId}/invoices endpoints. This will allow you to filter for invoices with specific custom field values, like a project ID or PO number.

React components have also been updated to take advantage of these new features.

API/SDK: v0.3.28 - React: v0.0.26

Apr 10, 2024

API Changes:

  • Added flag on bank account check options to specify using a signatory name or image for the signature on a check.
  • Added returnByDate option to invoice metrics endpoint. This will return metrics grouped by day for the specified date range.
  • New add-approver endpoint to add an approver to an invoice. This endpoint will intelligently add the approver to the best position in the approval chain, or take an explicit position.

React Component Updates:

  • Added heightOffset parameter to base MercoaSession component. Will be used in all fix height components to offset the height of the component.
  • Added new invoice metrics component to display per-day metrics for a specified date range.
  • Added the approvers column to the default inbox table columns.
  • Inbox table now supports the following mass actions: Add Approver, Submit for Approval, Approve, Reject, and Set Payment Date.

Admin Dashboard Changes:

  • Added SAVE AS ADMIN button to invoice details page. This will allow admins to update invoice details such as the invoice number, invoice date, and due date even after the invoice has been scheduled or paid.

API/SDK: v0.3.26

Mar 19, 2024

API Changes:

  • Removed disableLineItems from token options. This option is now deprecated and will be removed in the future.
  • Added lineItems to token options. This option replaces disableLineItems and instead allows you to make line items OPTIONAL, REQUIRED, or DISABLED.

API/SDK: v0.3.25

Mar 18, 2024

API Changes:

API/SDK: v0.3.22 - React: v0.0.16

Mar 6, 2024

API Changes:

  • Added endpoints to delete and upload attachments to invoices. See documentation for more details.
  • Renamed uploadedImage on invoice creation to document for consistency with other endpoints.

SDK/Docs Changes:

  • Namespaced endpoints to be more organized. Check PDF generation is now nested under the invoice.document namespace, and payment links are nested under the invoice.paymentLink namespace.
  • No breaking changes to the API or previous SDK versions.

React Component Changes:

  • Added checkboxes to all invoice tables to allow for bulk actions.
  • Created standalone component for invoice tables.
  • Added support for OCR to automatically extract vendor payment details from an invoice.

API/SDK: v0.3.19 - React: v0.0.14

Feb 22, 2024

API Changes:

  • Added immediate support for notifications. This will allow users to receive emails for every notification along with a daily email digest.
  • Removed Payment Source Options on Invoices. Moved ACH options to Payment Destination.
  • Added Calculate Fees endpoint to calculate fees for a payment before creating an invoice.
  • Updated Fees on an Invoice to return values of -1 if fees are not requested in the query.

React Component Changes:

  • Fixed Race Conditions on tables
  • Updated Payment Method Selectors on InvoiceDetails component
  • Support for multi-level approvals and approver propagation

API/SDK: v0.3.16 - React: v0.0.9

Feb 7, 2024

API Changes:

  • Added digest support for notifications. This will allow users to receive a daily email digest of their notifications instead of individual emails.

React Component Changes:

  • React component styles are now namespaced to avoid conflicts with other styles.

API/SDK: v0.3.15 - React: v0.0.8

Jan 29, 2024

API Changes:

  • Added support for multi-level approvals.

React Component Changes:

  • This is the first public release of the React component library!


Jan 22, 2024

API Changes:


Jan 19, 2024

API Changes:

  • Added support for checks as a payment method.
    • bankAccount can be enabled for checks and used as the payment source when the payment destination is a check.
    • The bank account must be a valid checking account that can have checks written against it.


Jan 9, 2024

API Changes:

  • Added counterparties and approvals page to token options. This page allows users to add and manage counterparties and approval rules.
  • Full SSN is now required for createEntity and updateEntity endpoints as well as the Business Representative endpoint.


Dec 12, 2023

API Changes:

  • Added getBalance endpoint to paymentMethods. This endpoint will return the current balance for an payment method. Currently only supported for bank accounts added via Plaid.
  • Removed markPaid option on iframeOptions. Instead, use the new offline payment method type as the destination.


Dec 11, 2023

API Changes:

Breaking Changes:

  • Removed ownedByOrg on the entity object. Please use isCustomer instead.

  • isCustomer on the entity object is now a required field for entity creation. It remains optional for entity updates.

  • Removed createdById on the invoice object. Please use creatorUserId instead.

  • Removed creatorId on the invoice object. Please use creatorEntityId instead.

New Features:

  • Added glAccountId to invoice line items. This field is used to map line items to a GL Account. This field is optional.

  • Added lineItem option to metadata. This field is used to map metadata to a line item.


Nov 16, 2023

API Changes:

  • Added creatorEntityId to invoice /create and /update request types. creatorEntityId will become a required field in the future. It is recommended to use this field instead of creatorId which will be deprecated in the future.
  • Added creatorUserId to invoice /create and /update request and response types. It is recommended to use this field instead of createdById which will be deprecated in the future.
  • Added foreignId to invoice /create and /update request and response types. This field is used to store an external ID for an invoice.
  • Renamed ownedByOrg to isCustomer on the entity object. It is recommended to use this field instead of ownedByOrg which will be deprecated in the future.


Nov 7, 2023

API Changes:

  • Added accountName to bank account payment methods. This is a user facing name for the bank account that is editable by the user.
  • Added vendor and metadata triggers for approval policies.
  • Added INVOICE_FAILED notification type.
  • Added disabled field to notification policies to completely disable a notification type.

Breaking Changes:

  • Approval Policy Triggers are now an array of objects instead of a single object. This allows you to set multiple triggers that all must be true for a single approval policy. The "all" policy is replaced with an empty list of triggers.
    • Current Policies have been migrated automatically


Oct 18, 2023

API Changes:

  • Added fees object to invoice /find and /get and entity /invoice/find and /invoice/get endpoints
    • To query for fees, pass in query param includeFees=true
  • Added iFrame Token Option for Entity: Enable Mercoa Payments


Oct 10, 2023

API Changes:

  • Added pagination to counterparty endpoints
  • Added logo to entity create and update endpoints
  • Added creatorId to invoice creation to specify if the payee or payor created the invoice
  • Created generateInvoicePdf endpoint to generate PDF of an invoice


Sep 29, 2023

Breaking Changes:

  • isPayor and isPayee fields are now required when creating an entity.

New Endpoints:

  • /entity/{entityId}/invoice/{invoiceId}
    • Can be used to get a single invoice for an entity by ID. This can be the full invoice ID (in_11aa2b77-6391-49e4-8c3f-b198009202c1) or the first 8 characters of the ID (11aa2b77).
    • Useful for bank statement reconciliation. The bank statement descriptor will read AP11aa2b77 for the payment associated with this invoice.


  • Added counterparty.added and counterparty.hidden webhooks

API Changes:

  • Added metadata, serviceStartDate and serviceEndDate fields to invoice line items
  • Added ownedByOrg filter to entity search
  • Added payerId filter to invoice search
  • Added excludePayables and excludeReceivables filters to entity invoice search
  • Added DELETE endpoint for entity metadata

SDK Changes:

  • archivePayees has been renamed to hidePayees
  • mercoaClient.entity.addPayees and mercoaClient.entity.archivePayees are now mercoaClient.entity.counterparty.addPayees and mercoaClient.entity.counterparty.hidePayees


Sep 25, 2023
  • Added new invoice metadata type KEY_VALUE to support key value pairs.
  • Added new JWT iframe option markPaid to allow users to mark invoices as paid on the iFrame.
  • Added new TokenGenerationOption expiresIn to set the expiration time of a token.

New Endpoints:

  • /entity/{entityId}/counterparties/payees
  • /entity/{entityId}/counterparties/payors
    • These endpoints will return a list of payees or payors for an entity. This replaces the /entity/{entityId}/counterparties endpoint. It is recommended to use these endpoints instead, as they will support pagination, search, and higher performance. The old endpoint will be deprecated in the future.


Sep 16, 2023

Breaking Changes:

  • Invoice Metrics now takes multiple currency codes and returns a list of metrics for each currency. See documentation for more details.


  • Added VENDOR_NAME and PAYER_NAME to invoice order by options.
  • Improved API Error Messages


Sep 1, 2023
  • Added metadataSchema parameter to updateOrganization endpoint.
  • Added metadata endpoints to entity. These endpoints allow you to create, update, and get metadata values for an entity.


Aug 29, 2023
  • Added counterpartyId filter to findCounterparties endpoint.


Aug 24, 2023

Vendor and Payer Onboarding

  • Added getOnboardingLink and sendOnboardingLink endpoints to the entity object.
    • getOnboardingLink endpoint will return a link to the Mercoa onboarding page for the entity.
    • sendOnboardingLink endpoint will send an email to the entity with a link to the Mercoa onboarding page.
    • Onboarding fields can be configured in the dashboard.

Other Changes


Aug 10, 2023

Breaking Changes

paymentMethod is now a discriminated union instead of nested objects. This change was made in v0.2.0 but had backwards compatibility. This change is now required. fundedDate has been renamed to settlementDate for consistency with industry norms.

New Features

  • Added defaultSource and defaultDestination parameters to paymentMethod creation and update requests.

  • Added isDefaultSource and isDefaultDestination parameters to paymentMethod response.

    • These parameters will set the payment method as the default source or destination for the entity.
  • Added formationDate to entity creation and update requests.


Aug 6, 2023


Jul 31, 2023
  • Added new getToken and getRawToken endpoints for an entity and entity users:
    • getRawToken is a GET endpoint that returns a JWT token for use with the API
    • getToken is a POST endpoint that returns a JWT token for use with the iFrame. This endpoint takes in a configuration object to customize the iFrame experience.
  • Added organization notification configuration endpoints. See documentation for more details.


Jul 29, 2023
  • Small breaking change for assigning approvers to an invoice.
    • userId has been renamed to assignedUserId for consistency with the response object
    • An additional approvalSlotId is now needed to specify the which slot the user will be assigned to.
    • See documentation for more details.


Jul 26, 2023
  • Added userNotificationPolicy endpoints to control what notifications are sent to a user. See documentation for more details.


Jul 19, 2023
  • Changed createPaymentMethod endpoint when creating a bank account to require accountId when using Plaid. This is to support multiple bank accounts per Plaid Link:


      type: 'bankAccount',
      plaidPublicToken: 'public-sandbox-1234',


      type: 'bankAccount',
      plaid: {
        publicToken: 'public-sandbox-1234',
        accountId: '1234',


Jul 17, 2023
  • Added getToken endpoint for an entity user:
    • /entity/{entityId}/user/{userId}/token
    • mercoaClient.entity.user.getToken(...
    • This endpoint will return a token scoped to a particular user in an entity


Jul 15, 2023


Breaking Changes

entity.find invoice.find and entity.invoice.find now return paginated results.

Previously, the response would be an array of the data requested. Now, the response is an object with the data and metadata about the request.

The response now looks like this:

  data: [ ... ],
  count: 100,
  hasMore: true,

New Features


Notifications are launched in beta! Your entity users can now get notifications for events like INVOICE_APPROVAL_NEEDED and INVOICE_PAID.

Notifications are available in the dashboard, iFrame, and the API. Email notifications are coming soon.

  • Notifications policies can be set on an entity to control what notifications are sent users aside from the default notifications.
  • New endpoint to get notifications for an entity user: entity.entityUser.notifications.find


  • Updated UI for managing entity users
  • Updated UI for managing approval policies
  • Created UI for managing entity notifications
  • Updated iFrame UI for approval workflows
  • Improved KYB process for entities to trigger fewer false negatives


Jul 10, 2023

Python issue with circular dependencies is fixed. Types are once again exported at the root level to make imports easier.


Jul 8, 2023


Breaking Changes

paymentMethod is now a discriminated union instead of nested objects.

Old Payment Method:

    type: 'bankAccount'
    bankAccount: {
      routingNumber: '12345'
      accountNumber: '9876'
    type: 'check'
    check: {
      addressLineOne: '123 Fake Street'
      stateOrProvince: 'California'
      postalCode: '94105'

New Payment Method:

    type: 'bankAccount'
    routingNumber: '12345'
    accountNumber: '9876'
    type: 'check'
    addressLineOne: '123 Fake Street'
    stateOrProvince: 'California'
    postalCode: '94105'


Breaking Changes

The 0.2.0 uses namespaces to make using the SDK more intuitive. The API routes have not changed, only the SDK structure

For example:

mercoaClient.paymentMethod.get() --> mercoaClient.entity.paymentMethod.get()
mercoaClient.entity.getInvoices() --> mercoaClient.entity.invoice.find()
mercoaClient.entityUsers.get() --> mercoaClient.entity.users.get()
mercoaClient.invoice.getDocuments() --> mercoaClinet.invoice.document.getAll()
mercoaClient.invoice.approve() --> mercoaClinet.invoice.approval.approve()
mercoaClient.invoice.getComment() --> mercoaClient.invoice.comment.get()

New Features


Jun 13, 2023


Breaking Change

  • Removed the createVendor and updateVendor options on invoice creation/update.
  • Vendors need to be explicitly created and linked to payers. See this guide for details.


New pages for managing Entity Users and Approval Policies are live!


May 30, 2023

BREAKING: Entity Invoices

  • Added pagination, server side search, and server side order to getInvoices
    • By default, this endpoint will now only return 10 results


  • Added new fields for approvers and approvalPolicy
  • Added approve and reject endpoints

Approval Policies (beta)

  • You can now set approval policies on entities.
    • Invoices for entities without an approval policy will have invoices go directly from DRAFT to APPROVED
    • Invoices for entities with an approval policy will have invoices go from DRAFT to NEW, and require the rules on the policy to be fulfilled to move into the APPROVED state


May 25, 2023


Update Payment Method had the wrong request body parameters that were too restrictive.


May 24, 2023

What's Changed

Add Payees Endpoint

  • Vendors (Payees) can now be explicitly added to a Payor, and do not need to be on an invoice to be linked to an entity.

JWT Options:

  • You can now disable vendor creation and restrict what vendors a entity sees on the iFrame

Payment Methods

  • Custom Payment Methods can now be updated.


  • New fields of invoiceDate and createdBy added to invoice.
  • New field userId added to invoice comment.
  • Invoice Response now returns invoice comments and hasDocuments
  • Invoice Comments return user information on who created the comment


  • File Hash based deduplication is now live


May 19, 2023
  • Added new invoice status of Scheduled

  • If you are using the API to create or update invoices, invoices will need to be set as Scheduled instead of New to be scheduled for processing. iFrame users will not be affected.

  • Added supportedCurrencies field to Custom Payment Method Schemas

  • This field is optional and will default to USD. If your payment rail supports currency other than USD or does not support USD, set this value to the supported currencies.

  • Entity Updates

  • Added new fields for isPayor and isPayee. These fields will become mandatory in the future. These fields determine if this entity is a payor or payee (vendor). If the entity is both, then both fields should be set to true.

  • Updated documentation for ownedByOrg field. This field currently determines if the entity is a payor or payee (vendor). In the future, this field will only be used to determine if you have a direct relationship with this entity.

Note: Current behavior will check if the isPayor and isPayee fields are not set and fall back to the old ownedByOrg method of determining who is a payer or vendor.


May 10, 2023
  • Entity Invoice Metrics
  • Get Transactions
  • BREAKING CHANGE: Counterparty now returns three lists


May 5, 2023
  • Org Color Settings
  • Plaid Link support
  • Date Range on Email Logs


Apr 20, 2023

Support for:

  • Invoice Line Items
  • Invoice Service Term


Apr 10, 2023

Python SDK Update


Apr 10, 2023

Python SDK


Apr 7, 2023

Manual webhook retrigger


Mar 22, 2023

Initial release