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.

Bill approval workflow options
OPTION 1: Set approvers for a created bill with /v2/SetApprovers.json. BILL sends an email notification to the approvers.
OPTION 2: Create an approval policy with /v2/Crud/Create/ApprovalPolicy.json.

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.

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.

FieldDescription
entityObject type. Set as Bill.
objectIdBILL-generated ID of the bill for which you want to set approvers
approversArray of BILL-generated ID of users that you want to set as approvers

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

FieldDescription
entityObject type. Set as ApprovalPolicy.
typeApproval policy type (0: Bill, 1: Vendor credit)
amountThresholdPayment amount threshold for the policy
minNumApproversMinimum number of required 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-stage.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.

FieldDescription
entityObject type. Set as Bill.
objectIdBILL-generated ID of the bill to approve

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