Spend

Subscribe to webhook events for bill, card expense, and reimbursement report status changes.

The following webhook events are available for your Spend integration.

Card expense webhooks

Web app Label	Event Type	Description
Expenses -> Expense draft	spend.expense.draft	A card expense has been created.
Expenses -> Expense awaiting approval	spend.expense.awaiting_approval	A card expense has been submitted for approval, or has been approved but requires additional approvals.
Expenses -> Expense updated	spend.expense.updated	A card expense or its underlying card transaction has been updated.
Expenses -> Expense rejected	spend.expense.rejected	A card expense has been rejected.
Expenses -> Expense approved	spend.expense.approved	A card expense has been fully approved.
Expenses -> Expense archived	spend.expense.archived	A card expense has been archived.
Expenses -> Expense deleted	spend.expense.deleted	A card expense has been deleted. This occurs when a bill is paid using a card transaction that already has an associated card expense.

For more details on card expense operations, see Card expenses via API.

Reimbursement report webhooks

Web app Label	Event Type	Description
Reimbursement Reports -> Report draft	spend.reimbursement_report.draft	A reimbursement report has been created.
Reimbursement Reports -> Report awaiting approval	spend.reimbursement_report.awaiting_approval	A reimbursement report has been submitted for approval.
Reimbursement Reports -> Report awaiting payment	spend.reimbursement_report.awaiting_payment	A reimbursement report has been approved and is awaiting payment.
Reimbursement Reports -> Report rejected	spend.reimbursement_report.rejected	A reimbursement report has been rejected.
Reimbursement Reports -> Report payment in progress	spend.reimbursement_report.payment_in_progress	Payment for a reimbursement report is being processed.
Reimbursement Reports -> Report paid	spend.reimbursement_report.paid	A reimbursement report has been paid through Airwallex.
Reimbursement Reports -> Report marked as paid	spend.reimbursement_report.mark_as_paid	A reimbursement report has been marked as paid externally, outside Airwallex.
Reimbursement Reports -> Report deleted	spend.reimbursement_report.deleted	A reimbursement report has been deleted.
Reimbursement Reports -> Report updated	spend.reimbursement_report.updated	A reimbursement report has been updated.

For more details on reimbursement operations, see Reimbursements via API.

Bill webhooks

Web app Label	Event Type	Description
Bills -> Bill awaiting approval	spend.bill.awaiting_approval	A bill is submitted and is awaiting approval.
Bills -> Bill updated	spend.bill.updated	A bill has been edited.
Bills -> Bill awaiting payment	spend.bill.awaiting_payment	A bill is approved and is awaiting payment.
Bills -> Bill payment in progress	spend.bill.payment_in_progress	A bill payment is in progress.
Bills -> Bill paid	spend.bill.paid	A bill is fully paid.
Bills -> Bill rejected	spend.bill.rejected	A bill's approval is rejected.
Bills -> Bill scheduled	spend.bill.scheduled	A bill is scheduled for payment.
Bills -> Bill deleted	spend.bill.deleted	A bill is deleted.

For more details on bill operations, see Bills via API.

Payload examples

Examples of different Spend event data objects are displayed below. The data object matches the retrieve response for the subscription API version. See Accounting field selections.

Card expense approved

When a card expense is fully approved, you receive a spend.expense.approved event with the following payload:

JSON

