---
title: "Get list of transactions"
method: GET
path: "/v3/spend/transactions"
tags: ["transactions"]
---

# Get list of transactions

`GET /v3/spend/transactions`

Get a list of transaction objects. By default, you get 20 results on one page of results. Set `max` in your request to get up to 50 results on one page. In the response, you get information about transactions, reversals, and refunds.

*   **Transaction**: For a standard transaction, `transactionType` is set as `AUTHORIZATION` or `DECLINE`. The field is updated to `CLEAR` once BILL has moved money from the funding account. `CLEAR` transactions receive a new ID and reference the original `AUTHORIZATION` transaction via the `originalAuthTransactionUuid` field.
*   **Reversal**: For a reversal (cancel before funds are settled), `transactionType` remains `AUTHORIZATION`, but the `amount` is typically a negative value.
*   **Refund**: For a refund (cancel after funds are settled), `transactionType` remains `CLEAR`, but the `amount` is a negative value.

**Note**: Only parent transactions are available in the response.

## Query parameters

- `max` integer, nullable — Maximum number of results
- `nextPage` string, nullable — Next page of results. When a list has multiple pages, the `nextPage` and `prevPage` values in the response enable you to navigate between the pages of results. Set this field as the `nextPage` value for navigation.
- `prevPage` string, nullable — Previous page of results. Set this field as the `prevPage` value for navigation.
- `sort` string, nullable — Field name and sort order. You can set only one sort field. The format is `sort={field}:{sort_order}`. The sortable fields are: - `amount` - `merchantName` - `occurredTime`
- `filters` string, nullable — Field name, operator, and value. You can set multiple filters. The format is `filters={field_01}:{op}:{value},{field_02}:{op}:{value}`. Example: `filters=cardId:eq:MyCardID,userId:in:"123,456"` The filterable fields are: - `cardId` - List of string IDs or UUIDs. Operators: `eq`, `in`. - `merchantName` - String. Operators: `eq`. - `userId` - List of string IDs or UUIDs. Operators: `eq`, `in`. - `budgetId` - List of string IDs or UUIDs. Operators: `eq`, `in`. - `fees` - Number with 2 decimal places. Operators: `lte`, `gte`. - `transactionIds` - List of string IDs or UUIDs. Operators: `eq`, `in`. - `customFieldIds` - List of string IDs or UUIDs. Operators: `eq`, `in`. - `customFieldValueIds` - List of string IDs or UUIDs. Operators: `eq`, `in`. **Note**: Use `customFieldIds` and `customFieldValueIds` to filter transactions based on custom fields. Use the `showCustomFieldIds` query parameter to control which custom fields are shown for each transaction. - `receiptStatus` - `VALIDATED`, `NOT_VALIDATED`, `ATTACHED`, `MISSING`, `NOT_REQUIRED`, `NOT_ATTACHED`. Operators: `eq`, `ne`, `in`, `nin`. - `type` - `CLEAR`, `DECLINE`, `AUTHORIZATION`, `OTHER`. Operators: `eq`, `ne`, `in`, `nin`. **Deprecated**: use `transactionType`. - `transactionType` - `CLEAR`, `DECLINE`, `AUTHORIZATION`, `OTHER`. Operators: `eq`, `ne`, `in`, `nin`. - `occurredTime` - DateTime. Operators: `lte`, `gte`. - `authorizedTime` - DateTime. Operators: `lte`, `gte`. - `updatedTime` - DateTime. Operators: `lte`, `gte`. - `isLocked` - `true` or `false`. Operators: `eq`. - `complete` - `true` or `false`. Operators: `eq`. - `amount` - Number with 2 decimal places. Operators: `lte`, `gte`. - `isReviewed` - `true` or `false`. Operators: `eq`. - `syncStatus` - `PENDING`, `SYNCED`, `ERROR`, `MANUAL_SYNCED`, `NOT_SYNCED`. Operators: `eq`, `ne`, `in`, `nin`.
- `showCustomFieldIds` string, nullable — List of BILL-generated IDs of custom fields to be displayed for each transaction. Set the IDs as comma-separated values. By default, all the custom fields are displayed for all transactions. **NOTE**: Use `customFieldIds` and `customFieldValueIds` to filter transactions based on custom fields.
- `includeReceipts` boolean, nullable — Set as `true` to include transaction receipts in the response. By default, receipts are not included in the response.

## Headers

- `apiToken` string, nullable — Access token for Spend & Expense API authentication

## Response `200`

Get list of transactions response

