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": 10000,
"tax": 0,
"total": 10000,
"amount_due": 10000,
"amount_paid": 0,
"amount_remaining": 10000
},
"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": "draft",
"status_label": "Draft",
"status_value": "draft",
"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": 10000,
"tax": 0,
"total": 10000,
"amount_due": 10000,
"amount_paid": 0,
"amount_remaining": 10000
},
"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": "open",
"status_label": "Open",
"status_value": "open",
"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": 10000,
"tax": 0,
"total": 10000,
"amount_due": 10000,
"amount_paid": 10000,
"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": 10000
},
"status": "paid",
"status_label": "Paid",
"status_value": "paid",
"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": 15000,
"tax": 0,
"total": 15000,
"amount_due": 15000,
"amount_paid": 0,
"amount_remaining": 15000
},
"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": "draft",
"status_label": "Draft",
"status_value": "draft",
"vendor": {
"object": "vendor",
"id": 789
}
},
"previous_attributes": {
"description": "Monthly service fee",
"subtotal": 10000,
"total": 10000,
"amount_due": 10000,
"amount_remaining": 10000
}
}
}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": "draft",
"status_label": "Draft",
"status_value": "draft"
}
}
}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 |
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 | string | Bill status: draft, open, paid, void |
status_label | string | Human-readable status label |
status_value | string | Status enum value |
user_id | integer | Vendor (user) ID |
vendor | object | Vendor information |
Amounts Object
| Field | Type | Description |
|---|---|---|
subtotal | integer | Subtotal before tax (in cents) |
tax | integer | Tax amount (in cents) |
total | integer | Total amount (in cents) |
amount_due | integer | Amount still owed (in cents) |
amount_paid | integer | Amount paid (in cents) |
amount_remaining | integer | Remaining balance (in cents) |
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 | Unix timestamp when the bill was finalized |
paid_at | integer | 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 | integer | Payment amount (in cents) |
Related
- Webhooks Overview - Setup, signatures, and configuration
Updated about 4 hours ago