Bill approval workflows

In this section, we showcase a sample bill approval workflow. You can use this workflow for both bills and vendor credits. See the API reference for more information.

When an approval policy is in place for paying a bill, the bill payment requires approval if the amount is above the policy threshold. For example, if a policy requires approvals for all bill payments above $999, a bill payment of $1500 will be flagged for approval before the bill can be paid.

❗️

IMPORTANT

An organization user with the Administrator role can pay a bill regardless of any bill approval policy or the bill's approval status.

Ensure that users have specific permissions for managing approval policies, approvals, bills, and payments. See User roles and permissions in the BILL Help Center for more information.

BILL provides 2 options with which you can begin your approvals workflow. After following either method, you can approve bills with /v2/Approve.json.

OPTION 1: Setting approvers for a bill

In your /v2/SetApprovers.json request, set the required fields. Note that users with the Administrator, Accountant, or Approver roles can be added as approvers. See User roles and permissions in the BILL Help Center for more information.

📘

NOTE

When you set approvers to a bill for a vendor, the BILL web app's Smart Data feature is used to remember and automatically assign the same approvers on the next bill for the same vendor.

See Manage custom approval workflow and policies in the BILL Help Center for more information.

See Set approvers for a bill or vendor credit in the API reference for more information.

Sample request

In this cURL example, 2 users are added as approvers for a bill before the bill can be paid. The order in which the users are added is the sequence of approvals required.

curl --request POST \
--url 'https://api-sandbox.bill.com/api/v2/SetApprovers.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}' \
--data 'sessionId={session_id}' \
--data 'data={
  "entity":"Bill",
  "objectId":"{bill_id}",
  "approvers":["{user01_id}","{user02_id}"]
}'

When users are added as approvers for the bill, BILL sends an email notification to the approvers.

OPTION 2: Creating an approval policy

In your /v2/Crud/Create/ApprovalPolicy.json request, set the required fields. Note that users with the Administrator role can set up approval policies. See User roles and permissions in the BILL Help Center for more information.

❗️

IMPORTANT

When a bill is created with an amount above the policy threshold, attempting to pay the bill results in an error. Set approvers for the bill with /v2/SetApprovers.json. BILL sends an email notification to the approvers.

See Create an approval policy in the API reference for more information about the other fields you can set.

Sample request

In this cURL example, an bill approval policy is created with an amount threshold of $999. In addition, the approverNotSameAsPayer field is set as true for additional scrutiny. With this setting, the approver and payer cannot be the same user.

curl --request POST \
--url 'https://api-sandbox.bill.com/api/v2/Crud/Create/ApprovalPolicy.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}' \
--data 'sessionId={session_id}' \
--data 'data={
  "obj":{
     "entity":"ApprovalPolicy",
     "type":"0",
     "amountThreshold":999,
     "minNumApprovers":1,
     "approverNotSameAsPayer":true
     }
}'

Response

In the response, a BILL-generated approval policy id is available. The value begins with app.

After this approval policy is set up, when a bill is created that crosses the policy amount threshold of $999, attempting to pay the bill results in an error. Set approvers for the bill with /v2/SetApprovers.json. BILL sends an email notification to the approvers. Note that a user with the Administrator role can pay a bill regardless of the approval policy or the bill's approval status.

After setting up an approval policy, you can add new approvers to the policy with /v2/Crud/Create/ApprovalPolicyApprover.json. See Add an approval policy approver in the API reference for more information.

Approving a bill

In your /v2/Approve.json request, set the required fields. Note that users with the Administrator, Accountant, or Approver roles can approve bills. See User roles and permissions in the BILL Help Center for more information.

See Approve a bill or vendor credit in the API reference for more information.

Sample request

In this cURL example, a bill is approved for payment.

curl --request POST \
--url 'https://api-sandbox.bill.com/api/v2/Approve.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}' \
--data 'sessionId={session_id}' \
--data 'data={
  "entity" : "Bill",
  "objectId" : "{bill_id}"
}'

When the bill is approved, users with the Administrator or Payer roles can pay the bill.