Spend & Expense transaction notification payloads

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.

❗️
IMPORTANT
When you create a subscription (POST v3/subscriptions) for a Spend & Expense event, the 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 `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, if any, on this transaction
`transactionType`	Transaction type (`CLEAR`, `DECLINE`, `AUTHORIZATION`, or `OTHER`)
`parentTransactionUuid`	BILL-generated UUID of the parent transaction. This value 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 that this transaction belongs to
`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
`customFields`	Transaction custom fields information
`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",
    "customFields": [
      {
        "uuid": "{customfield_uuid}",
        "name": "Team offsite",
        "note": null,
        "selectedValues": "Food"
      }
    ],
    "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 bill, 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
`customFields`	Transaction custom fields information. Note: BILL will not send a notification when a custom field is updated with `PATCH /v3/spend/custom-fields/{customFieldId}`.
`receiptStatus`	Receipt status (`VALIDATED`, `NOT_VALIDATED`, `ATTACHED`, `MISSING`, `NOT_REQUIRED`, or `NOT_ATTACHED`)

❗️IMPORTANT

Sample spend.transaction.updated payload

Fields that trigger spend.transactions.updated notifications

❗️
IMPORTANT

Sample `spend.transaction.updated` payload

Fields that trigger `spend.transactions.updated` notifications