Send paymentsBills and payment links

Bill statuses and lifecycle

Understand how a bill moves from created to paid, including approval, and what each status means
View as MarkdownOpen in Claude
Applies to:DevelopersPartnersPaypoints

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. For how bills fit into your wider accounts payable, see Understanding payables.

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, you work bill-first: you create a bill, then pay it (even using a direct flow in the Virtual Terminal). Through the API, 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). To find, edit, or pay an existing bill, see Manage bills (Portal). For the API, see Manage bills with the API.

Bill statuses

These statuses appear in the Payabli Portal and the API. They describe where a bill is in its lifecycle.

StatusKeyDescriptionEvents
Active1The 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 Approval2The bill has been sent to approval for payout.None
Partially Approved5The bill has been partially approved for payout.None
Rejected11The bill has been rejected and won’t be paid.BillDisApproved
Approved20The bill has been approved for payout.BillApproved
In Transit50The payout for the bill is in transit.BillProcessing
Paid100The bill has been paid.BillPaid
Cancelled-99The 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:

1// Example truncated to show the most relevant fields
2{
3  "isSuccess": true,
4  "responseText": "Success",
5  "responseCode": 1,
6  "responseData": {
7    "IdBill": 364,
8    "BillNumber": "bill444",
9...
10    "Status": 2,
11...
12 }
13}

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

Bill status lifecycle from Active through approval to In Transit and Paid, with Rejected and Cancelled end states
Click to expand

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 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 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.

See these related resources to help you get the most out of Payabli.