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 request, 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.