Bills via API

Create, list, retrieve, update, and mark bills as paid programmatically using the Spend API.

Beta: The Bills API is in Beta. You can create, list, retrieve, update sync status, and mark bills as paid externally.

The Bills API lets you create and manage invoices received from vendors for goods or services. You can also update the sync status of your bills and mark them as paid outside Airwallex.

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.

Create a bill

To create a new bill, call the Create bill API endpoint.

Send the create request with all required fields:
Shell
```
1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/spend/bills/create' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "billing_currency": "USD",
7    "due_date": "2025-01-10",
8    "external_id": "BILL-EXT-001",
9    "invoice_number": "INV-0001",
10    "issued_date": "2025-01-10",
11    "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
12    "line_items": [
13      {
14        "quantity": "1",
15        "unit_price": "500.0"
16      }
17    ],
18    "request_id": "985461d5-016f-4e1f-a387-5f1380b42d92",
19    "sync_status": "SYNCED",
20    "tax_status": "TAX_EXCLUSIVE",
21    "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d"
22  }'
```

The response returns the created bill with its unique ID:

JSON

1{
2  "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
3  "external_id": "BILL-EXT-001",
4  "invoice_number": "INV-0001",
5  "billing_currency": "USD",
6  "billing_amount": "551.0",
7  "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
8  "status": "AWAITING_PAYMENT",
9  "sync_status": "SYNCED",
10  "created_at": "2025-01-01T00:00:00Z"
11}

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}

Mark a bill as paid externally

When a bill is paid outside Airwallex (for example, from your ERP or an external bank account), call Mark bill as paid API so bill status is updated in Airwallex.

Send the mark-as-paid request with the bill ID in the path:

Shell

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

The response returns the updated bill details with status set to PAID.

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?