Invoice Webhooks

Invoice webhooks apply to invoice-based billing. Use them to keep the invoice status in your system the same as in Dodo Payments.

Invoice Webhook Events

Event	Fires when
`invoice.finalized`	An invoice is finalized.
`invoice.sent`	You send an invoice, Dodo Payments sends a renewal invoice, or the hosted link is first created.
`invoice.paid`	An invoice is paid, including a $0 invoice at finalize.
`invoice.payment_failed`	An automatic charge fails.
`invoice.past_due`	An invoice becomes past due.
`invoice.reopened`	A past-due invoice becomes open after a due date change.
`invoice.voided`	An invoice is voided.
`invoice.marked_uncollectable`	An invoice is marked uncollectable.

The payload shows the invoice at the time of delivery, not at the time of the event. Read status from the payload, and do not assume it from the event type.

Handling Invoice Events

Handling invoice events

app.post('/webhooks/dodo', async (req, res) => {
  // Verify the signature first. See /developer-resources/webhooks#verifying-signatures.
  const event = JSON.parse(req.body);
  const invoice = event.data;

  switch (event.type) {
    case 'invoice.paid':
      await markInvoicePaid(invoice.invoice_id, invoice.amount_paid);
      break;
    case 'invoice.past_due':
      await notifyAccountManager(invoice.invoice_id, invoice.amount_due);
      break;
    case 'invoice.voided':
    case 'invoice.marked_uncollectable':
      await closeInvoice(invoice.invoice_id, invoice.status);
      break;
  }

  res.json({ received: true });
});

Refunds and disputes on invoice payments send the refund and dispute events.

Webhook Payload Schema

An invoice-led invoice. Every read and every invoice.* webhook uses this schema.

allowed_actions

enum<string>[]

required

The actions that the current status accepts.

An action that a merchant can request on the invoice in its current status.

Available options:

edit,

finalize,

delete,

send,

retry,

void,

mark_uncollectable,

change_dunning,

add_note,

duplicate

amount_due

integer<int64>

required

The amount that the customer must pay. Zero unless the invoice is open or past due.

amount_paid

integer<int64>

required

The sum of the succeeded payments, in the smallest currency unit. A late payment is not included after its late refund.

amount_refunded

integer<int64>

required

The sum of the succeeded refunds, in the currency of each payment. The late refund of a late payment is not included.

billing_mode

enum<string>

required

Available options:

normal,

invoice_led

business_id

string

required

created_at

string<date-time>

required

credits

integer<int64>

required

Customer credits applied at finalise, in the smallest currency unit. Zero or less.

currency

enum<string>

required

Available options:

AED,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BWP,

BYN,

BZD,

CAD,

CHF,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SEK,

SGD,

SHP,

SLE,

SLL,

SOS,

SRD,

SSP,

STN,

SVC,

SZL,

THB,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

customer

object

required

Show child attributes

discount_ids

string[]

required

The discount codes of the invoice.

editable_fields

enum<string>[]

required

The fields that PATCH can change in the current status.

Available options:

customer,

items,

discounts,

currency,

billing_address,

tax_id,

review_required,

due_at,

collection_method,

memo,

customer_email,

cc_emails,

dunning,

metadata

frequency

One Time · object

required

How often the invoice lines bill. mixed covers several intervals, or one-time lines next to a plan.

One Time
Recurring
Mixed

Show child attributes

invoice_id

string

required

metadata

object

required

refund_ids

string[]

required

retry_count

integer<int32>

required

The number of failed automatic charges.

row_version

integer<int64>

required

Goes up by one on each change. Use it to ignore an older webhook delivery.

status

enum<string>

required

The message of each variant is the label of the invoice document.

Available options:

open,

paid,

void,

draft,

past_due,

uncollectable

subscription_ids

string[]

required

tags

enum<string>[]

required

Available options:

refunded,

partially_refunded,

disputed,

payment_reversed

tax

integer<int32>

required

Tax in the smallest currency unit.

total_amount

integer<int32>

required

Total with tax, before credits, in the smallest currency unit.

collection_method

null | enum<string>

Available options:

auto_charge,

manual

due_at

string<date-time> | null

dunning_state

null | enum<string>

null for an invoice that has no collection: draft, paid, void or uncollectable.

Available options:

not_started,

active,

paused,

exhausted

finalized_at

string<date-time> | null

hosted_url

string | null

The page where the customer pays. null until the invoice is sent.

lines

object[] | null

Only on a single invoice. A list leaves it out.

Show child attributes

memo

string | null

next_reminder_at

string<date-time> | null

The time of the next reminder email to the customer, before or after the due date. null when no reminder email will go out.

next_retry_at

string<date-time> | null

payment_terms_days

integer<int32> | null

Days from finalise to the due date. null when the invoice has a custom due date.

payments

object[] | null

Only on a single invoice. A list leaves it out.

Show child attributes

pdf_url

string | null

reminder_settings

Snapshot · object

null on a draft that keeps all reminder settings of the business.

Snapshot
Override

Show child attributes

review_deadline

string<date-time> | null

The time at which a draft that waits for review finalises.

sent_at

string<date-time> | null

Last modified on November 12, 2026

{
  "allowed_actions": [],
  "amount_due": 123,
  "amount_paid": 123,
  "amount_refunded": 123,
  "business_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "credits": 123,
  "customer": {
    "billing_address": {
      "city": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipcode": "<string>"
    },
    "cc_emails": [
      "<string>"
    ],
    "customer_id": "<string>",
    "email": "<string>",
    "tax_id": "<string>"
  },
  "discount_ids": [
    "<string>"
  ],
  "editable_fields": [],
  "frequency": {
    "type": "one_time"
  },
  "invoice_id": "<string>",
  "metadata": {},
  "refund_ids": [
    "<string>"
  ],
  "retry_count": 123,
  "row_version": 123,
  "subscription_ids": [
    "<string>"
  ],
  "tags": [],
  "tax": 123,
  "total_amount": 123,
  "due_at": "2023-11-07T05:31:56Z",
  "finalized_at": "2023-11-07T05:31:56Z",
  "hosted_url": "<string>",
  "lines": [
    {
      "amount": 123,
      "quantity": 123,
      "tax": 123,
      "tax_inclusive": true,
      "unit_amount": 123,
      "addon_id": "<string>",
      "description": "<string>",
      "name": "<string>",
      "period_end": "2023-11-07T05:31:56Z",
      "period_start": "2023-11-07T05:31:56Z",
      "product_id": "<string>",
      "subscription_id": "<string>",
      "tax_rate": 123
    }
  ],
  "memo": "<string>",
  "next_reminder_at": "2023-11-07T05:31:56Z",
  "next_retry_at": "2023-11-07T05:31:56Z",
  "payment_terms_days": 123,
  "payments": [
    {
      "amount": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "payment_id": "<string>",
      "retry_attempt": 123
    }
  ],
  "pdf_url": "<string>",
  "reminder_settings": {
    "kind": "snapshot",
    "offsets_minutes": [
      123
    ],
    "paused": true,
    "reminders_enabled": true
  },
  "review_deadline": "2023-11-07T05:31:56Z",
  "sent_at": "2023-11-07T05:31:56Z"
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Invoice Webhook Events

Handling Invoice Events

Webhook Payload Schema

​Invoice Webhook Events

​Handling Invoice Events

​Webhook Payload Schema

Invoice Webhook Events

Handling Invoice Events

Webhook Payload Schema