Card expenses via API

The Card Expenses API lets you retrieve approved card expenses from Airwallex and mark them as synced after ingesting them into your ERP or accounting system. This prevents re-processing and keeps your records in sync.

Before you begin

• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You can create scoped API keys in Settings > Developer > API keys in the Airwallex web app. Spend resources require Organization-level permissions.
• Familiarize yourself with the Spend data model.

List card expenses

To retrieve a list of card expenses, call the List card expenses API endpoint. You can use query parameters to filter results by status, sync status, and pagination.

1. Send the request with your desired filters:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/spend/expenses' \
   3  --data-urlencode 'status=APPROVED' \
   4  --data-urlencode 'sync_status=NOT_SYNCED' \
   5  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

2. Review the response:

   JSON

   1{
   2  "items": [
   3    {
   4      "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
   5      "approvers": [
   6      ],
   7      "billing_amount": "1234.56",
   8      "billing_currency": "USD",
   9      "card_id": "bdfd278d-14f8-4d12-a04f-a7a1871babd2",
   10      "created_at": "2025-01-01T00:00:00Z",
   11      "description": "Business lunch with client",
   12      "id": "f865c064-57bb-4ca0-9793-54011e00cb53",
   13      "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   14      "merchant": "Restaurant ABC",
   15      "settled_at": "2025-03-03T00:00:00Z",
   16      "status": "APPROVED",
   17      "sync_status": "NOT_SYNCED",
   18      "card_transaction": {
   19        "status": "CLEARED",
   20        "amount": "1234.56",
   21        "currency": "USD"
   22      },
   23      "updated_at": "2025-02-02T00:00:00Z"
   24    },
   25    {
   26      "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
   27      "approvers": [
   28        "[email protected]",
   29        "[email protected]"
   30      ],
   31      "billing_amount": "567.89",
   32      "billing_currency": "USD",
   33      "card_id": "7d2faf05-a771-4964-92ed-0b65ef3ea04b",
   34      "created_at": "2025-01-01T01:00:00Z",
   35      "description": "Team dinner",
   36      "id": "313c9a4f-2e7b-40f2-9b89-ebb08bc7d856",
   37      "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   38      "merchant": "Restaurant XYZ",
   39      "settled_at": "2025-03-03T01:00:00Z",
   40      "status": "APPROVED",
   41      "sync_status": "NOT_SYNCED",
   42      "card_transaction": {
   43        "status": "CLEARED",
   44        "amount": "567.89",
   45        "currency": "USD"
   46      },
   47      "updated_at": "2025-02-02T01:00:00Z"
   48    }
   49  ],
   50  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
   51  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
   52}

Key query parameters include:

Get card expense details

To retrieve the full details of a specific expense, including attachments, line items, accounting fields, and comments, call the Get card expense API endpoint.

1. Use the id from the list response:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/spend/expenses/{{ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

2. The response includes complete expense details:

   JSON

   1{
   2  "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
   3  "accounting_field_selections": [
   4    {
   5      "name": "Cost Center",
   6      "type": "OTHER",
   7      "value": "Office Expense",
   8      "external_id": "1036f6f7-87e4-4508-b865-f670b1926022",
   9      "value_label": "Office Expense"
   10    }
   11  ],
   12  "approvers": [
   13    "[email protected]",
   14    "[email protected]"
   15  ],
   16  "attachments": [
   17    {
   18      "content_type": "image/jpeg",
   19      "created_at": "2025-02-02T00:00:00Z",
   20      "file_name": "receipt.jpg",
   21      "file_url": "https://www.airwallex.com/receipt.jpg",
   22      "id": "0fd62109-cfc0-4c94-86a5-d01c42506b76"
   23    }
   24  ],
   25  "billing_amount": "100.0",
   26  "billing_currency": "USD",
   27  "card_id": "93eed14b-104d-4f40-ae1d-3633c6538276",
   28  "comments": [
   29    {
   30      "content": "Please review this expense.",
   31      "created_at": "2025-02-02T08:00:00Z",
   32      "created_by": "[email protected]"
   33    }
   34  ],
   35  "created_at": "2025-01-01T00:00:00Z",
   36  "description": "This is a description of the expense.",
   37  "id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   38  "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   39  "line_items": [
   40    {
   41      "accounting_field_selections": [
   42        {
   43          "name": "Cost Center",
   44          "type": "OTHER",
   45          "value": "Office Expense",
   46          "external_id": "a7e44855-e7f3-47ce-be50-182b666d543c",
   47          "value_label": "Office Expense"
   48        }
   49      ],
   50      "description": "Office supplies purchase",
   51      "id": "a12fca5e-4aeb-4adb-85b0-428b4f078aba",
   52      "transaction_amount": "100.00"
   53    }
   54  ],
   55  "merchant": "Airwallex",
   56  "settled_at": "2025-03-03T00:00:00Z",
   57  "status": "APPROVED",
   58  "sync_status": "SYNCED",
   59  "card_transaction": {
   60    "status": "AUTHORIZED",
   61    "amount": "100.0",
   62    "currency": "USD"
   63  },
   64  "updated_at": "2025-02-02T00:00:00Z"
   65}

Use the accounting_field_selections, attachments, and line_items data to map the expense to the correct accounts in your ERP.

Update sync status

After you persist an expense to your system, mark it as synced to prevent re-processing.

1. Call the Sync card expense status API endpoint:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/spend/expenses/{{ID}}/sync' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "sync_status": "SYNCED"
   7  }'

2. The response confirms the updated status:

   JSON

   1{
   2  "id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   3  "sync_status": "SYNCED"
   4}

Next steps

Now that you can manage card expenses via the API, explore these related guides:

• Reimbursements via API
• Set up Spend webhooks
• Error codes