Bills via API

List, retrieve, and update bills programmatically using the Spend API.

Beta: The Bills API is in Beta. Currently supports list, get, and update operations. Bill creation is planned for a future release.

The Bills API lets you retrieve and manage invoices received from vendors for goods or services. You can also update the sync status of your bills.

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.
Set up custom accounting data with external IDs if you plan to update bills with accounting field selections.

List bills

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

Send the request with optional filters:
Shell
```
1curl -G \
2  'https://api-demo.airwallex.com/api/v1/spend/bills' \
3  --data-urlencode 'sync_status=NOT_SYNCED' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
```

The response returns a list of bills:

JSON

1{
2  "items": [
3    {
4      "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
5      "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
6      "billing_amount": "4500.00",
7      "billing_currency": "USD",
8      "status": "AWAITING_PAYMENT",
9      "sync_status": "NOT_SYNCED",
10      "due_date": "2026-03-01"
11    }
12  ],
13  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
14  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
15}

Key query parameters include:

Parameter	Description
`status`	Filter by bill status. Possible values are `DRAFT`, `AWAITING_APPROVAL`, `AWAITING_PAYMENT`, `PAYMENT_IN_PROGRESS`, `PAID`, `REJECTED`, `SCHEDULED`.
`sync_status`	Filter by sync status (`NOT_SYNCED`, `SYNCED`, `SYNC_FAILED`).
`from_created_at`	Filter bills created on or after this timestamp (ISO 8601).
`to_created_at`	Filter bills created on or before this timestamp (ISO 8601).
`legal_entity_id`	Filter bills by legal entity ID.
`purchase_order_id`	Filter bills by associated purchase order ID.
`page`	A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call.

Get bill details

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

Use the id from the list response:

Shell

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

The response includes complete bill details:

JSON

1{
2  "approvers": [
3    "[email protected]",
4    "[email protected]"
5  ],
6  "attachments": [
7    {
8      "content_type": "image/jpeg",
9      "created_at": "2025-02-02T00:00:00Z",
10      "file_name": "flight_receipt.jpg",
11      "file_url": "https://www.airwallex.com/flight_receipt.jpg",
12      "id": "985461d5-016f-4e1f-a387-5f1380b42d92"
13    }
14  ],
15  "bill_payments": [
16    {
17      "amount": "500.00",
18      "card_transaction": {
19        "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
20        "card_funding_type": "CREDIT",
21        "card_id": "985461d5-016f-4e1f-a387-5f1380b42d92",
22        "card_transaction_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
23        "source_amount": "500.00",
24        "source_currency": "USD",
25        "transacted_at": "2025-01-02T00:00:00Z"
26      },
27      "created_at": "2025-01-02T00:00:00Z",
28      "currency": "USD",
29      "id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
30      "type": "CARD_TRANSACTION"
31    },
32    {
33      "amount": "4000.00",
34      "created_at": "2025-01-01T00:00:00Z",
35      "currency": "USD",
36      "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
37      "transfer": {
38        "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
39        "multi_bill": false,
40        "source_amount": "400.00",
41        "source_currency": "USD",
42        "status": "PAID",
43        "transfer_date": "2025-01-01",
44        "transfer_id": "985461d5-016f-4e1f-a387-5f1380b42d92"
45      },
46      "type": "TRANSFER"
47    }
48  ],
49  "billing_amount": "4500.0",
50  "billing_currency": "USD",
51  "created_at": "2025-01-01T00:00:00Z",
52  "description": "This is a description of the bill.",
53  "due_date": "2025-01-10",
54  "external_id": "BILL-EXT-001",
55  "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
56  "invoice_number": "INV-0001",
57  "issued_date": "2025-01-10",
58  "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
59  "line_items": [
60    {
61      "accounting_field_selections": [
62        {
63          "name": "Cost Center",
64          "type": "OTHER",
65          "value": "Office Expense",
66          "external_id": "1036f6f7-87e4-4508-b865-f670b1926022",
67          "value_label": "Office Expense"
68        }
69      ],
70      "description": "Office supplies",
71      "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
72      "purchase_order_line_item_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
73      "quantity": "5",
74      "tax_amount": "0.0",
75      "total_amount": "4500.0",
76      "unit_price": "500.0"
77    }
78  ],
79  "purchase_order_id": "ca56f0ff-8081-4db6-8333-4e011fe9561e",
80  "status": "AWAITING_PAYMENT",
81  "sync_status": "NOT_SYNCED",
82  "tax_status": "TAX_EXCLUSIVE",
83  "updated_at": "2025-02-02T00:00:00Z",
84  "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d"
85}

Update a bill

To update a bill with a new sync status, call the Update bill sync status API endpoint.

Update sync status

After you persist a bill to your system, mark it as synced:

Send the update request with the sync status:

Shell

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

The response confirms the updated status:

JSON

1{
2  "id": "uuid",
3  "sync_status": "SYNCED"
4}

If an error occurs:

Send the update request with the sync status:

Shell

1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/spend/bills/{{BILL_ID}}/sync' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "sync_error_message": "Failed to sync bill: found a mismatch between the bill payment and bill currency.",
7    "sync_status": "SYNC_FAILED"
8  }'

The response confirms the updated status:

JSON

1{
2  "id": "uuid",
3  "sync_error_message": "Failed to sync bill: found a mismatch between the bill payment and bill currency.",
4  "sync_status": "SYNC_FAILED"
5}

Next steps

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

Was this page helpful?