Invoice Webhooks

Modern Treasury will send webhooks to convey the status of the invoice. Some invoice statuses can be manually transitioned by you, while invoice statuses tied to the status of the invoice's payment order are automatically transitioned.

The message body will include the event and a data representation of the invoice.

Invoice Events

These are the events you may receive:

EventDescription
createdAn invoice has been created.
unpaidAn invoice has been marked as unpaid. This happens when you are done creating and adding details to the invoice and are ready to send it to the counterparty.
payment_pendingAn invoice has a pending payment order. This happens when a counterparty initiates a payment through the invoice's payment UI and creates a payment order.
paidAn invoice has been paid. This happens when the payment order that was created for paying the invoice completes successfully.
voidedAn invoice has been manually voided.
overdueAn invoice is overdue. This will be sent at 6am Pacific Time when the due_date is passed and the invoice has the status unpaid, which indicates the invoice was not paid by the expected date. For example, if you expected the invoice to be paid by Monday but it was not paid, this webhook will be sent on Tuesday at 6am PT.
When this event is sent, the status is unpaid.

An invoice's payment order's status changes will also transition the invoice's status accordingly:

Payment Order EventInvoice Status Change
completedpayment_pending to paid
cancelled, failed, reversedpayment_pending to unpaid
failed, reversed, returnedpaid to unpaid
Invoice webhooks and statuses. Asterisked events are triggered by the invoice's Payment Order.

Invoice webhooks and statuses. Asterisked events are triggered by the invoice's Payment Order.

Invoice Statuses

StatusDescription
draftThe invoice is still being edited/added to and not ready to send to the counterparty.
unpaidThe invoice is finalized and ready to send to the counterparty for payment collection.
payment_pendingThe counterparty has created a payment order for paying the invoice and is waiting for the payment order to complete.
paidThe invoice's payment order successfully completed and the invoice has been paid in full.
voidedThe invoice has been voided by the invoicer and cannot be reopened. This is a terminal state.

Sample Created Invoice Webhook Event

{
  "event": "unpaid",
  "data": {
    "id": "092b78c3-b3ce-4560-908f-08ad31e5fd86",
    "number": "2023-00006",
    "object": "invoice",
    "status": "unpaid",
    "pdf_url": "http://payments.moderntreasury.com/invoices/092b78c3-b3ce-4560-908f-08ad31e5fd86.pdf?organization_id=00112233-4455-6677-8899-aabbccddeeff",
    "currency": "USD",
    "due_date": "2023-04-29T23:37:23Z",
    "live_mode": true,
    "created_at": "2023-03-30T23:37:23Z",
    "hosted_url": "http://payments.moderntreasury.com/invoices/092b78c3-b3ce-4560-908f-08ad31e5fd86?organization_id=00112233-4455-6677-8899-aabbccddeeff",
    "updated_at": "2023-03-30T23:42:00Z",
    "description": "Invoice due by end of month.",
    "total_amount": 3920,
    "payment_orders": [],
    "contact_details": [],
    "counterparty_id": "f33226d7-a16f-41c2-94eb-1f807db4f6fb",
    "invoicer_address": {...},
    "originating_account_id": "97ecc158-209c-458f-a20c-da99e39e7487",
    "counterparty_billing_address": nil,
    "counterparty_shipping_address": nil
  }
}