Reimbursements via API

The Reimbursements API lets you retrieve employee reimbursement reports from Airwallex, mark them as synced after ingesting them into your ERP, and mark them as paid when payment occurs outside Airwallex. This follows the same pattern as the Card Expenses API, with an additional endpoint for external payment tracking.

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 reimbursements

To retrieve a list of reimbursement reports, call the List reimbursement reports API endpoint. You can filter by status and sync status.

1. Send the request with your desired filters:

   Shell

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

2. Review the response:

   JSON

   1 {
   2   "items": [
   3     {
   4       "approvers": [],
   5       "beneficiary_id": null,
   6       "billing_currency": "USD",
   7       "created_at": "2025-01-01T00:00:00Z",
   8       "created_by": "[email protected]",
   9       "id": "5ff441f8-1721-4148-b73a-bf690733f0f4",
   10       "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   11       "name": "Reimbursement report 2025-11-24",
   12       "status": "AWAITING_PAYMENT",
   13       "sync_status": "NOT_SYNCED",
   14       "updated_at": "2025-02-02T00:00:00Z"
   15     }
   16   ],
   17   "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
   18   "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
   19 }

Key query parameters include:

Get reimbursement details

To retrieve the summary of a specific reimbursement report, including accounting fields and comments, call the Get reimbursement report API endpoint. To retrieve the individual reimbursement claims within the report, use the List reimbursements for a report endpoint.

1. Use the id from the list response:

   Shell

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

2. The response includes the report summary:

   JSON

   1{
   2  "accounting_field_selections": [
   3    {
   4      "name": "Cost Center",
   5      "type": "OTHER",
   6      "value": "Office Expense",
   7      "external_id": "1036f6f7-87e4-4508-b865-f670b1926022",
   8      "value_label": "Office Expense"
   9    }
   10  ],
   11  "approvers": [
   12    "[email protected]",
   13    "[email protected]"
   14  ],
   15  "beneficiary_id": "55458be4-271c-488d-a12b-5e0709f4a0c0",
   16  "billing_currency": "USD",
   17  "comments": [
   18    {
   19      "content": "This is a report comment",
   20      "created_at": "2023-10-01T12:00:00Z",
   21      "created_by": "[email protected]"
   22    },
   23    {
   24      "content": "This is another report comment",
   25      "created_at": "2023-10-01T13:00:00Z",
   26      "created_by": "[email protected]"
   27    }
   28  ],
   29  "created_at": "2025-01-01T00:00:00Z",
   30  "created_by": "[email protected]",
   31  "id": "126ff4d1-737c-4a62-a862-f76b3f103357",
   32  "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   33  "name": "Example Reimbursement Report",
   34  "status": "PAID",
   35  "sync_status": "NOT_SYNCED",
   36  "updated_at": "2025-02-02T00:00:00Z"
   37}

List reimbursements for a report

To retrieve the individual reimbursement claims within a report, call the List reimbursements API endpoint.

1. Use the report id from the list or get response:

   Shell

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

2. The response returns a paginated list of reimbursements:

   JSON

   1{
   2  "items": [
   3    {
   4      "accounting_field_selections": [],
   5      "attachments": [
   6        {
   7          "content_type": "application/pdf",
   8          "created_at": "2025-11-27T10:00:00Z",
   9          "file_name": "receipt.pdf",
   10          "file_url": "https://example.com/receipt.pdf",
   11          "id": "1540326e-f828-4c16-9ef0-2e5045618637"
   12        }
   13      ],
   14      "billing_amount": "551.00",
   15      "comments": [],
   16      "created_at": "2025-11-10T12:00:00Z",
   17      "description": "Hotel stay for business trip",
   18      "id": "1ae9f098-c845-4c31-a7b2-2fc65eb3bbbb",
   19      "line_items": [
   20        {
   21          "accounting_field_selections": [
   22            {
   23              "name": "Department",
   24              "type": "OTHER",
   25              "value": "123456",
   26              "external_id": null,
   27              "value_label": "Communications"
   28            }
   29          ],
   30          "id": "1706880f-4257-4f6e-a714-ced27172fdf6",
   31          "tax_amount": "0.00",
   32          "transaction_amount": "551.00"
   33        }
   34      ],
   35      "merchant_name": "A Grand Hotel",
   36      "transaction_amount": "551.00",
   37      "transaction_currency": "USD",
   38      "transaction_date": "2024-12-15T00:00:00Z",
   39      "updated_at": "2025-11-10T00:00:00Z"
   40    }
   41  ],
   42  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
   43  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
   44}

Get a single reimbursement

To retrieve the full details of a specific reimbursement within a report, call the Get reimbursement API endpoint.

1. Use the reimbursement id from the list response:

   Shell

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

Mark as synced

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

1. Call the Sync reimbursement report status API endpoint:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/spend/reimbursement_reports/{{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 sync status:

   JSON

   1{
   2  "id": "126ff4d1-737c-4a62-a862-f76b3f103357",
   3  "sync_status": "SYNCED"
   4}

Mark as paid externally

When an employee is reimbursed through a payment system outside Airwallex, mark the reimbursement as paid to keep Airwallex records accurate.

1. Call the Mark reimbursement report as paid API endpoint:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/spend/reimbursement_reports/{{ID}}/mark_as_paid' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{}'

2. The response returns the full reimbursement report summary with status set to MARKED_AS_PAID:

   JSON

   1{
   2  "accounting_field_selections": [],
   3  "approvers": [
   4    "[email protected]"
   5  ],
   6  "beneficiary_id": "55458be4-271c-488d-a12b-5e0709f4a0c0",
   7  "billing_currency": "USD",
   8  "comments": [],
   9  "created_at": "2025-01-01T00:00:00Z",
   10  "created_by": "[email protected]",
   11  "id": "126ff4d1-737c-4a62-a862-f76b3f103357",
   12  "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
   13  "name": "Example Reimbursement Report",
   14  "status": "MARKED_AS_PAID",
   15  "sync_status": "NOT_SYNCED",
   16  "updated_at": "2025-02-02T00:00:00Z"
   17}

Next steps

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

• Card expenses via API
• Set up Spend webhooks
• Error codes