Vendor Credits

API Reference

Mercoa also supports vendor credit tracking. Vendor credits are credits your users can receive from their vendors that represent the amount of money a vendor owes your user.

Creating Vendor Credits

Vendor credits can be created through Mercoa’s frontend via the entity dashboard or Mercoa’s vendor portal. You can also create vendor credits through the create vendor credit API endpoint.

1
from mercoa import Mercoa
2
from mercoa.vendor_credit_types import VendorCreditRequest
3
4
client = Mercoa(
5
    token="YOUR_TOKEN",
6
)
7
client.entity.counterparty.vendor_credit.create(
8
    entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9
    counterparty_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
10
    request=VendorCreditRequest(
11
        total_amount=100.0,
12
        currency="USD",
13
        note="This is a note",
14
    ),
15
)

Applying Vendor Credits

If a vendor credit between the payer and vendor of an invoice is available, Mercoa allows the payer to apply the credit to the invoice. This deducts the vendor credit amount from the invoice total, reducing the amount transferred through Mercoa.

Mercoa’s frontend automatically applies available vendor credits to invoices created via the <PayableDetails /> React component. You can also apply vendor credits using the vendorCreditIds parameter on the update invoice API endpoint.

1
from mercoa import Mercoa
2
from mercoa.invoice_types import InvoiceUpdateRequest
3
4
client = Mercoa(
5
    token="YOUR_TOKEN",
6
)
7
client.invoice.update(
8
    invoice_id="in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9",
9
    request=InvoiceUpdateRequest(
10
        vendor_credit_ids=["vcr_c3f4c87d-794d-4543-9562-575cdddfc0d7"],
11
    ),
12
)

When paying an invoice with vendor credits through Mercoa’s payment rails, there are two scenarios to consider:

Vendor credits partially cover the invoice

If the applied vendor credits sum to less than the invoice total, Mercoa only transfers the remaining invoice amount to the vendor. In this case, the invoice enters the PENDING state and is processed normally.

Vendor credits fully cover the invoice

If the applied vendor credits sum to the invoice total or more, Mercoa does not transfer any funds to the vendor. In this case, the invoice enters the PENDING state and then immediately enters the PAID state. Please note that all the same webhooks are still sent as if the invoice is paid normally.

Estimating Vendor Credit Usage

You can estimate the usage of vendor credits on an invoice of a given amount using the estimate usage endpoint.

1
from mercoa import Mercoa
2
3
client = Mercoa(
4
    token="YOUR_TOKEN",
5
)
6
client.entity.counterparty.vendor_credit.estimate_usage(
7
    entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8
    counterparty_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
9
    amount=150.0,
10
    currency="USD",
11
)