- PaginatedTransactionsResponseDto — Response from a list API request with paging references.
  - `nextPage` string — Next page token
  - `prevPage` string — Previous page token
  - `results` TransactionResponseDto[] — Results
    - `id` string — BILL-generated ID of the transaction
    - `uuid` string — BILL-generated UUID of the transaction
    - `childTransactionIds` string[] — BILL-generated IDs of child transactions associated with the current transaction
    - `childTransactionUuids` string[] — BILL-generated IDs of child transactions associated with the current transaction
    - `isLocked` boolean — Set as `true` if the transaction is locked
    - `isReconciled` boolean — Set as `true` if the transaction is reconciled
    - `transactionType` 'CLEAR' | 'DECLINE' | 'AUTHORIZATION' — Transaction type.
    - `parentTransactionId` string — BILL-generated ID of the parent transaction. This field is set on child transactions when a parent transaction is split.
    - `userId` string — BILL-generated ID of the user who created the transaction
    - `userUuid` string — BILL-generated UUID of the user who created the transaction
    - `userName` string — Display name of the user who created the transaction
    - `rawMerchantName` string — Raw merchant name for the transaction
    - `merchantName` string — Readable (cleaned) merchant name for the transaction
    - `budgetId` string — BILL-generated ID of the budget linked with the transaction
    - `budgetUuid` string — BILL-generated UUID of the budget linked with the transaction
    - `budgetName` string — Name of the budget linked with the transaction
    - `parentBudgetUuid` string — BILL-generated UUID of the parent budget linked with the transaction
    - `originalAuthTransactionId` string — BILL-generated ID of the originating authorization transaction
    - `originalAuthTransactionUuid` string — BILL-generated UUID of the originating authorization transaction. After a transaction is authorized, it is set as cleared when it is complete. The `originalAuthTransactionUuid` ties the cleared transaction to the authorized transaction. The value is `null` when the transaction is not authorized.
    - `isCredit` boolean — Set as `true` if the transaction is a credit
    - `currencyData` object — Transaction currency information
      - `exchangeRate` number
      - `exponent` integer
      - `originalCurrencyAmount` string
      - `originalCurrencyCode` string
      - `symbol` string
    - `receiptRequired` boolean — Set as `true` if a receipt is required to complete the transaction
    - `reviewRequired` boolean — Set as `true` if a review is required to complete the transaction
    - `status` 'APPROVED' | 'COMPLETE' | 'DECLINED' | 'DENIED' | 'DISPUTE_LOST' | 'DISPUTE_UPDATE' | 'DISPUTE_WON' | 'DISPUTED' | 'DO_NOT_SYNC' | 'INCOMPLETE' | 'NONE' | 'PENDING' | 'PTR_INCOMPLETE' | 'PTR_NEEDS_YOUR_APPROVAL' | 'PTR_PENDING_APPROVAL' | 'PTR_UPCOMING_APPROVAL' | 'REVIEWED' — Transaction status
    - `occurredTime` string, date-time — Created date and time
    - `updatedTime` string, date-time — Updated date and time
    - `authorizedTime` string, date-time — Transaction authorized date and time
    - `complete` boolean — Set as `true` if the transaction has all the required fields completed
    - `pointsAwarded` integer — Points awarded for the transaction. This value is `0` until the transaction is cleared. **Note**: Only `ADMIN` users can view any awarded points.
    - `customFields` CustomFieldDto[] — Transaction custom fields information
      - `id` string — BILL-generated ID of the custom field
      - `uuid` string — BILL-generated UUID of the custom field
      - `name` string — Custom field name
      - `note` string — Custom field note
      - `isRequired` boolean — Set as `true` if the custom field is required
      - `selectedValues` CustomFieldValueDto[] — List of selected values for this custom field. **NOTE**: In the response, you get up to 20 selected values for a custom field. Use `GET /v3/spend/custom-fields/{customFieldId}/values` to get the complete list of selected values.
        - `id` string — BILL-generated ID of the custom field value
        - `uuid` string — BILL-generated UUID of the custom field value
        - `value` string — Custom field value
    - `receipts` ReceiptImage[] — List of receipts attached to the transaction
      - `url` string, required — Uploaded receipt URL
      - `filename` string, required — Receipt file name
      - `uuid` string, required — BILL-generated UUID for the receipt image
    - `network` 'VISA' | 'MASTERCARD' — Transaction network type.
    - `isParent` boolean — Set as `true` if the transaction is the parent of another transaction
    - `reviews` Review[] — Transaction review information
      - `id` string — BILL-generated ID of the review
      - `isApproved` boolean — Set as `true` if the transaction was approved
      - `note` string — Review note
      - `createdTime` string, date-time — Review created date and time
      - `deletedTime` string, date-time — Review deleted date and time (if available)
      - `reviewerId` string — BILL-generated ID of the user who reviewed the transaction
      - `reviewerUuid` string — BILL-generated UUID of the user who reviewed the transaction
    - `amount` number — Transaction amount including fees. When `amount` is negative, the transaction is a reversal or refund. * **Reversal**: For a reversal (cancel before funds are settled), `transactionType` is set as `AUTHORIZATION` and `amount` is a negative value. * **Refund**: For a refund (cancel after funds are settled), `transactionType` is set as `CLEAR` and `amount` is a negative value.
    - `transactedAmount` number — Transaction amount not including fees
    - `fees` number — Sum of transaction fees (including `foreignExchangeFee`)
    - `foreignExchangeFee` number — Foreign exchange fee for the transaction (if any)
    - `receiptStatus` 'VALIDATED' | 'NOT_VALIDATED' | 'ATTACHED' | 'MISSING' | 'NOT_REQUIRED' | 'NOT_ATTACHED' | 'UNSPECIFIED' — Receipt status.
    - `matchedClearTransactionId` string — BILL-generated ID of the cleared transaction. Use this ID to identify the transaction after it is cleared.
    - `matchedClearTransactionUuid` string — BILL-generated UUID of the cleared transaction. Use this ID to identify the transaction after it is cleared.
    - `accountingIntegrationTransactions` AccountingIntegrationTransaction[] — Accounting system integration information
      - `id` string — BILL-generated ID of the transaction in your accounting system
      - `billable` boolean — Set as `true` if the transaction can be billed to a client or customer
      - `integrationTxId` string — Unique transaction ID in your accounting system
      - `syncStatus` string — Current sync status of the transaction with your accounting system
      - `syncMessage` string — Message describing the result of the previous sync attempt
      - `integrationType` string — Accounting system integration type
      - `integrationId` string — BILL-generated ID of the accounting system integration
      - `syncRequestId` string — Unique ID of the sync request that processed the transaction
    - `reviewers` Reviewer[] — Transaction reviewers information
      - `approverType` 'ADMIN' | 'MANAGER' | 'NEXT_MANAGER' | 'BUDGET_OWNER' | 'BOOKKEEPER' | 'SPECIFIC_PERSON' — Approver type.
      - `reviewedTime` string, date-time — Transaction review date and time
      - `status` 'WAITING' | 'APPROVED' | 'DENIED' — Review status.
      - `userId` string — BILL-generated ID of the user assigned to review the transaction
      - `userUuid` string — BILL-generated UUID of the user assigned to review the transaction
      - `userName` string — Display name of the user assigned to review the transaction
    - `cardId` string — BILL-generated ID of the card used to make the transaction
    - `cardUuid` string — BILL-generated UUID of the card used to make the transaction
    - `cardLastFour` string — Last four digits of the card number used to make the transaction
    - `cardType` 'PHYSICAL' | 'VIRTUAL_MEMBER' | 'VIRTUAL_VENDOR' | 'VIRTUAL' — Type of the card used to make the transaction
    - `receiptSyncStatus` 'NOT_SYNCED' | 'SYNCED' | 'SYNC_ERROR' | 'NO_ATTACHMENTS' — Transaction receipt sync status.
    - `merchantCategoryCode` string — Merchant category code
    - `declineReason` string — Human-readable transaction decline reason. This field is available when `transactionType` is set as `DECLINE`.
    - `declineInternalReasonCode` string — Transaction decline reason code. This field is available when `transactionType` is set as `DECLINE`.
    - `cardPresent` boolean — Set as `true` if a physical card was present for the transaction
    - `merchantLocation` object — Merchant location information for the transaction. This information is available when `cardPresent` is set as `true`.
      - `city` string — Merchant city
      - `state` string — Merchant state or region
      - `postalCode` string — Merchant zip or postal code
      - `country` string — Merchant country
    - `disputeStatus` 'SUBMITTED' | 'IN_PROGRESS' | 'CLOSED_WON' | 'CLOSED_LOST' — Dispute status for the transaction. This information is available when the transaction has been disputed.

## Other responses

- `4XX` — List of errors.
- `5XX` — List of errors.

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/versions/0483350c434e/schema)