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. We will provide more information when these webhooks are available in the sandbox environment.
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 Working 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.

Field	Description
`uuid`	BILL-generated UUID of the transaction
`fees`	Sum of transaction fees (including `foreignExchangeFee`)
`foreignExchangeFee`	Foreign exchange fee for this transaction (if any)
`transactionType`	Transaction type (`CLEAR`, `DECLINE`, `AUTHORIZATION`, or `OTHER`)
`parentTransactionUuid`	BILL-generated UUID of the parent transaction. This field is set on child transactions when a parent transaction is split.
`userUuid`	BILL-generated UUID of the user that created the transaction
`rawMerchantName`	Raw merchant name for the transaction
`merchantName`	Readable (cleaned) merchant name for the transaction
`budgetUuid`	BILL-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.
`occurredTime`	Created date and time
`updatedTime`	Updated date and time
`authorizedTime`	Transaction authorized date and time
`complete`	Set as `true` if the transaction has all the required fields completed
`declineReason`	Transaction decline reason. This field is available when `transactionType` is set as `DECLINE`.
`declineInternalReasonCode`	Transaction decline reason code
`currencyData`	Transaction currency information. In this object, `exponent` is the number of decimal places in the currency format.
`amount`	Transaction amount
`receiptStatus`	Receipt status (`VALIDATED`, `NOT_VALIDATED`, `ATTACHED`, `MISSING`, `NOT_REQUIRED`, or `NOT_ATTACHED`)
`cardUuid`	BILL-generated UUID of the card used to make the transaction
`companyUuid`	BILL-generated UUID of the company in your Spend & Expense account
`merchantCategoryCode`	Merchant category code

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "spendCompanyUuid": "{S&E_company_uuid}",
    "eventType": "spend.transaction.updated",
    "version": "1"
  },
  "transaction": {
    "uuid": "{transaction_uuid}",
    "fees": 3.21,
    "foreignExchangeFee": 2.98,
    "transactionType": "DECLINE",
    "parentTransactionUuid": "{parent_transaction_uuid}",
    "userUuid": "{user_id}",
    "rawMerchantName": "AMZN Mktp US",
    "merchantName": "Amazon",
    "budgetUuid": "{budget_uuid}",
    "originalAuthTransactionUuid": "{originating_authorization_transaction}",
    "occurredTime": "2025-12-30T18:23:01.211+00:00",
    "updatedTime": "2025-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": "{card_uuid}",
    "companyUuid": "{company_uuid}",
    "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.

Field	Description
`transactionType`	Transaction type (`CLEAR`, `DECLINE`, `AUTHORIZATION`, or `OTHER`). Note: The `AUTHORIZATION` or `DECLINE` value is set at the time of the transaction. 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.
`parentTransactionUuid`	BILL-generated UUID of the parent transaction. This value is set on child transactions when a parent transaction is split.
`budgetUuid`	BILL-generated UUID of the budget that this transaction belongs to
`receiptStatus`	Receipt status (`VALIDATED`, `NOT_VALIDATED`, `ATTACHED`, `MISSING`, `NOT_REQUIRED`, or `NOT_ATTACHED`)

Updated 9 days ago