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.

FieldDescription
nameCustom field name
allowCustomValuesSet as true if the custom field allows adding custom values
globalSet 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.
valuesIn 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.

FieldDescription
transactionIdBILL-generated ID of the transaction
customFieldsIn 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.