--- updatedAt: 2026-02-24T16:36:40.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # 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`](#billcreated) | A new bill was created | | [`bill.finalized`](#billfinalized) | A bill was finalized and moved to open status | | [`bill.paid`](#billpaid) | A bill was marked as paid | | [`bill.updated`](#billupdated) | An existing bill was modified | | [`bill.deleted`](#billdeleted) | A bill was deleted | *** ## bill.created ### Triggered When * A bill is created via the Core API * A bill is created from the Platform ### Payload ```json { "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": "vendor@example.com", "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 ```json { "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 ```json { "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. ```json { "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 ```json { "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](webhooks) - Setup, signatures, and configuration # Sibling pages * [Email Templates](https://docs.pelcro.com/v2.4/docs/e-mail-templates-for-webhooks.md) * [Addresses](https://docs.pelcro.com/v2.4/docs/webhooks-addresses.md) * [Campaigns](https://docs.pelcro.com/v2.4/docs/webhooks-campaigns.md) * [Charges](https://docs.pelcro.com/v2.4/docs/webhooks-charges.md) * [Customers](https://docs.pelcro.com/v2.4/docs/webhooks-customers.md) * [Exports](https://docs.pelcro.com/v2.4/docs/webhooks-exports.md) * [Fraud Prevention](https://docs.pelcro.com/v2.4/docs/webhooks-fraud-prevention.md) * [Invoices](https://docs.pelcro.com/v2.4/docs/webhooks-invoices.md) * [Members](https://docs.pelcro.com/v2.4/docs/webhooks-members.md) * [Newsletters](https://docs.pelcro.com/v2.4/docs/webhooks-newsletters.md) * [Orders](https://docs.pelcro.com/v2.4/docs/webhooks-orders.md) * [Payment Methods](https://docs.pelcro.com/v2.4/docs/webhooks-payment-methods.md) * [Plans](https://docs.pelcro.com/v2.4/docs/webhooks-plans.md) * [Products](https://docs.pelcro.com/v2.4/docs/webhooks-products.md) * [Subscriptions](https://docs.pelcro.com/v2.4/docs/webhooks-subscriptions.md) * [Vendors](https://docs.pelcro.com/v2.4/docs/webhooks-vendors.md)