Guides
System Status
Start typing to search…

Invoice notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/invoices in the API reference for more information about the request and response fields.

Sample invoice.created payload

In this sample unescaped JSON payload, the details of a created invoice are available.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "invoice.created",
    "version": 1
  },
  "invoice": {
    "id": "{invoice_id}",
    "customerId": "{customer_id}",
    "archived": false,
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-20",
    "dueDate": "2025-12-20",
    "totalAmount": 120.00,
    "dueAmount": 120.00,
    "createdTime": "2025-12-15T23:15:23.127+00:00",
    "updatedTime": "2025-12-15T23:15:23.127+00:00",
    "status": "OPEN",
    "scheduledAmount": 0.00,
    "creditAmount": 0.00,
    "salesTaxTotal": 0.00,
    "salesTaxPercentage": 0
  }
}

Sample invoice.updated payload

In this sample unescaped JSON payload, the details of an updated invoice are available.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "invoice.updated",
    "version": 1
  },
  "invoice": {
    "id": "{invoice_id}",
    "customerId": "{customer_id}",
    "archived": false,
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-20",
    "dueDate": "2025-12-20",
    "totalAmount": 120.00,
    "dueAmount": 0.00,
    "createdTime": "2025-12-15T23:15:23.127+00:00",
    "updatedTime": "2025-12-20T23:15:23.127+00:00",
    "status": "PAID_IN_FULL",
    "scheduledAmount": 0.00,
    "creditAmount": 0.00,
    "salesTaxTotal": 0.00,
    "salesTaxPercentage": 0
  }
}

Fields that trigger invoice.updated notifications

When changes are made to a set of fields in an invoice, the invoice.updated event notification is triggered.

FieldDescription
totalAmountInvoice total amount
statusInvoice status
invoice.invoiceNumberUser-generated invoice number. This value can be your chosen number scheme.

Sample invoice.archived payload

In this sample unescaped JSON payload, the details of an archived invoice are available. The archived field is set as true.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "invoice.archived",
    "version": 1
  },
  "invoice": {
    "id": "{invoice_id}",
    "customerId": "{customer_id}",
    "archived": true,
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-20",
    "dueDate": "2025-12-20",
    "totalAmount": 120.00,
    "dueAmount": 120.00,
    "createdTime": "2025-12-15T23:15:23.127+00:00",
    "updatedTime": "2025-12-16T23:15:23.127+00:00",
    "status": "OPEN",
    "scheduledAmount": 0.00,
    "creditAmount": 0.00,
    "salesTaxTotal": 0.00,
    "salesTaxPercentage": 0
  }
}

Sample invoice.restored payload

In this sample unescaped JSON payload, the details of a restored invoice are available. The archived field is set as false.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "invoice.restored",
    "version": 1
  },
  "invoice": {
    "id": "{invoice_id}",
    "customerId": "{customer_id}",
    "archived": false,
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-20",
    "dueDate": "2025-12-20",
    "totalAmount": 120.00,
    "dueAmount": 120.00,
    "createdTime": "2025-12-15T23:15:23.127+00:00",
    "updatedTime": "2025-12-17T23:15:23.127+00:00",
    "status": "OPEN",
    "scheduledAmount": 0.00,
    "creditAmount": 0.00,
    "salesTaxTotal": 0.00,
    "salesTaxPercentage": 0
  }
}

Updated about 13 hours ago