Guides
System Status

Spend & Expense transaction notification payload

🚧

Limited access to Spend & Expense webhooks

At this time, the Spend & Expense webhooks are available only in the production environment. You can test with Spend & Expense transaction notifications in the sandbox environment only with GET /v3/subscriptions/{subscriptionId}/test.

This does not affect access to any other webhook in the sandbox environment.

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/spend/transactions in the API reference for more information about the response fields.

Prerequisites

  • Spend & Expense API token: When you create a subscription (POST v3/subscriptions) for a Spend & Expense event, the Spend & Expense apiToken header value is required for authentication. See Authentication with Spend & Expense API token for information about authentication for the Spend & Expense API endpoints.
  • Sample request: See Work with BILL webhooks for information about setting up a subscription for a Spend & Expense API event.

Sample spend.transaction.updated payload

In this sample unescaped JSON payload, the details of a Spend & Expense transaction are available. The notification provides a set of transaction fields.

FieldDescription
uuidBILL-generated UUID of the transaction
feesSum of transaction fees (including foreignExchangeFee)
foreignExchangeFeeForeign exchange fee for this transaction (if any)
transactionTypeTransaction type (CLEAR, DECLINE, AUTHORIZATION, or OTHER)
parentTransactionUuidBILL-generated UUID of the parent transaction. This field is set on child transactions when a parent transaction is split.
userUuidBILL-generated UUID of the user that created the transaction
rawMerchantNameRaw merchant name for the transaction
merchantNameReadable (cleaned) merchant name for the transaction
budgetUuidBILL-generated UUID of the budget linked with the transaction
originalAuthTransactionUuid

BILL-generated UUID of the originating authorization transaction.

After a transaction is authorized, it is set as cleared when it is complete. The originalAuthTransactionUuid ties the cleared transaction to the authorized transaction. The value is null when the transaction is not authorized.

occurredTimeCreated date and time
updatedTimeUpdated date and time
authorizedTimeTransaction authorized date and time
completeSet as true if the transaction has all the required fields completed
declineReasonTransaction decline reason. This field is available when transactionType is set as DECLINE.
declineInternalReasonCodeTransaction decline reason code
currencyDataTransaction currency information. In this object, exponent is the number of decimal places in the currency format.
amountTransaction amount
receiptStatusReceipt status (VALIDATED, NOT_VALIDATED, ATTACHED, MISSING, NOT_REQUIRED, or NOT_ATTACHED)
cardUuidBILL-generated UUID of the card used to make the transaction
companyUuidBILL-generated UUID of the company in your Spend & Expense account
merchantCategoryCodeMerchant category code
{
  "metadata": {
    "eventId": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
    "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
    "spendCompanyUuid": "9ddf9db2-210c-45cc-a5b8-c25f3f741721",
    "eventType": "spend.transaction.updated",
    "version": "1"
  },
  "transaction": {
    "uuid": "txr_9fiia79nt179111gr6ptuf4qmd",
    "fees": 3.21,
    "foreignExchangeFee": 2.98,
    "transactionType": "DECLINE",
    "parentTransactionUuid": null,
    "userUuid": "usr_8fe5a27i617a3557lirjoag5ks",
    "rawMerchantName": "AMZN Mktp US",
    "merchantName": "Amazon",
    "budgetUuid": "bgt_8rt78qggbl63j5ohq000m8qq85",
    "originalAuthTransactionUuid": "txr_pr7roo4vlp4jr7hvnm37mtpjeq",
    "occurredTime": "2026-12-30T18:23:01.211+00:00",
    "updatedTime": "2026-12-30T18:23:01.211+00:00",
    "authorizedTime": null,
    "complete": false,
    "declineReason": "CVV is invalid. Check if the CVV is correct and try again.",
    "declineInternalReasonCode": "invalid_cvc_code",
    "currencyData": {
      "exchangeRate": 1.0,
      "exponent": 2,
      "originalCurrencyAmount": "5303",
      "originalCurrencyCode": "USD",
      "symbol": "$"
    },
    "amount": 53.03,
    "receiptStatus": "NOT_ATTACHED",
    "cardUuid": "crd_p6ck386qk12cbbjkk8l687h901",
    "companyUuid": "cmp_jnfprch11h2sp9doo9fjut2wqa",
    "merchantCategoryCode": "5942"
  }
}

Fields that trigger spend.transactions.updated notifications

When changes are made to a set of fields in a transaction, the spend.transactions.updated event notification is triggered.

FieldDescription
transactionType

Transaction type (CLEAR, DECLINE, AUTHORIZATION, or OTHER).

Note: The AUTHORIZATION or DECLINE value is set when the transaction is created. The CLEAR value is set after BILL has moved money from the funding account. In addition, BILL may update a transaction a few minutes after the transaction is created.

parentTransactionUuidBILL-generated UUID of the parent transaction. This value is set on child transactions when a parent transaction is split.
budgetUuidBILL-generated UUID of the budget that this transaction belongs to
receiptStatusReceipt status (VALIDATED, NOT_VALIDATED, ATTACHED, MISSING, NOT_REQUIRED, or NOT_ATTACHED)

Notifications for a cleared transaction

For each cleared Spend & Expense transaction, you get a minimum of two event notifications. You get additional notifications when there a change in the fields that trigger notifications.

  1. When the transaction is created: BILL sends an event notification when the transactionType is set as AUTHORIZATION.
  2. When the transaction is cleared: BILL sends an event notification when the transactionType is set as CLEARED.

Updated 4 months ago

Did this page help you?