1{
2  "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3  "name": "spend.expense.approved",
4  "org_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "account_id": "acct_--hXbQInMnenHjfxoO0mTg",
7    "accounting_field_selections": [
8      {
9        "source_id": "d8e2f0ff-8081-4db6-8333-4e011fe9561d",
10        "type": "MERCHANT",
11        "value": "Coffee Shop",
12        "value_label": "Coffee Shop"
13      }
14    ],
15    "approvers": [],
16    "attachments": [],
17    "billing_amount": "50.00",
18    "billing_currency": "AUD",
19    "card_id": "2a6c461c-efdb-465f-8b0a-c2e7040a878e",
20    "comments": [],
21    "created_at": "2025-09-08T10:00:00.000000Z",
22    "description": null,
23    "id": "47725807-2085-443e-9c2c-ce9ca9627247",
24    "legal_entity_id": "le_8CqerfacM_aSwB3G3SnAOw",
25    "line_items": [
26      {
27        "accounting_field_selections": [],
28        "description": null,
29        "id": "09a60121-a387-39d4-b46e-f491b6efa6a0",
30        "transaction_amount": "50.00"
31      }
32    ],
33    "merchant": "Coffee Shop",
34    "settled_at": "2025-09-08T10:02:00.000000Z",
35    "status": "APPROVED",
36    "sync_status": "NOT_SYNCED",
37    "card_transaction": {
38      "status": "CLEARED",
39      "amount": "50.00",
40      "currency": "AUD"
41    },
42    "updated_at": "2025-09-08T10:02:00.000000Z"
43  },
44  "created_at": "2026-02-06T10:10:29+0000",
45  "version": "2026-08-21"
46}

Key fields in the expense data object:

Field	Description
`id`	Unique identifier of the card expense.
`account_id`	The Airwallex account ID.
`legal_entity_id`	The legal entity associated with this expense.
`card_id`	The card used for this transaction.
`billing_amount` / `billing_currency`	The amount and currency billed to the card.
`card_transaction`	Nested object containing the card transaction details: `status` (for example, `CLEARED`), `amount`, and `currency`.
`merchant`	The merchant name.
`status`	The expense approval status (for example, `APPROVED`).
`sync_status`	Whether the expense has been synced to an external system (`NOT_SYNCED`, `SYNCED`).
`line_items`	Array of line items. Line-item `accounting_field_selections` use `GENERAL_LEDGER_ACCOUNT`, `TAX_CODE`, or `OTHER`.
`accounting_field_selections`	Root-level selections on a card expense are merchant-only (`type: MERCHANT`).
`attachments`	Array of file attachments associated with the expense.
`approvers`	Array of users who approved the expense.
`comments`	Array of comments on the expense.
`settled_at`	Timestamp when the card transaction was settled.

Reimbursement report awaiting payment

When a reimbursement report is approved and awaiting payment, you receive a spend.reimbursement_report.awaiting_payment event with the following payload:

JSON

1{
2  "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3  "name": "spend.reimbursement_report.awaiting_payment",
4  "org_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "accounting_field_selections": [],
7    "approvers": [
8      "[email protected]",
9      "[email protected]"
10    ],
11    "beneficiary_id": "a26d26ea-8b2c-4b5f-a7a6-24edcdf2cfa5",
12    "billing_currency": "AUD",
13    "comments": [],
14    "created_at": "2025-09-08T10:00:00.000000Z",
15    "created_by": "[email protected]",
16    "id": "58d716bc-c03e-4c38-80c1-b030c602c8ae",
17    "legal_entity_id": "e63bad9f-28e5-4ffa-a366-1fe20b8d5647",
18    "name": "Q3 Marketing Campaign",
19    "status": "AWAITING_PAYMENT",
20    "sync_status": "NOT_SYNCED",
21    "updated_at": "2025-09-08T10:05:20.000000Z"
22  },
23  "created_at": "2026-02-06T10:15:07+0000",
24  "version": "2026-08-21"
25}

Key fields in the reimbursement report data object:

Field	Description
`id`	Unique identifier of the reimbursement report.
`name`	The report name (for example, `Q3 Marketing Campaign`).
`legal_entity_id`	The legal entity associated with this report.
`beneficiary_id`	The beneficiary who receives the reimbursement payment.
`billing_currency`	The currency for the report.
`status`	The report status (for example, `AWAITING_PAYMENT`).
`sync_status`	Whether the report has been synced to an external system (`NOT_SYNCED`, `SYNCED`).
`accounting_field_selections`	Accounting coding on the report. `type` is one of `GENERAL_LEDGER_ACCOUNT`, `TAX_CODE`, or `OTHER`.
`approvers`	Array of email addresses of users who approved the report.
`created_by`	Email address of the user who created the report.

