Spend & Expense reimbursement 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 reimbursement 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/reimbursements 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.reimbursement.created payload

In this sample unescaped JSON payload, the details of a created reimbursement are available. The notification provides a set of reimbursement fields.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "spendCompanyUuid": "{S&E_company_uuid}",
    "eventType": "spend.reimbursement.created",
    "version": "1"
  },
  "reimbursement": {
    "uuid": "{reimbursement_uuid}",
    "note": "Holiday party office expenses",
    "merchantName": "Amazon",
    "amount": 1200.0,
    "status": "CREATED",
    "fulfillmentType": "ACH",
    "budgetUuid": "{budget_uuid}",
    "companyUuid": "{company_uuid}",
    "userUuid": "\{user_uuid}",
    "occurredTime": "2026-12-30T00:00:00.000+00:00",
    "updatedTime": "2026-12-30T18:23:01.211+00:00",
    "submittedTime": "2026-12-30T00:00:00.000+00:00"
  }
}

Sample spend.reimbursement.updated payload

In this sample unescaped JSON payload, the details of an updated reimbursement are available.

👍

Use updatedTime as the source of truth for spend.reimbursement.updated notifications

When a reimbursement is approved, fulfillmentType is set based on how the approved reimbursement funds will be transferred to the user (ACH or PAYROLL).

After reimbursement approval, you may receive a spend.reimbursement.updated notification when fulfillmentType is intermittently set as UNSPECIFIED. In this case, the latest spend.reimbursement.updated notification by updatedTime will have the correct fulfillmentType.

The simplest way to ignore this notification is to rely on reimbursement event notifications based on updatedTime.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "spendCompanyUuid": "{S&E_company_uuid}",
    "eventType": "spend.reimbursement.updated",
    "version": "1"
  },
  "reimbursement": {
    "uuid": "{reimbursement_uuid}",
    "note": "Holiday party office expenses",
    "merchantName": "Amazon",
    "amount": 1200.0,
    "status": "AWAITING_APPROVAL",
    "fulfillmentType": "ACH",
    "budgetUuid": "{budget_uuid}",
    "companyUuid": "{company_uuid}",
    "userUuid": "\{user_uuid}",
    "occurredTime": "2026-12-30T00:00:00.000+00:00",
    "updatedTime": "2026-12-31T18:23:01.211+00:00",
    "submittedTime": "2026-12-30T00:00:00.000+00:00"
  }
}

Fields that trigger spend.reimbursement.updated notifications

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

Sample spend.reimbursement.deleted payload

In this sample unescaped JSON payload, the details of a deleted reimbursement are available. This event notification is triggered with the reimbursement status is set as DELETED. In the notification, retiredTime is set as the date and time when the reimbursement was deleted.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "spendCompanyUuid": "{S&E_company_uuid}",
    "eventType": "spend.reimbursement.deleted",
    "version": "1"
  },
  "reimbursement": {
    "uuid": "{reimbursement_uuid}",
    "note": "Holiday party office expenses",
    "merchantName": "Amazon",
    "amount": 1200.0,
    "status": "DELETED",
    "fulfillmentType": "ACH",
    "budgetUuid": "{budget_uuid}",
    "companyUuid": "{company_uuid}",
    "userUuid": "\{user_uuid}",
    "occurredTime": "2026-12-30T00:00:00.000+00:00",
    "updatedTime": "2026-12-31T20:23:01.211+00:00",
    "submittedTime": "2026-12-30T00:00:00.000+00:00",
		"retiredTime": "2026-12-31T20:23:01.211+00:00"
  }
}