Manage bills with the API

In Payabli, bills represent a bill from a vendor that a paypoint is expected to pay. Use managed payables with Payabli to turn those payouts to vendors into an income stream.

Basic bill workflow

1. When you get an invoice from a vendor or supplier, add it to Payabli as a bill via the API, File Exchange, or the web.
2. Update or delete bills, and then queue them for approval.
3. After bills are approved, make payout requests, and you can pay one or many bills.

Via an enablement process, your vendors are contacted to help decide on a payment method. The goal is that they choose to receive payments through virtual cards for ease, speed, and security of payment.

Considerations

Keep these points in mind when working with bills:

• You don’t have to use Payabli’s bill engine to make a payout. When making a payout request, set the query parameter doNotCreateBills to true.
• Payabli strongly recommends including bill images with your bills. Including bill images can make payouts faster, more accurate, and prevent problems.
• You can pay more than one bill with one payout request. If several active bills added, queued, and ready to be paid, you can make a payout request to pay all active bills. Remittance information for that single payout request will include the details for all of the paid bills.
• Bill approval isn’t required. If a bill status is Active (1) or Approved (20) it can be sent for payout. If a bill status is Sent to Approval (2) you can’t send it for payout. For the full numeric mapping, see Bill statuses.
• You can use the OCR engine to capture data from uploaded bill images.

Create a bill

To create a single bill, send a POST request to /api/Bill/single/{entry}.

For complete information, see the API reference.

This example adds a bill to the entrypoint with ID 8cfec329267. The bill is for a vendor with the vendorNumber VEN-123. The bill number is ABC-123, and the request includes an uploaded bill image, and optional fields like comments. The status is 1 (Active), so the bill is payout-eligible. See Bill statuses for the other values.

curl -X POST https://api-sandbox.payabli.com/api/Bill/single/8cfec329267 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "accountingField1": "MyInternalId",
  "attachments": [
    {
      "filename": "my-doc.pdf",
      "ftype": "pdf",
      "furl": "https://mysite.com/my-doc.pdf"
    }
  ],
  "billDate": "2024-07-01",
  "billItems": [
    {
      "itemCategories": [
        "deposits"
      ],
      "itemCommodityCode": "010",
      "itemCost": 5,
      "itemDescription": "Deposit for materials",
      "itemMode": 0,
      "itemProductCode": "M-DEPOSIT",
      "itemProductName": "Materials deposit",
      "itemQty": 1,
      "itemTaxAmount": 7,
      "itemTaxRate": 0.075,
      "itemTotalAmount": 123,
      "itemUnitOfMeasure": "SqFt"
    }
  ],
  "billNumber": "ABC-123",
  "comments": "Deposit for materials",
  "dueDate": "2024-07-01",
  "endDate": "2024-07-01",
  "frequency": "monthly",
  "mode": 0,
  "netAmount": 3762.87,
  "status": 1,
  "terms": "NET30",
  "vendor": {
    "vendorNumber": "VEN-123"
  }
}'

A successful response returns the bill ID in the responseData field.

{
  "responseText": "Success",
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseData": 6101
}

If your workflow requires bill approval, you can send the bill to approval with the API. For more information, see Send a bill to approval.

If an approver’s email doesn’t yet belong to a Payabli user, include the autocreateUser=true query parameter so the request creates the user. Without it, the call returns a 400 error with the message Empty approvals.

After your bill is approved you can make a payout request to pay the bill. For more information, see Make a payout request.

Attach a bill image

Payabli recommends attaching a bill image to every bill — it makes payouts faster and more accurate. Add images with the attachments array when you create the bill.

Each attachment is a file object with a filename, an ftype (pdf, doc, docx, jpg, jpeg, png, gif, or txt), and the file itself, provided one of two ways:

• Base64-encoded content in fContent.
• A public URL in furl that Payabli fetches the file from. When you set furl, Payabli ignores fContent.

Payabli stores the file with the bill either way. The maximum upload size is 30 MB.

{
  "billNumber": "ABC-123",
  "netAmount": 100.00,
  "billDate": "2026-08-20",
  "dueDate": "2026-09-20",
  "vendor": {
    "vendorNumber": "VEN-123"
  },
  "attachments": [
    {
      "ftype": "pdf",
      "filename": "invoice.pdf",
      "furl": "https://example.com/invoice.pdf"
    }
  ]
}

See Add bill for the full API reference.

Apply a credit to a bill

If a vendor offers a credit against a bill, record it with the bill’s discount field when you create the bill. When you pay the bill, the payout pays the net amount after the credit, and the credit flows through to your reconciliation data.

Set the bill amounts like this:

• discount is the credit applied to the bill.
• netAmount is the bill total minus the discount. This is the amount you actually pay.

discount plus netAmount equals the original bill total. For example, a $100.00 bill with a $25.00 credit has a netAmount of 75.00 and a discount of 25.00:

{
  "billNumber": "ABC-123",
  "netAmount": 75.00,
  "discount": 25.00,
  "billDate": "2024-12-01",
  "dueDate": "2024-12-31",
  "comments": "Credit Memo 1234",
  "vendor": {
    "vendorNumber": "VEN-123"
  }
}

To record a credit memo number, use the comments field.

Import bills

You can import a list of bills into Payabli using the API. This is useful if you have many bills to add at once, or if you want to automate the process. Before you get started, download the example CSV file and open it with the editor of your choice. Use it as an example to help you build your import file.

To create a bill, send a POST request to the /api/Import/billsForm/{entrypoint} endpoint, with an attached CSV file.

This example imports billImport.csv for the entrypoint e56ce00572.

curl -X POST https://api-sandbox.payabli.com/api/Import/billsForm/8cfec329267 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: multipart/form-data" \
     -F file=@<file1>

A successful request returns a JSON response with the number of added and rejected records, and any errors. The imported data is now available for use, and you can confirm by checking the Payabli Portal.

{
  "responseText": "Success",
  "isSuccess": true,
  "pageIdentifier": "null",
  "responseCode": 1,
  "responseData": {
    "added": 26,
    "errors": [
      "errors",
      "errors"
    ],
    "rejected": 2
  }
}

After you import bills, you can manage them with the API. For example, you can update or delete bills, send them for approval, and create payout requests.

Partially pay a bill

If you’re using managed payables, you can pay part of a bill instead of the full amount. To pay part of a bill, send a payout for a single bill whose totalAmount is less than the bill’s outstanding balance. The bill moves to Partially Paid status (75) and stays selectable for further payment until it’s fully paid.

Each bill response includes two fields for tracking the balance:

• paidAmount — the amount paid toward the bill so far.
• outstandingBalance — the amount still owed, calculated as netAmount minus paidAmount.

To check a bill’s remaining balance at any time, get the bill or list bills and read outstandingBalance. It reaches 0 when the bill is fully paid, and you can filter for bills that still owe a balance with the Partially Paid status (?status=75).

Subscribe to the BillPartiallyPaid webhook to be notified each time a partial payout posts. Paying more than the outstanding balance returns error 3448, a request with more than one bill returns 3451, and paying a bill that’s already fully paid returns 3411.

Manage bills

You can also manage your bills via the API. See these endpoint references for more information:

• Update a bill
• Delete a bill
• Send a bill to approval
• Approve a bill

Related resources

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