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.
Field | Description |
---|---|
entity | Object type. Set as Bill . |
objectId | BILL-generated ID of the bill for which you want to set approvers |
approvers | Array 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.
Field | Description |
---|---|
entity | Object type. Set as ApprovalPolicy . |
type | Approval policy type (0 : Bill, 1 : Vendor credit) |
amountThreshold | Payment amount threshold for the policy |
minNumApprovers | Minimum 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.
Field | Description |
---|---|
entity | Object type. Set as Bill . |
objectId | BILL-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.
Updated 4 months ago