# List all Expenses

> Status: beta

List expenses based on the query parameters.

## Endpoint

`GET /api/v1/spend/expenses`

## Request Headers

- `Authorization` (string, required)
  Obtain a token via `POST /api/v1/authentication/login` with your API key and client unique identifier. Pass it as `Authorization: Bearer {{ACCESS_TOKEN}}`. Tokens expire after a configurable duration.

## Request Parameters

### Query Parameters

- `page` (string, optional)
  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.
- `page_size` (integer, optional)
  The number of items returned per page, between 1 and 100. The default is 100.
- `from_created_at` (string, optional)
  Filter by expenses created after this timestamp (inclusive) in ISO8601 format.

  If not specified, defaults to last 30 days from `to_created_at`.
- `to_created_at` (string, optional)
  Filter by expenses created before this timestamp (exclusive) in ISO8601 format.

  If not specified, defaults to now.
- `status` (array[string], optional)
  Filter by expense statuses. Additional values may appear; implementations should handle unknown values gracefully.
- `sync_status` (array[string], optional)
  Filter by sync statuses.
- `legal_entity_id` (string, optional)
  Filter by legal entity identifier.

## cURL example

```bash
curl --request GET \
  --url 'https://api.sandbox.airwallex.com/api/v1/spend/expenses' \
  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json'
```

## Response

### 200 OK

**Example:**

```json
{
  "items": [
    {
      "id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
      "account_id": "acct_a2y0pxz3m4k5hoZldn97hjzp",
      "legal_entity_id": "le_U3jlHqQRNHWn2zAKeeT8sg",
      "card_id": "93eed14b-104d-4f40-ae1d-3633c6538276",
      "status": "AWAITING_APPROVAL",
      "card_transaction": {
        "status": "CLEARED",
        "amount": "105.50",
        "currency": "USD"
      },
      "sync_status": "SYNCED",
      "billing_currency": "USD",
      "billing_amount": "105.5",
      "description": "Client dinner at restaurant for Q4 planning meeting.",
      "merchant": "Starbucks Coffee #1234",
      "approvers": [
        "manager@company.com",
        "finance@company.com"
      ],
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-02-02T00:00:00Z",
      "settled_at": "2025-03-03T10:15:30Z",
      "accounting_field_selections": [
        {
          "type": "MERCHANT",
          "source_id": "ba46f0ff-8081-4db6-8333-4e011fe9561d",
          "name": null,
          "external_id": null,
          "value": "Starbucks Coffee #1234",
          "value_label": "Starbucks Coffee #1234"
        }
      ],
      "attachments": [
        {
          "id": "0fd62109-cfc0-4c94-86a5-d01c42506b76",
          "content_type": "image/jpeg",
          "file_name": "receipt.jpg",
          "file_url": "https://files.airwallex.com/receipt.jpg",
          "created_at": "2024-12-16T09:22:00Z"
        }
      ],
      "line_items": [
        {
          "id": "a12fca5e-4aeb-4adb-85b0-428b4f078aba",
          "transaction_amount": "105.50",
          "description": "Business meal with client.",
          "accounting_field_selections": []
        }
      ],
      "comments": [
        {
          "content": "Expense approved - valid business purpose confirmed",
          "created_by": "manager@company.com",
          "created_at": "2025-01-01T00:00:00Z"
        }
      ]
    }
  ],
  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
}
```