Bill awaiting approval

When a bill is submitted and awaiting approval, you receive a spend.bill.awaiting_approval event with the following payload:

JSON

1{
2  "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3  "name": "spend.bill.awaiting_approval",
4  "org_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
7    "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
8    "invoice_number": "INV-0001",
9    "billing_amount": "551.00",
10    "billing_currency": "USD",
11    "status": "AWAITING_APPROVAL",
12    "sync_status": "SYNCED",
13    "sync_error_message": null,
14    "tax_status": "TAX_EXCLUSIVE",
15    "description": "Office supplies for Q1 2025.",
16    "approvers": [
17      "[email protected]",
18      "[email protected]"
19    ],
20    "issued_date": "2025-01-01",
21    "due_date": "2025-01-31",
22    "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
23    "purchase_order_id": "1541e085-16e9-45e2-a236-5dd2308ff766",
24    "bill_payments": [],
25    "external_id": "BILL-EXT-001",
26    "attachments": [
27      {
28        "id": "0fd62109-cfc0-4c94-86a5-d01c42506b76",
29        "content_type": "application/pdf",
30        "file_name": "invoice.pdf",
31        "file_url": "https://files.airwallex.com/invoice.pdf",
32        "created_at": "2025-01-01T00:00:00Z"
33      }
34    ],
35    "line_items": [
36      {
37        "id": "a12fca5e-4aeb-4adb-85b0-428b4f078aba",
38        "unit_price": "55.10",
39        "quantity": "10",
40        "description": "Printer paper (A4, 80gsm)",
41        "total_amount": "551.00",
42        "tax_amount": "51.00",
43        "accounting_field_selections": [
44          {
45            "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
46            "type": "GENERAL_LEDGER_ACCOUNT",
47            "name": null,
48            "external_id": "c9fcfdee-f943-45c9-abaa-45df1601ae04",
49            "value": "Office Supplies",
50            "value_label": "Office Supplies"
51          }
52        ],
53        "purchase_order_line_item_id": "1541e085-16e9-45e2-a236-5dd2308ff766"
54      }
55    ],
56    "created_at": "2025-01-01T00:00:00Z",
57    "updated_at": "2025-02-02T00:00:00Z"
58  },
59  "created_at": "2026-02-06T10:20:15+0000",
60  "version": "2026-08-21"
61}

All bill lifecycle events use the same data object shape. Only the event name and data.status differ across events such as spend.bill.awaiting_payment, spend.bill.payment_in_progress, spend.bill.rejected, spend.bill.scheduled, and spend.bill.deleted.

Key fields in the bill data object:

Field	Description
`id`	Unique identifier of the bill.
`legal_entity_id`	The legal entity associated with this bill.
`invoice_number`	Invoice number associated with the bill.
`billing_amount` / `billing_currency`	Total amount and currency of the bill.
`status`	Bill status (for example, `AWAITING_APPROVAL`, `AWAITING_PAYMENT`, `PAYMENT_IN_PROGRESS`, `PAID`, `REJECTED`, or `SCHEDULED`, and `DELETED` on the deleted event). Handle unknown values gracefully.
`sync_status` / `sync_error_message`	Sync status with external accounting systems (`NOT_SYNCED`, `SYNCED`, `SYNC_FAILED`) and any failure message.
`tax_status`	Tax treatment of the bill (`TAX_EXCLUSIVE`, `TAX_INCLUSIVE`, `UNSPECIFIED`).
`vendor_id` / `purchase_order_id`	Vendor and purchase order associated with the bill.
`bill_payments`	Payments applied to the bill. Empty until payments exist.
`line_items`	Line items on the bill. Line-item `accounting_field_selections` use `GENERAL_LEDGER_ACCOUNT`, `TAX_CODE`, or `OTHER`.
`attachments`	File attachments associated with the bill. `file_url` requires authentication.
`external_id`	External identifier for this bill in your system.
`approvers`	Email addresses of users who can approve the bill.

The data object matches the Get billAPI response body.

