Spend & Expense transaction notification payload
Limited access to Spend & Expense webhooksAt 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 & ExpenseapiToken
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
spend.transaction.updated
payloadIn this sample unescaped JSON payload, the details of a Spend & Expense transaction are available. The notification provides a set of transaction
fields.
Field | Description |
---|---|
| BILL-generated UUID of the transaction |
| Sum of transaction fees (including |
| Foreign exchange fee for this transaction (if any) |
| Transaction type ( |
| BILL-generated UUID of the parent transaction. This field is set on child transactions when a parent transaction is split. |
| BILL-generated UUID of the user that created the transaction |
| Raw merchant name for the transaction |
| Readable (cleaned) merchant name for the transaction |
| BILL-generated UUID of the budget linked with the transaction |
| BILL-generated UUID of the originating authorization transaction. After a transaction is authorized, it is set as cleared when it is complete. The |
| Created date and time |
| Updated date and time |
| Transaction authorized date and time |
| Set as |
| Transaction decline reason. This field is available when |
| Transaction decline reason code |
| Transaction currency information. In this object, |
| Transaction amount |
| Receipt status ( |
| BILL-generated UUID of the card used to make the transaction |
| BILL-generated UUID of the company in your Spend & Expense account |
| 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
spend.transactions.updated
notificationsWhen changes are made to a set of fields in a transaction, the spend.transactions.updated
event notification is triggered.
Field | Description |
---|---|
| Transaction type (
|
| BILL-generated UUID of the parent transaction. This value is set on child transactions when a parent transaction is split. |
| BILL-generated UUID of the budget that this transaction belongs to |
| Receipt status ( |
Updated about 22 hours ago