How Airwallex Spend works

Understand the key features and data model of the Airwallex Spend APIs.

The Spend API provides programmatic access to expense and accounts payable data in Airwallex for custom ERP integrations. Understanding how the API is structured is important when building sync workflows, as it helps you design efficient, reliable integrations with external financial systems.

Primary use cases

The Spend API supports two main integration scenarios:

Custom ERP sync: Build automated sync workflows for accounting or ERP systems that Airwallex does not integrate with directly.
Programmatic sync status management: Mark card expenses, reimbursements, and bills as synced or paid to prevent re-processing and keep records in sync across systems.

Spend data model

The Spend API organizes data across two main areas: Expenses and Accounts Payable.

Expenses

Card expenses: Transactions made on Airwallex-issued cards. Each expense includes details such as attachments, line items, accounting field selections, and comments.
Reimbursements: Out-of-pocket expense reports submitted by employees. Reimbursement reports can be retrieved, marked as synced, and marked as paid externally when payment occurs outside Airwallex.

Accounts Payable

Vendors: External suppliers or service providers your organization pays. Each vendor is associated with one or more legal entities in your organization.
Purchase orders (POs): Formal requests to purchase goods or services from a vendor. POs include line items. You can attach accounting field selections to those line items.
Bills: Invoices received from vendors for goods or services. Bills can be created, retrieved, have their sync status updated, and be marked as paid externally.

Sync status

A core concept in the Spend API is sync status tracking. When you retrieve spend items, you can filter by sync_status to find items that have not yet been ingested into your system. After processing an item, you mark it as synced to prevent duplicate processing on subsequent API calls.

Typical sync statuses include:

NOT_SYNCED: The item has not been synced to an external system.
SYNCED: The item has been successfully synced.
SYNC_FAILED: The sync attempt failed. An error message provides details.
READY_TO_SYNC: The item is ready for sync but has not been picked up yet.

Accounting field selections

The Spend API uses accounting field selections to associate items with your chart of accounts, tax rates, and custom fields.

API version 2026-08-21 and later: Write requests use type and source_id. Earlier API versions use identifier_type, field_id, and field_value_id. See VersioningAPI.

Write (create bills and purchase orders)

Specify accounting_field_selections with:

type: The kind of accounting value. One of GENERAL_LEDGER_ACCOUNT (GL account assigned to the line item), TAX_CODE (tax code applied to the line item), or OTHER (custom accounting field; the field name is in name).
source_id: The UUID of the selected accounting value. This is the id returned when you create or list GL accounts, tax codes, or custom field values.

JSON

1{
2  "accounting_field_selections": [
3    {
4      "type": "GENERAL_LEDGER_ACCOUNT",
5      "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d"
6    },
7    {
8      "type": "TAX_CODE",
9      "source_id": "ca56f0ff-8081-4db6-8333-4e011fe9561e"
10    },
11    {
12      "type": "OTHER",
13      "source_id": "ea76f0ff-8081-4db6-8333-4e011fe95620"
14    }
15  ]
16}

Your account API version is applied automatically. Use this contract when your account is on 2026-08-21 or later. To test or migrate without changing your account version, you can override the version on a per-call basis. See VersioningAPI.

Earlier API versions

On API versions earlier than 2026-08-21, specify field_id, field_value_id, and identifier_type set to EXTERNAL_ID. These IDs correspond to the external IDs you define during custom accounting data setup. Only identifier_type: EXTERNAL_ID is supported on those versions.

JSON

1{
2  "accounting_field_selections": [
3    {
4      "field_id": "Chart of accounts",
5      "field_value_id": "601022001",
6      "identifier_type": "EXTERNAL_ID"
7    }
8  ]
9}

Read responses

Responses include type, value, and source_id. name is present only when type is OTHER.

On bills, purchase orders, reimbursement reports, and expense line items, type is one of GENERAL_LEDGER_ACCOUNT, TAX_CODE, or OTHER.
On a card expense, root-level accounting_field_selections are merchant-only (type: MERCHANT). GL accounts, tax codes, and custom fields are on line_items[].accounting_field_selections.

Webhooks

Webhooks send real-time notifications for asynchronous updates about your spend data. The event data object matches the retrieve response for the subscription API version, including source_id on populated accounting field selections. You can subscribe to events for card expenses, reimbursements, and bills. For setup instructions, see Set up Spend webhooks. For a list of available events, see Spend webhook event types.