> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md
# Bill statuses and lifecycle
> Understand how a bill moves from created to paid, including approval, and what each status means
A bill is a record of a payment that a paypoint owes a vendor. It's the record Payabli pays when it processes a Pay Out transaction, much like an invoice is the record that's paid when Payabli processes a Pay In transaction. A bill's status tells you what state it's in on its journey to being paid.
To understand how bills differ from invoices, see [Bills and invoices](/guides/platform-bills-vs-invoices). For how bills fit into your wider accounts payable, see [Understanding payables](/guides/pay-out-payables-overview).
## A payout settles the bill
When a bill is paid, Payabli creates a Pay Out transaction — a payout — that settles it. The payout carries the bill through the rest of its lifecycle: the bill goes In Transit while the payout processes, then Paid once the payout settles.
How a bill reaches a payout depends on where you work. In the [Payabli Portal](/guides/pay-out-portal-bills-manage), you work bill-first: you create a bill, then pay it (even using a direct flow in the Virtual Terminal). Through the [API](/guides/pay-out-developer-payouts-manage), a payout request can pay existing bills, create a bill for you, or skip bills entirely with `doNotCreateBills` — so a bill isn't required to send a payout.
To create a bill, see [Create a bill (Portal)](/guides/pay-out-portal-bills-create). To find, edit, or pay an existing bill, see [Manage bills (Portal)](/guides/pay-out-portal-bills-manage). For the API, see [Manage bills with the API](/guides/pay-out-developer-bills-manage).
## Bill statuses
These statuses appear in the Payabli Portal and the API. They describe where a bill is in its lifecycle.
| Status | Key | Description | Events |
| ------------------ | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Active | 1 | The bill has been added for a vendor. It can be sent for approval or sent to payment. Only bills with an Active or Approved status can be sent for payment. | None |
| Sent to Approval | 2 | The bill has been sent to approval for payout. | None |
| Partially Approved | 5 | The bill has been partially approved for payout. | None |
| Rejected | 11 | The bill has been rejected and won't be paid. | BillDisApproved |
| Approved | 20 | The bill has been approved for payout. | BillApproved |
| In Transit | 50 | The payout for the bill is in transit. | BillProcessing |
| Paid | 100 | The bill has been paid. | BillPaid |
| Cancelled | -99 | The bill has been canceled. This is usually to correct the payment type. | BillCanceled |
If you are working with money out endpoints in the API, the **Key** is returned as `Status`. For example, a response body that includes bill data will look like this:
```json
// Example truncated to show the most relevant fields
{
"isSuccess": true,
"responseText": "Success",
"responseCode": 1,
"responseData": {
"IdBill": 364,
"BillNumber": "bill444",
...
"Status": 2,
...
}
}
```
The value of `Status` indicates the status. In the example, the `Status` is 2, which means the bill has been sent to approval.
## How a bill moves through statuses
Diagram: Bill status lifecycle
The diagram shows how a bill moves between its statuses:
* An **Active** (status 1) bill can be paid directly, or sent for approval.
* A bill **Sent to Approval** (status 2) becomes **Approved** (status 20), **Partially Approved** (status 5) when some but not all approvers have approved, or **Rejected** (status 11).
* A **Partially Approved** bill becomes **Approved** once all approvers approve.
* Only an **Active** or **Approved** bill can be paid. Paying a bill sends it **In Transit** (status 50), and it becomes **Paid** (status 100) when the payout settles.
* An **Active**, **Sent to Approval**, or **Approved** bill can be **Cancelled** (status -99), usually to correct the payment type.
Most bills follow the same path:
1. **Active** — You add the bill for a vendor. It's ready to pay, or to send for approval if your workflow requires one.
2. **Approved** — If the bill goes through approval, it becomes Approved once the approvers sign off. Approval is optional: an Active bill can be paid without it.
3. **In Transit** — You pay the bill, and the payout is on its way to the vendor.
4. **Paid** — The payout settles and the bill is complete.
Timing and triggers for **In Transit** and **Paid** vary by payables model and payment method. For Managed Payables, In Transit includes vendor enablement. Paid triggers only once the payment settles at the vendor's bank, which can take days for ACH or weeks for an uncashed check. See [Managed Payables](/guides/pay-out-managed-payables-overview) for details.
A bill can also leave this path. You can cancel an Active, Sent to Approval, or Approved bill, which moves it to **Cancelled**. A bill sent for approval can also end in **Rejected**. See [Bill approval](#bill-approval) for how the approval states work.
## Bill approval
Approval is optional. An **Active** bill is already eligible for payout, so a bill only needs approval when your workflow requires a sign-off before you pay a vendor. Approval runs through the API, and each step moves the bill to a new status.
When you send a bill to approval, it moves from **Active** to **Sent to Approval**, and it can't be paid until it's approved. From there it reaches one of:
* **Approved** — the approvers signed off. The bill is payout-eligible again, and you can pay it.
* **Partially Approved** — some, but not all, approvers have approved.
* **Rejected** — the bill won't be paid.
You assign approvers by email when you send the bill to approval. If an approver's email doesn't yet belong to a Payabli user, include `autocreateUser=true` so the request creates the user. Without it, the call returns a `400` error. For the endpoints and full workflow, see [Manage bills with the API](/guides/pay-out-developer-bills-manage).
## Related resources
See these related resources to help you get the most out of Payabli.
#### References
* **[Pay Out statuses](/guides/pay-out-status-reference)** - Learn about Pay Out statuses
#### Related topics
* **[Create a bill (Portal)](/guides/pay-out-portal-bills-create)** - Add vendor bills in the Payabli Portal, then send a payment link or pay with a stored method
* **[Manage bills (Portal)](/guides/pay-out-portal-bills-manage)** - Track, pay, and reconcile vendor bills from the Bills report
* **[Manage bills with the API](/guides/pay-out-developer-bills-manage)** - Learn how to add and manage bills for vendors via the API
* **[Manage payouts with the API](/guides/pay-out-developer-payouts-manage)** - Learn how to use the Payabli API to create, capture, and cancel payout transactions
* **[Understanding payables](/guides/pay-out-payables-overview)** - Learn about managing your payables and payouts with Payabli
* **[Bills and invoices](/guides/platform-bills-vs-invoices)** - Understand the difference between bills and invoices in Payabli