Bill paid

When a bill is fully paid, you receive a spend.bill.paid event with the following payload. A paid bill can include a mix of payment types. The example below shows a TRANSFER payment alongside a CARD_TRANSACTION payment.

JSON

1{
2  "id": "3b407a08-a3a5-4186-b99a-54bda1c98523",
3  "name": "spend.bill.paid",
4  "org_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
7    "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
8    "invoice_number": "INV-0001",
9    "billing_amount": "551.00",
10    "billing_currency": "USD",
11    "status": "PAID",
12    "sync_status": "SYNCED",
13    "sync_error_message": null,
14    "tax_status": "TAX_EXCLUSIVE",
15    "description": "Office supplies for Q1 2025.",
16    "approvers": [
17      "[email protected]",
18      "[email protected]"
19    ],
20    "issued_date": "2025-01-01",
21    "due_date": "2025-01-31",
22    "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
23    "purchase_order_id": "1541e085-16e9-45e2-a236-5dd2308ff766",
24    "bill_payments": [
25      {
26        "id": "b1a1f0ff-8081-4db6-8333-4e011fe95611",
27        "type": "TRANSFER",
28        "amount": "551.00",
29        "currency": "USD",
30        "transfer": {
31          "transfer_id": "c2b2f0ff-8081-4db6-8333-4e011fe95622",
32          "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
33          "multi_bill": false,
34          "source_amount": "551.00",
35          "source_currency": "USD",
36          "transfer_date": "2025-01-15"
37        },
38        "card_transaction": null,
39        "created_at": "2025-01-15T00:00:00Z"
40      },
41      {
42        "id": "d3c3f0ff-8081-4db6-8333-4e011fe95633",
43        "type": "CARD_TRANSACTION",
44        "amount": "300.00",
45        "currency": "USD",
46        "transfer": null,
47        "card_transaction": {
48          "card_transaction_id": "e4d4f0ff-8081-4db6-8333-4e011fe95644",
49          "card_id": "f5e5f0ff-8081-4db6-8333-4e011fe95655",
50          "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
51          "card_funding_type": "CREDIT",
52          "source_amount": "300.00",
53          "source_currency": "USD",
54          "transacted_at": "2025-01-15T00:00:00Z"
55        },
56        "created_at": "2025-01-15T00:00:00Z"
57      }
58    ],
59    "external_id": "BILL-EXT-001",
60    "attachments": [
61      {
62        "id": "0fd62109-cfc0-4c94-86a5-d01c42506b76",
63        "content_type": "application/pdf",
64        "file_name": "invoice.pdf",
65        "file_url": "https://files.airwallex.com/invoice.pdf",
66        "created_at": "2025-01-01T00:00:00Z"
67      }
68    ],
69    "line_items": [
70      {
71        "id": "a12fca5e-4aeb-4adb-85b0-428b4f078aba",
72        "unit_price": "55.10",
73        "quantity": "10",
74        "description": "Printer paper (A4, 80gsm)",
75        "total_amount": "551.00",
76        "tax_amount": "51.00",
77        "accounting_field_selections": [
78          {
79            "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
80            "type": "GENERAL_LEDGER_ACCOUNT",
81            "name": null,
82            "external_id": "c9fcfdee-f943-45c9-abaa-45df1601ae04",
83            "value": "Office Supplies",
84            "value_label": "Office Supplies"
85          }
86        ],
87        "purchase_order_line_item_id": "1541e085-16e9-45e2-a236-5dd2308ff766"
88      }
89    ],
90    "created_at": "2025-01-01T00:00:00Z",
91    "updated_at": "2025-02-02T00:00:00Z"
92  },
93  "created_at": "2026-02-06T10:25:42+0000",
94  "version": "2026-08-21"
95}

Each entry in bill_payments is discriminated by type:

TRANSFER — transfer is populated and card_transaction is null.
CARD_TRANSACTION — card_transaction is populated and transfer is null.
EXTERNAL — both transfer and card_transaction are null (payment recorded outside Airwallex).

Was this page helpful?