Tax rates via API

The tax codes API lets you manage tax rates in Airwallex Spend. Sync tax codes from your ERP or accounting system so employees and automated workflows can apply the correct tax rates when coding expenses, bills, and other Spend items.

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 for an overview of accounting data concepts, including external IDs, legal entity scope, and status.

Sync tax codes from your ERP

A typical sync workflow looks like this:

1. List existing tax codes in Airwallex, filtering by external_id or status where needed.
2. Create tax codes that exist in your ERP but not yet in Airwallex. Match on external_id before creating. A duplicate external_id or tax rate name (value) causes the create request to fail.
3. Update tax codes whose names, rates, or other attributes have changed in your ERP.
4. Set status to ARCHIVED on update for tax codes that are no longer active in your ERP.

Use external_id to reference a value from your ERP on create and update so you can match records across systems.

Create a tax code

To create a tax code, call the Create tax code API endpoint. Each tax code must have a unique tax rate name (value) within your organization. When you provide an external_id, it must also be unique: this is the identifier you use as field_value_id when coding transactions via the Spend API.

1. Send the create request with the rate as rate_percent and your ERP identifier as external_id:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/accounting/tax_codes/create' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "request_id": "985461d5-016f-4e1f-a387-5f1380b42d92",
   7    "value": "GST",
   8    "rate_percent": "9.0000",
   9    "value_label": "9% GST",
   10    "external_id": "GST-9"
   11  }'

   The rate_percent field is required and must be a percentage between 0 and 100, with up to 4 decimal places. Omit legal_entity_ids when the tax code applies to all legal entities in your organization.

2. The response returns the created tax code with its unique Airwallex id:

   JSON

   1{
   2  "id": "ca56f0ff-8081-4db6-8333-4e011fe9561e",
   3  "value": "GST",
   4  "rate_percent": "9.0000",
   5  "value_label": "9% GST",
   6  "external_id": "GST-9",
   7  "status": "ACTIVE",
   8  "created_at": "2026-06-15T00:00:00Z",
   9  "updated_at": "2026-06-15T00:00:00Z"
   10}

List tax codes

To retrieve tax codes, call the List tax codes API endpoint.

1. Send the request with optional filters:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/accounting/tax_codes' \
   3  --data-urlencode 'status=ACTIVE' \
   4  --data-urlencode 'external_id=GST-9' \
   5  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

2. The response returns a paginated list of tax codes:

   JSON

   1{
   2  "items": [
   3    {
   4      "id": "ca56f0ff-8081-4db6-8333-4e011fe9561e",
   5      "value": "GST",
   6      "rate_percent": "9.0000",
   7      "value_label": "9% GST",
   8      "external_id": "GST-9",
   9      "status": "ACTIVE",
   10      "created_at": "2026-06-15T00:00:00Z",
   11      "updated_at": "2026-06-15T00:00:00Z"
   12    }
   13  ],
   14  "page_after": "string",
   15  "page_before": "string"
   16}

Key query parameters include:

Get tax code details

To retrieve a specific tax code, call the Get tax code API endpoint.

1. Use the id from the list or create response:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/accounting/tax_codes/{{TAX_CODE_ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Update a tax code

To update an existing tax code, call the Update tax code API endpoint.

1. Send the update request with the fields you want to change:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/accounting/tax_codes/{{TAX_CODE_ID}}/update' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "value": "GST",
   7    "rate_percent": "9.0000",
   8    "value_label": "9% GST",
   9    "external_id": "GST-9",
   10    "legal_entity_ids": [
   11      "le_U3jlHqQRNHWn2zAKeeT8sx"
   12    ],
   13    "status": "ARCHIVED"
   14  }'

2. The response returns the updated tax code.

Use tax rates in Spend APIs

When coding line items on bills, purchase orders, expenses, or other Spend resources, reference a tax rate in accounting_field_selections using:

• field_id: Tax rates
• field_value_id: The tax code external_id (for example, GST-9)
• identifier_type: EXTERNAL_ID

1{
2  "accounting_field_selections": [
3    {
4      "field_id": "Tax rates",
5      "field_value_id": "GST-9",
6      "identifier_type": "EXTERNAL_ID"
7    }
8  ]
9}

Next steps

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

• GL accounts via API
• Custom fields via API
• Set up custom accounting data
• Bills via API