Guides
System Status
Start typing to search…

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.

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": "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.

Field

Description

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.

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)

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 20 days ago