Transaction management
In this section, we walk through setting up custom fields for categorizing transactions in a Spend & Expense budget.
What is a custom field?
A custom field enables you to categorize transactions in a budget based on policies and projects in your organization. For example, you can tag transactions to a Team offsite
custom field based on different values, such as Travel
and Food
.
See How do I create custom fields for transactions in BILL Spend & Expense? in the BILL Help Center to learn about setting up custom fields with the BILL web app.
Creating a custom field
In your POST /v3/spend/custom-fields
, set the required fields.
Field | Description |
---|---|
name | Custom field name |
allowCustomValues | Set as true if the custom field allows adding custom values |
global | Set as true if the custom field applies to all budgets.If this value is set as false , the selectedBudgetIds array must be set as the list of budgets (id ) in which transactions can be tagged with this custom field. |
values | In the values array, set the list of options for the custom field. When these options are set, they are available in the custom field dropdown list.values is an optional field. |
See the /v3/spend/custom-fields API for more information about other custom field values you can set.
Sample request
In this cURL example, a custom field is created with the specified details. The custom field is set as global (applies to all budgets), and two option values
are added.
curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/spend/custom-fields' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"name": "Team offsite",
"allowCustomValues": false,
"global": true,
"values": [
"Travel",
"Food"
]
}'
Response
In the response, a BILL-generated custom field id
is available. There are additional boolean values in the response that are set to their default values. You can get the ID values of the custom field options with GET /v3/spend/custom-fields/{customFieldId}/values
.
{
"id": "{customfield_id}",
"name": "Team offsite",
"type": "CUSTOM_SELECTOR",
"multiSelect": false,
"allowCustomValues": false,
"required": false,
"global": true
}
See the /v3/spend/custom-fields API for more information about the complete list of Spend & Expense custom field operations.
Tagging a transaction with a custom field
When you create a custom field, you can then tag budget transactions with the custom field.
In your PUT /v3/spend/transactions/{transactionId}/custom-fields
request, set the required fields.
Field | Description |
---|---|
transactionId | BILL-generated ID of the transaction |
customFields | In the customFields array, set the customFieldId and selectedvalues fields for tagging the transaction with the custom field.You can get the ID values of the custom field options with GET /v3/spend/custom-fields/{customFieldId}/values . |
See the /v3/spend/transactions/{transactionId}/custom-fields API for more information about the other fields you can set.
Sample request
In this cURL example, a transaction is tagged with the custom field and option. You can get the ID values of the custom field options with GET /v3/spend/custom-fields/{customFieldId}/values
.
curl --request PUT \
--url 'https://gateway.stage.bill.com/connect/v3/spend/transactions/{transactionId}/custom-fields' \
--header 'apiToken: {api_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"customFields": [
{
"customFieldId": "{customfield_id}",
"selectedValues": [
"{option_id}"
]
}
]
}'
When the transaction is tagged, you can get updated details about the transaction with GET /v3/spend/transactions/{transactionId}
.
Transaction reporting enables you to view transactions in real-time. This information is useful for insights and forecasting. You can get an individual transaction or a list of transactions based on a range of filter and sort options.
See the /v3/spend/transactions API for more information about the fields that you can filter with and sort with.
Updated 30 days ago