Purchase orders via APIBeta

The Purchase Orders (PO) API lets you create and manage formal purchase requests to vendors. Each purchase order requires line items. You can attach accounting field selections to map those line items to your chart of accounts, tax rates, and custom fields.

Before you begin

• Obtain your access tokenAPI 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 if you plan to code line items with accounting field selections. See Accounting field selections.
• Create or identify a vendor to associate with the purchase order.

Prepare line items with accounting field selections

Each purchase order requires a line_items array. Each line item can contain accounting_field_selections that map the item to your chart of accounts, tax rates, and custom fields.

The structure for a line item with accounting field selections:

1{
2  "line_items": [
3    {
4      "description": "Office furniture - standing desks",
5      "quantity": 10,
6      "unit_price": 450.00,
7      "accounting_field_selections": [
8        {
9          "type": "GENERAL_LEDGER_ACCOUNT",
10          "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d"
11        },
12        {
13          "type": "TAX_CODE",
14          "source_id": "ca56f0ff-8081-4db6-8333-4e011fe9561e"
15        },
16        {
17          "type": "OTHER",
18          "source_id": "ea76f0ff-8081-4db6-8333-4e011fe95620"
19        }
20      ]
21    }
22  ]
23}

Key fields for each accounting field selection:

Create a purchase order

After preparing line items, create the purchase order by calling the Create purchase orderAPI endpoint.

1. Send the create request with the required fields:

   Shell

   1curl -X POST \
   2  'https://api.sandbox.airwallex.com/api/v1/spend/purchase_orders/create' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "request_id": "unique-request-id-001",
   7    "external_id": "PO-ERP-001",
   8    "legal_entity_id": "le_xyz789",
   9    "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   10    "purchase_order_number": "PO-2026-001",
   11    "billing_currency": "USD",
   12    "sync_status": "SYNCED",
   13    "line_items": [
   14      {
   15        "description": "Office furniture - standing desks",
   16        "quantity": "10",
   17        "unit_price": "450",
   18        "accounting_field_selections": [
   19          {
   20            "type": "GENERAL_LEDGER_ACCOUNT",
   21            "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d"
   22          }
   23        ]
   24      }
   25    ]
   26  }'

2. The response returns the created purchase order with its unique ID:

   JSON

   1{
   2  "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
   3  "external_id": "PO-ERP-001",
   4  "legal_entity_id": "le_xyz789",
   5  "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   6  "purchase_order_number": "PO-2026-001",
   7  "billing_currency": "USD",
   8  "status": "OPEN",
   9  "sync_status": "SYNCED",
   10  "line_items": [
   11    {
   12      "description": "Office furniture - standing desks",
   13      "quantity": 10,
   14      "unit_price": 450.00,
   15      "accounting_field_selections": [
   16        {
   17          "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   18          "type": "GENERAL_LEDGER_ACCOUNT",
   19          "value": "7100-Furniture",
   20          "external_id": "7100-Furniture",
   21          "value_label": "Furniture"
   22        }
   23      ]
   24    }
   25  ],
   26  "created_at": "2026-02-01T14:00:00Z"
   27}

List purchase orders

To retrieve a list of purchase orders, call the List purchase ordersAPI endpoint.

1. Send the request with optional filters:

   Shell

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

2. The response returns a list of purchase orders:

   JSON

   1{
   2  "items": [
   3    {
   4      "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
   5      "vendor_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
   6      "billing_currency": "USD",
   7      "status": "OPEN",
   8      "sync_status": "SYNCED"
   9    }
   10  ],
   11  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
   12  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
   13}

Key query parameters include:

Get purchase order details

To retrieve the full details of a specific purchase order, call the Get purchase orderAPI endpoint.

1. Use the id from the list response:

   Shell

   1curl -G \
   2  'https://api.sandbox.airwallex.com/api/v1/spend/purchase_orders/{{PO_ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Update the sync status of a purchase order

To update the sync status of an existing purchase order, call the Update purchase order sync statusAPI endpoint.

1. Send the update request with the request body:

   Shell

   1curl -X POST \
   2  'https://api.sandbox.airwallex.com/api/v1/spend/purchase_orders/{{PO_ID}}/sync' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "sync_error_message": "Failed to sync purchase order: this purchase order number already exists.",
   7    "sync_status": "SYNC_FAILED"
   8  }'

2. The response returns the updated purchase order.

Next steps

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

• Vendors via API
• Bills via API
• Error codes