Bills
Receive notifications when bills are created, finalized, paid, updated, or deleted.
Overview
Bill webhooks notify your application when vendor bills are created, modified, or paid. Use these events to integrate with your accounts payable systems and track vendor payments.
Use Cases
- Sync bills to your accounting system (QuickBooks, Xero, etc.)
- Trigger approval workflows when new bills are created
- Update payment records when bills are paid
- Track vendor spending and payment history
- Automate payment reminders for unpaid bills
Events
| Event | Description |
|---|---|
bill.created | A new bill was created |
bill.finalized | A bill was finalized and moved to open status |
bill.paid | A bill was marked as paid |
bill.updated | An existing bill was modified |
bill.deleted | A bill was deleted |
bill.created
Triggered When
- A bill is created via the Core API
- A bill is created from the Platform
Payload
{
"type": "bill.created",
"id": "evt_a1b2C3d4E5f6g7H8i9J0k1L2",
"created": 1704067200,
"data": {
"bill": {
"object": "bill",
"id": 123,
"account_id": 456,
"amounts": {
"subtotal": 100.00,
"tax": null,
"total": 100.00,
"amount_due": 100.00,
"amount_paid": 0,
"amount_remaining": 100.00
},
"currency": "usd",
"dates": {
"created_at": 1704067200,
"updated_at": 1704067200,
"finalized_at": null,
"paid_at": null
},
"description": "Monthly service fee",
"line_items": [
{
"object": "bill_line_item",
"id": 789,
"amounts": {
"unit_price": 10000,
"quantity": 1,
"subtotal": 10000
},
"dates": {
"created_at": 1704067200,
"updated_at": 1704067200
},
"description": "Consulting services"
}
],
"number": "BILL-0001",
"paid": false,
"status": 3,
"status_label": "Draft",
"status_value": 3,
"user_id": 789,
"vendor": {
"object": "vendor",
"id": 789,
"dates": {
"created_at": 1704067200,
"updated_at": 1704067200
},
"email": "[email protected]",
"first_name": "Vendor",
"last_name": "Company"
}
}
}
}bill.finalized
Triggered When
- A draft bill is finalized via the Core API (moves to "open" status)
- A bill is finalized from the Platform
Payload
{
"type": "bill.finalized",
"id": "evt_b2C3d4E5f6g7H8i9J0k1L2m3",
"created": 1704153600,
"data": {
"bill": {
"object": "bill",
"id": 123,
"account_id": 456,
"amounts": {
"subtotal": 100.00,
"tax": null,
"total": 100.00,
"amount_due": 100.00,
"amount_paid": 0,
"amount_remaining": 100.00
},
"bill_pdf": "https://example.com/bills/123.pdf",
"currency": "usd",
"dates": {
"created_at": 1704067200,
"updated_at": 1704153600,
"finalized_at": 1704153600,
"paid_at": null
},
"hosted_bill_url": "https://example.com/bills/123",
"number": "BILL-0001",
"paid": false,
"status": 2,
"status_label": "Open",
"status_value": 2,
"vendor": {
"object": "vendor",
"id": 789
}
}
}
}bill.paid
Triggered When
- An open bill is marked as paid via the Core API
- A bill is marked as paid from the Platform
Payload
{
"type": "bill.paid",
"id": "evt_c3D4e5F6g7H8i9J0k1L2m3N4",
"created": 1704240000,
"data": {
"bill": {
"object": "bill",
"id": 123,
"account_id": 456,
"amounts": {
"subtotal": 100.00,
"tax": null,
"total": 100.00,
"amount_due": 100.00,
"amount_paid": 100.00,
"amount_remaining": 0
},
"currency": "usd",
"dates": {
"created_at": 1704067200,
"updated_at": 1704240000,
"finalized_at": 1704153600,
"paid_at": 1704240000
},
"number": "BILL-0001",
"paid": true,
"payment": {
"paid": true,
"paid_at": 1704240000,
"amount_paid": 100.00
},
"status": 1,
"status_label": "Paid",
"status_value": 1,
"vendor": {
"object": "vendor",
"id": 789
}
}
}
}bill.updated
Triggered When
- A bill is updated via the Core API
- A bill is updated from the Platform
Payload
The payload includes a previous_attributes object containing only the fields that changed.
{
"type": "bill.updated",
"id": "evt_d4E5f6G7h8I9j0K1l2M3n4O5",
"created": 1704326400,
"data": {
"bill": {
"object": "bill",
"id": 123,
"account_id": 456,
"amounts": {
"subtotal": 150.00,
"tax": null,
"total": 150.00,
"amount_due": 150.00,
"amount_paid": 0,
"amount_remaining": 150.00
},
"currency": "usd",
"dates": {
"created_at": 1704067200,
"updated_at": 1704326400,
"finalized_at": null,
"paid_at": null
},
"description": "Updated service fee",
"number": "BILL-0001",
"paid": false,
"status": 3,
"status_label": "Draft",
"status_value": 3,
"vendor": {
"object": "vendor",
"id": 789
}
},
"previous_attributes": {
"description": "Monthly service fee",
"subtotal": 100.00,
"total": 100.00,
"amount_due": 100.00,
"amount_remaining": 100.00
}
}
}bill.deleted
Triggered When
- A bill is deleted via the Core API
Payload
{
"type": "bill.deleted",
"id": "evt_e5F6g7H8i9J0k1L2m3N4o5P6",
"created": 1704412800,
"data": {
"bill": {
"object": "bill",
"id": 123,
"account_id": 456,
"deleted_at": 1704412800,
"number": "BILL-0001",
"status": 3,
"status_label": "Draft",
"status_value": 3
}
}
}Payload Fields
Bill Object
| Field | Type | Description |
|---|---|---|
object | string | Object type identifier, always bill |
id | integer | Unique identifier for the bill |
account_id | integer | Account that owns this bill |
amounts | object | Amount breakdown (see below) |
bill_pdf | string | URL to the bill PDF (after finalization) |
currency | string | Three-letter ISO currency code |
dates | object | Timestamp information (see below) |
description | string | Bill description |
footer | string | Footer notes |
hosted_bill_url | string | URL to view the bill online |
line_items | array | List of line items on the bill |
metadata | object | Custom key-value metadata |
notes | string | Additional notes (populated from footer field) |
number | string | Bill reference number |
paid | boolean | Whether the bill has been paid |
payment | object | Payment details (when paid) |
purchase_order | string | Purchase order reference |
status | integer | Bill status code: 1 (paid), 2 (open), 3 (draft) |
status_label | string | Human-readable status label: "Paid", "Open", "Draft" |
status_value | integer | Status enum backing value: 1 (paid), 2 (open), 3 (draft) |
user_id | integer | Vendor (user) ID |
vendor | object | Vendor information |
Amounts Object
| Field | Type | Description |
|---|---|---|
subtotal | float | Subtotal before tax (in dollars) |
tax | float/null | Tax amount (in dollars, or null if not set) |
total | float | Total amount (in dollars) |
amount_due | float | Amount still owed (in dollars) |
amount_paid | float | Amount paid (in dollars) |
amount_remaining | float | Remaining balance (in dollars) |
Dates Object
| Field | Type | Description |
|---|---|---|
created_at | integer | Unix timestamp when the bill was created |
updated_at | integer | Unix timestamp when the bill was last modified |
finalized_at | integer/null | Unix timestamp when the bill was finalized |
paid_at | integer/null | Unix timestamp when the bill was paid |
Payment Object (when paid)
| Field | Type | Description |
|---|---|---|
paid | boolean | Payment confirmation |
paid_at | integer | Unix timestamp when payment was received |
amount_paid | float | Payment amount (in dollars) |
Line Item Object
| Field | Type | Description |
|---|---|---|
object | string | Object type identifier, always bill_line_item |
id | integer | Unique identifier for the line item |
amounts | object | Amount breakdown (see below) |
dates | object | Timestamp information |
description | string | Line item description |
metadata | object | Custom key-value metadata |
period | object | Service period (if applicable) |
Line Item Amounts Object
| Field | Type | Description |
|---|---|---|
unit_price | integer | Price per unit (in cents) |
quantity | integer | Number of units |
subtotal | integer | Total for line item (in cents): unit_price × quantity |
Related
- Webhooks Overview - Setup, signatures, and configuration
Updated 21 days ago