- `items` (array[object], required)
  List of items returned.
  - `account_id` (string, required)
    Unique identifier of the Airwallex account that owns this expense. This determines which account the expense amount is debited from.
  - `accounting_field_selections` (array[object], required)
    Accounting categories and custom fields assigned to this expense for reporting and categorization in your accounting system.
    - `source_id` (string, format: uuid, required)
      Unique identifier of the merchant associated with this expense. This value is returned for reference only and is not supported in Bill or Purchase Order create requests.
    - `type` (string, required)
      Type of accounting field.
      Possible values:
      - `MERCHANT` — Merchant accounting field selection.
    - `value` (string, required)
      Name of the accounting field value in the ERP.
    - `external_id` (string, optional)
      External unique identifier of the accounting field value in the ERP.
    - `name` (string, optional)
      Name of the accounting field in the ERP software. This field is populated only when `type` is set to `OTHER`.
    - `value_label` (string, optional)
      Name of the accounting field value displayed in Airwallex.
  - `approvers` (array[string], required)
    Email addresses of users authorized to approve this expense. An empty array indicates no approval is required or the expense has already been approved.
  - `attachments` (array[object], required)
    Receipt images and supporting documents uploaded for this expense. Commonly used for compliance and approval workflows.
    - `content_type` (string, required)
      MIME type of the attached file. Common types include `image/jpeg`, `image/png`, and `application/pdf`.
    - `created_at` (string, required)
      Timestamp for when the resource was created in ISO8601 format.
    - `file_name` (string, required)
      Original filename of the uploaded attachment, including the file extension.
    - `file_url` (string, required)
      URL to access and download the attachment file. Authentication is required.
    - `id` (string, format: uuid, required)
      Unique identifier of the attachment.
  - `billing_amount` (string, required)
    Total amount charged to your account in billing currency, including any fees or currency conversion. This may differ from the original transaction amount.
  - `billing_currency` (string, required)
    Currency in which the billing amount is charged to your account. This is your account's primary currency, regardless of the original transaction currency.
  - `card_id` (string, format: uuid, required)
    Unique identifier of the Airwallex card used to make this purchase. Links the expense to the specific card and cardholder for tracking and reporting.
  - `card_transaction` (object, required)
    Details of the original card transaction associated with an expense, including the authorization status, amount, and currency.
    - `amount` (string, required)
      Amount of the original card transaction in the transaction currency.
    - `currency` (string, required)
      Currency of the original card transaction, as an ISO 4217 currency code.
    - `status` (string, required)
      Transaction status.
      Possible values:
      - `AUTHORIZED`
      - `CLEARED`
      - `DECLINED`
      - `REVERSED`
  - `comments` (array[object], required)
    Conversation thread and notes about this expense, typically used for approval workflows and clarifications between cardholders and approvers.
    - `content` (string, required)
      Text body of the comment.
    - `created_at` (string, required)
      Timestamp for when the resource was created in ISO8601 format.
    - `created_by` (string, optional)
      Email address of the user who created this comment. Used for attribution, notifications, and audit trail tracking.
  - `created_at` (string, required)
    Timestamp for when the resource was created in ISO8601 format.
  - `id` (string, format: uuid, required)
    Unique identifier of the expense.
  - `legal_entity_id` (string, required)
    Unique identifier of the business entity associated with this expense. Used for accounting segregation and compliance reporting across different business entities.
  - `line_items` (array[object], required)
    Breakdown of the expense into detailed line items with individual accounting categories. The sum of all line item amounts should equal the total expense amount.
    - `accounting_field_selections` (array[object], required)
      Accounting and categorization fields assigned to this specific line item. Allows for different accounting treatment of individual components within a single expense.
      - `source_id` (string, format: uuid, required)
        Unique identifier of the selected general ledger (GL) account, tax code, or accounting field value.
      - `type` (string, required)
        Type of accounting field.
        Possible values:
        - `GENERAL_LEDGER_ACCOUNT` — General ledger (GL) account assigned to the line item.
        - `TAX_CODE` — Tax code applied to the line item.
        - `OTHER` — Custom accounting field defined in your ERP. The field name is provided in `name`.
      - `value` (string, required)
        Name of the accounting field value in the ERP.
      - `external_id` (string, optional)
        External unique identifier of the accounting field value in the ERP.
      - `name` (string, optional)
        Name of the accounting field in the ERP software. This field is populated only when `type` is set to `OTHER`.
      - `value_label` (string, optional)
        Name of the accounting field value displayed in Airwallex.
    - `id` (string, format: uuid, required)
      Unique identifier of the expense line item.
    - `description` (string, optional)
      Optional description providing details about this specific line item. Helps explain what this component of the expense represents for accounting and approval purposes.
    - `transaction_amount` (string, optional)
      Amount of this line item in the transaction currency, including all taxes. Represents the actual expense amount for this specific component of the overall expense.
  - `status` (string, required)
    Current approval status of the expense. Additional values may appear; implementations should handle unknown values gracefully.
    Possible values:
    - `DRAFT`
    - `AWAITING_APPROVAL`
    - `REJECTED`
    - `APPROVED`
    - `ARCHIVED`
    - `DELETED`
  - `sync_status` (string, required)
    Expense sync status.
    Possible values:
    - `NOT_SYNCED`
    - `READY_TO_SYNC`
    - `SYNCED`
    - `SYNC_FAILED`
  - `updated_at` (string, required)
    Timestamp for when the resource was updated in ISO8601 format.
  - `attendees` (array[object], optional)
    Attendees associated with this expense, including internal employees and external guests.
    - `external` (boolean, required)
      Indicates whether the attendee is external to the organization.
    - `name` (string, required)
      Name of the attendee.
    - `email` (string, optional)
      Email address of the attendee. Present only when `external` is `false`.
  - `description` (string, optional)
    Optional description or memo providing additional context about the expense. Often includes the business purpose or additional details about the purchase.
  - `merchant` (string, optional)
    Name of the business or merchant where the purchase was made, as reported by the payment network. Null for some transaction types.
  - `settled_at` (string, optional)
    Timestamp when the transaction was settled, in ISO8601 format. Null if transaction is still pending settlement.
- `page_after` (string, optional)
  A pointer to the end of the page list used in pagination to retrieve the next page of results.
- `page_before` (string, optional)
  A pointer to the start of the page list use in pagination to retrieve the previous page of results.

## Errors

### 400 Bad request

Invalid Request.

### 404 Not found

Not found.

### 500 Server error

Internal server error.