Get all Transactions

Overview

The Transactions API allows you to retrieve a comprehensive history of all financial transactions associated with your account. This includes purchases, deposits, withdrawals, transfers, bill payments, and all other financial activities.

Endpoint Type: GraphQL Query
Authentication: Required (JWT Bearer Token)
Required Scopes: LIST_PAYMENT AND LIST_PURCHASES
Rate Limit: Standard GraphQL rate limits apply

Quick Start

Basic Query

query GetTransactions {
  getTransactions {
    transactions {
      recordId
      transactionType
      amount
      status
      channel
      connectedAppId
      connectedAppName
      createdAt
    }
    totalCount
    hasNextPage
  }
}

Query Structure

getTransactions(
  filter: TransactionFilterInput
  paginate: OffsetInput
): TransactionConnection!

Parameters

Parameter	Type	Required	Description
`filter`	`TransactionFilterInput`	No	Filtering criteria for transactions
`paginate`	`OffsetInput`	No	Pagination parameters (default: limit=20, offset=0)

Response Structure

TransactionConnection

type TransactionConnection {
  transactions: [Transaction]
  totalCount: Int!
  hasNextPage: Boolean!
}

Field	Type	Description
`transactions`	`[Transaction]`	Array of transaction records
`totalCount`	`Int!`	Total count of transactions matching filter (for pagination)
`hasNextPage`	`Boolean!`	Whether more results are available

Filter Options

TransactionFilterInput

input TransactionFilterInput {
  # Record & Status
  recordId: [UUID]
  status: [TransactionStatus]
  
  # Amount Filters
  amount: Float
  amountGte: Float
  amountLte: Float
  finalAmount: Float
  finalAmountGte: Float
  finalAmountLte: Float
  
  # Cashback Filters
  cashbackAmount: Float
  cashbackAmountGte: Float
  cashbackAmountLte: Float
  cashbackPercentage: Float
  cashbackPercentageGte: Float
  cashbackPercentageLte: Float
  
  # Fee Filters
  feeAmount: Float
  feeAmountGte: Float
  feeAmountLte: Float
  
  # Date Filters
  createdGte: DateTime
  createdLte: DateTime
  updatedGte: DateTime
  updatedLte: DateTime
  
  # Merchant Filters
  merchantId: [UUID]
  merchant: [String]
  
  # Transaction Properties
  transactionType: [String]
  channel: [String!]
  category: [String]
  
  # Virtual Card Filters
  virtualCardProgram: [String]
  virtualCard: [UUID]
  
  # Other
  fundingSource: [String]
  userCashBalanceId: [UUID]
  referenceId: String
  liabilityId: UUID
}

Filter Field Details

Record & Status Filters

`recordId`

Type: [UUID]
Description: Filter by specific transaction record IDs.

Example:

filter: {
  recordId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`status`

Type: [TransactionStatus]
Description: Filter by transaction status.

Options:

PENDING - Transaction is being processed
SETTLED - Transaction completed successfully

Example:

filter: {
  status: [SETTLED]
}

Amount Filters

`amount`, `amountGte`, `amountLte`

Type: Float
Description: Filter by exact amount or amount range in USD.

amount - Exact amount match
amountGte - Minimum amount (greater than or equal)
amountLte - Maximum amount (less than or equal)

Example:

# Transactions between $10 and $500
filter: {
  amountGte: 10.00
  amountLte: 500.00
}

`finalAmount`, `finalAmountGte`, `finalAmountLte`

Type: Float
Description: Filter by final amount (amount + fees).

Example:

filter: {
  finalAmountGte: 25.00
}

Cashback Filters

`cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

Type: Float
Description: Filter by cashback amount earned.

Example:

# Transactions that earned $5 or more in cashback
filter: {
  cashbackAmountGte: 5.00
}

`cashbackPercentage`, `cashbackPercentageGte`, `cashbackPercentageLte`

Type: Float
Description: Filter by cashback rate percentage.

Example:

# Transactions with 5% or higher cashback
filter: {
  cashbackPercentageGte: 5.0
}

Fee Filters

`feeAmount`, `feeAmountGte`, `feeAmountLte`

Type: Float
Description: Filter by transaction fee amount.

Example:

# Transactions with fees
filter: {
  feeAmountGte: 0.01
}

Date Filters

`createdGte`, `createdLte`

Type: DateTime
Format: ISO 8601 (e.g., 2025-01-01T00:00:00Z)
Description: Filter by transaction creation date range.

Example:

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

`updatedGte`, `updatedLte`

Type: DateTime
Description: Filter by transaction last update date range.

Merchant Filters

`merchantId`

Type: [UUID]
Description: Filter by specific merchant IDs.

Example:

filter: {
  merchantId: ["550e8400-e29b-41d4-a716-446655440000"]
}

`merchant`

Type: [String]
Description: Filter by merchant names (matches against destination field).

Example:

filter: {
  merchant: ["Amazon", "Walmart"]
}

Transaction Properties

`transactionType`

Type: [String]
Description: Filter by specific transaction types.

Common Values:

Add Money - Deposits
Gift Card Purchase - Gift card purchases
Transfer - In - Incoming transfers
Transfer - Out - Outgoing transfers
Virtual Card Purchase - Virtual card purchases
Withdrawal

Example:

filter: {
  transactionType: ["Gift Card Purchase", "Add Money"]
}

`channel`

Type: [String!]
Description: Filter by platform channel.

Common Values:

WEB - Web browser
MOBILE - Mobile app
API - API requests

Example:

filter: {
  channel: ["WEB", "MOBILE"]
}

`category`

Type: [String]
Description: Filter by transaction category.

Example:

filter: {
  category: ["Shopping", "Travel"]
}

Virtual Card Filters

`virtualCardProgram`

Type: [String]
Description: Filter by virtual card program/issuer.

Common Values:

LITHIC
MARQETA
HIGHNOTE_CFSB
HIGHNOTE_SUTTON
HIGHNOTE_TPB
I2C

Example:

filter: {
  virtualCardProgram: ["LITHIC", "MARQETA"]
}

`virtualCard`

Type: [UUID]
Description: Filter by specific virtual card IDs.

Example:

filter: {
  virtualCard: ["vc-1", "vc-2"]
}

Other Filters

`fundingSource`

Type: [String]
Description: Search for funding source names (partial match on source or destination).

Example:

filter: {
  fundingSource: ["Visa"]
}

`referenceId`

Type: String
Description: Filter by external reference ID (e.g., purchase display ID).

Example:

filter: {
  referenceId: "1000123"
}

`liabilityId`

Type: UUID
Description: Filter by liability ID (for bill payments).

Pagination

OffsetInput

input OffsetInput {
  limit: Int = 20
  offset: Int = 0
}

Field	Type	Default	Max	Description
`limit`	Int	20	20	Number of transactions to return per page
`offset`	Int	0	-	Number of transactions to skip

Example - Page 1:

paginate: {
  limit: 20
  offset: 0
}

Example - Page 2:

paginate: {
  limit: 20
  offset: 20
}

Example - Check if more pages exist:

query GetTransactions {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions { record_id }
    hasNextPage  # Use this to determine if there are more results
    totalCount   # Total matching records
  }
}

Transaction Type

type Transaction {
  record_id: UUID
  user: String!
  account_id: UUID!
  user_id: UUID
  transaction_type: String
  amount: Float!
  destination: String
  source: String
  external_funding_source_activity: Float
  fluz_balance_activity: Float
  fee: Float
  cashback: Float
  
  # Ending balances after transaction
  gift_card_prepayment_balance_available_balance: Float
  gift_card_prepayment_balance_total_balance: Float
  cash_balance_available_balance: Float
  cash_balance_total_balance: Float
  seat_balance_available_balance: Float
  seat_balance_total_balance: Float
  reserve_balance_available_balance: Float
  reserve_balance_total_balance: Float
  other_cash_balance_available_balance: Float
  other_cash_balance_total_balance: Float
  
  status: TransactionStatus
  reference_id: String
  description: String
  note: String
  category: String
  card_last_four: String
  card_display_name: String
  original_currency_amount: Float
  original_currency_code: String
  conversion_rate: Float
  merchant_id: UUID
  descriptor_id: UUID
  virtual_card_program: String
  cashback_rate: Float
  bonus_cashback_rate: Float
  channel: String
  source_type: String
  logo_url: String
  platformInstitutionLogo: String
  challengeLogoUrl: String
  invitedAccountId: UUID
  expectedClearedDate: DateTime
  liability_id: UUID
  is_gift_card_balance_affected: Boolean
  is_cash_balance_affected: Boolean
  is_seat_balance_affected: Boolean
  is_reserve_balance_affected: Boolean
  transfer_id: UUID
  used_user_cash_balance_id: UUID
  connectedAppId: UUID
  connectedAppName: String
  
  memo: String
	transactionCategory: String
  attachmentUrl: String

  created_at: DateTime
  updated_at: DateTime
}

Field Descriptions

Core Transaction Fields

Field	Type	Description
`record_id`	UUID	Unique identifier for this transaction record
`user`	String	Display name of the user associated with transaction
`account_id`	UUID	Account that owns this transaction
`user_id`	UUID	User who initiated the transaction
`transaction_type`	String	Type of transaction (PURCHASE, DEPOSIT, etc.)
`amount`	Float	Primary transaction amount in USD
`source`	String	Where the funds came from (e.g., "Bank Card ****1234")
`destination`	String	Where the funds went (e.g., merchant name)
`status`	TransactionStatus	Current status (PENDING or SETTLED)

Financial Details

Field	Type	Description
`external_funding_source_activity`	Float	Change to external funding sources (bank cards/accounts)
`fluz_balance_activity`	Float	Change to Fluz internal balances
`fee`	Float	Fees charged for this transaction
`cashback`	Float	Cashback earned from this transaction
`cashback_rate`	Float	Cashback rate percentage
`bonus_cashback_rate`	Float	Additional bonus cashback rate

Balance Snapshots

Important: All balance fields show the balance after this transaction was applied.

Field	Description
`cash_balance_available_balance`	Available cash balance after transaction
`cash_balance_total_balance`	Total cash balance after transaction
`seat_balance_available_balance`	Available rewards balance after transaction
`seat_balance_total_balance`	Total rewards balance after transaction
`gift_card_prepayment_balance_available_balance`	Available prepayment balance after transaction
`gift_card_prepayment_balance_total_balance`	Total prepayment balance after transaction
`reserve_balance_available_balance`	Available reserve balance after transaction
`reserve_balance_total_balance`	Total reserve balance after transaction
`other_cash_balance_available_balance`	Other cash available balance after transaction
`other_cash_balance_total_balance`	Other cash total balance after transaction

Transaction Details

Field	Type	Description
`reference_id`	String	External reference (e.g., purchase display ID)
`description`	String	Human-readable description
`note`	String	Additional notes
`category`	String	Transaction category
`card_last_four`	String	Last 4 digits of card used (if applicable)
`card_display_name`	String	Display name of payment method
`memo`	String	A free-text memo attached to this transaction. Set via `updateTransactionMetadata` or at transaction time on deposits, purchases, and transfers.
`transactionCategory	String	Category label attached to this transaction. Set via `updateTransactionMetadata` or at transaction time on deposits, purchases, and transfers.
`attachmentUrl`	String	A signed URL for the file attached to this transaction. Set via `updateTransactionMetadata` or at transaction time. This URL expires — do not store it. Re-fetch the transaction when you need to access the file.

Merchant Information

Field	Type	Description
`merchant_id`	UUID	Merchant identifier
`descriptor_id`	UUID	Transaction descriptor ID
`logo_url`	String	URL to merchant/source logo

Virtual Card Information

Field	Type	Description
`virtual_card_program`	String	Virtual card program (LITHIC, MARQETA, etc.)

Currency Conversion

Field	Type	Description
`original_currency_amount`	Float	Amount in original currency (for foreign transactions)
`original_currency_code`	String	Original currency code (e.g., "EUR")
`conversion_rate`	Float	Exchange rate applied

Metadata

Field	Type	Description
`channel`	String	Platform channel (WEB, MOBILE, API)
`source_type`	String	Type of funding source
`liability_id`	UUID	Associated liability (for bill payments)
`transfer_id`	UUID	Associated transfer (for P2P)
`used_user_cash_balance_id`	UUID	Specific cash balance used
`is_gift_card_balance_affected`	Boolean	Whether gift card balance changed
`is_cash_balance_affected`	Boolean	Whether cash balance changed
`is_seat_balance_affected`	Boolean	Whether rewards balance changed
`is_reserve_balance_affected`	Boolean	Whether reserve balance changed
`connectedAppId`	UUID	Associated application ID
`connectedAppName`	String	Associated application name
`created_at`	DateTime	When transaction was created
`updated_at`	DateTime	When transaction was last updated

Examples

Example 1: Basic Transaction List

Query:

query GetRecentTransactions {
  getTransactions(
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      cashback
      created_at
    }
    totalCount
    hasNextPage
  }
}

Response:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "transaction_type": "GIFT_CARD_PURCHASE",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "status": "SETTLED",
          "cashback": 2.50,
          "created_at": "2025-01-15T14:30:00Z"
        },
        {
          "record_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "transaction_type": "DEPOSIT",
          "amount": 100.00,
          "description": "Cash Balance Deposit",
          "status": "SETTLED",
          "cashback": 0.00,
          "created_at": "2025-01-14T10:15:00Z"
        }
      ],
      "totalCount": 2,
      "hasNextPage": false
    }
  }
}

Example 2: Filtered by Date Range

Query:

query GetJanuaryTransactions {
  getTransactions(
    filter: {
      createdGte: "2025-01-01T00:00:00Z"
      createdLte: "2025-01-31T23:59:59Z"
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      status
      created_at
    }
    totalCount
    hasNextPage
  }
}

Example 3: Purchases Only with Balances

Query:

query GetPurchaseHistory {
  getTransactions(
    filter: {
      transactionType: ["GIFT_CARD_PURCHASE"]
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      reference_id
      amount
      description
      source
      destination
      cashback
      cashback_rate
      cash_balance_available_balance
      seat_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}

Response:

{
  "data": {
    "getTransactions": {
      "transactions": [
        {
          "record_id": "550e8400-e29b-41d4-a716-446655440000",
          "reference_id": "1000123",
          "amount": 50.00,
          "description": "Gift card purchase at Amazon",
          "source": "Visa ****1234",
          "destination": "Amazon",
          "cashback": 2.50,
          "cashback_rate": 5.0,
          "cash_balance_available_balance": 102.50,
          "seat_balance_available_balance": 25.00,
          "created_at": "2025-01-15T14:30:00Z"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}

Example 4: High-Cashback Transactions

Query:

query GetHighCashbackTransactions {
  getTransactions(
    filter: {
      cashbackPercentageGte: 5.0
      status: [SETTLED]
    }
    paginate: { limit: 10, offset: 0 }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      description
      cashback
      cashback_rate
      status
      created_at
    }
    totalCount
  }
}

Example 5: Amount Range Filter

Query:

query GetMediumTransactions {
  getTransactions(
    filter: {
      amountGte: 50.00
      amountLte: 200.00
      status: [SETTLED]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      transaction_type
      description
      created_at
    }
    totalCount
    hasNextPage
  }
}

Example 6: Virtual Card Transactions

Query:

query GetVirtualCardTransactions {
  getTransactions(
    filter: {
      virtualCardProgram: ["LITHIC", "MARQETA"]
    }
    paginate: { limit: 20, offset: 0 }
  ) {
    transactions {
      record_id
      amount
      description
      virtual_card_program
      merchant_id
      status
      created_at
    }
    totalCount
  }
}

Example 7: Pagination Example

Query - Get first page and check for more:

query GetFirstPage {
  getTransactions(paginate: { limit: 20, offset: 0 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

Response shows hasNextPage=true:

{
  "data": {
    "getTransactions": {
      "transactions": [...],
      "totalCount": 150,
      "hasNextPage": true
    }
  }
}

Query - Get second page:

query GetSecondPage {
  getTransactions(paginate: { limit: 20, offset: 20 }) {
    transactions {
      record_id
      amount
      transaction_type
    }
    totalCount
    hasNextPage
  }
}

Error Handling

Common Errors

Missing or Invalid Token

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

HTTP Status: 401 Unauthorized

Insufficient Permissions

{
  "errors": [
    {
      "message": "Insufficient permissions: LIST_PAYMENT and LIST_PURCHASES scopes required",
      "extensions": {
        "code": "FORBIDDEN",
        "requiredScopes": ["LIST_PAYMENT", "LIST_PURCHASES"]
      }
    }
  ]
}

HTTP Status: 403 Forbidden

Invalid Filter Parameters

{
  "errors": [
    {
      "message": "Invalid date format for createdGte",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

HTTP Status: 400 Bad Request

Rate Limit Exceeded

{
  "errors": [
    {
      "message": "Rate limit exceeded. Please try again later.",
      "extensions": {
        "code": "RATE_LIMITED",
        "retryAfter": 60
      }
    }
  ]
}

HTTP Status: 429 Too Many Requests

Best Practices

1. Use Pagination Effectively

Always check hasNextPage to determine if more results exist:

async function fetchAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 20;
  
  while (true) {
    const result = await getTransactions({ 
      paginate: { limit, offset } 
    });
    
    allTransactions.push(...result.transactions);
    
    if (!result.hasNextPage) break;
    offset += limit;
  }
  
  return allTransactions;
}

2. Request Only Needed Fields

Specify only the fields you need to reduce response size:

# ✅ Good - minimal fields
getTransactions {
  transactions {
    record_id
    amount
    transaction_type
    created_at
  }
  totalCount
  hasNextPage
}

# ❌ Less efficient - requesting all 40+ fields
getTransactions {
  transactions {
    record_id
    transaction_type
    amount
    ... (all fields)
  }
}

3. Use Date Filters for Historical Queries

When querying older transactions, always use date filters:

# ✅ Good
filter: {
  createdGte: "2024-01-01T00:00:00Z"
  createdLte: "2024-12-31T23:59:59Z"
}

4. Cache Settled Transactions

Transactions with status: SETTLED are immutable and can be cached:

// Example caching strategy
const cacheKey = `transactions:${accountId}:${createdGte}:${createdLte}`;
let result = cache.get(cacheKey);

if (!result) {
  result = await getTransactions({
    filter: { status: ['SETTLED'], createdGte, createdLte }
  });
  cache.set(cacheKey, result, '1 hour');
}

5. Combine Filters Efficiently

Use range filters to narrow results before applying other filters:

# ✅ Efficient - date range first
filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
  transactionType: ["GIFT_CARD_PURCHASE"]
  amountGte: 50.00
}

Rate Limits

Resource	Limit	Window
Queries per user	100	1 minute
Queries per IP	300	1 minute

Headers:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Time when the rate limit resets (Unix timestamp)

Code Examples

JavaScript/TypeScript

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://api.fluz.app/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${accessToken}`,
  },
});

const GET_TRANSACTIONS = gql`
  query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
    getTransactions(filter: $filter, paginate: $paginate) {
      transactions {
        record_id
        transaction_type
        amount
        description
        status
        cashback
        created_at
      }
      totalCount
      hasNextPage
    }
  }
`;

async function fetchTransactions() {
  const { data } = await client.query({
    query: GET_TRANSACTIONS,
    variables: {
      filter: {
        status: ['SETTLED'],
        createdGte: '2025-01-01T00:00:00Z',
      },
      paginate: {
        limit: 20,
        offset: 0,
      },
    },
  });
  
  return data.getTransactions;
}

Python

import requests

def get_transactions(access_token, created_gte=None, created_lte=None, limit=20, offset=0):
    url = "https://api.fluz.app/graphql"
    
    query = """
        query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) {
            getTransactions(filter: $filter, paginate: $paginate) {
                transactions {
                    record_id
                    transaction_type
                    amount
                    description
                    status
                    cashback
                    created_at
                }
                totalCount
                hasNextPage
            }
        }
    """
    
    variables = {
        "filter": {},
        "paginate": {
            "limit": limit,
            "offset": offset
        }
    }
    
    if created_gte:
        variables["filter"]["createdGte"] = created_gte
    if created_lte:
        variables["filter"]["createdLte"] = created_lte
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(
        url,
        json={"query": query, "variables": variables},
        headers=headers
    )
    
    return response.json()["data"]["getTransactions"]

# Usage
result = get_transactions(
    access_token="your_token_here",
    created_gte="2025-01-01T00:00:00Z",
    limit=20
)

print(f"Found {result['totalCount']} transactions")
print(f"Has more pages: {result['hasNextPage']}")

cURL

curl -X POST https://api.fluz.app/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetTransactions($filter: TransactionFilterInput, $paginate: OffsetInput) { getTransactions(filter: $filter, paginate: $paginate) { transactions { record_id transaction_type amount description status cashback created_at } totalCount hasNextPage } }",
    "variables": {
      "filter": {
        "status": ["SETTLED"],
        "createdGte": "2025-01-01T00:00:00Z"
      },
      "paginate": {
        "limit": 20,
        "offset": 0
      }
    }
  }'

FAQ

Q: What's the maximum number of transactions I can retrieve in one request?

A: The maximum limit is 20 transactions per request. Use the hasNextPage field to implement pagination.

Q: How far back does transaction history go?

A: All transactions from account creation are available indefinitely.

Q: Are pending transactions included?

A: Yes, pending transactions are included by default. Filter by status: [SETTLED] to exclude them.

Q: What timezone are the timestamps in?

A: All timestamps are in UTC (ISO 8601 format).

Q: What scopes do I need?

A: You need both LIST_PAYMENT AND LIST_PURCHASES scopes.

Q: Can I filter by user ID within my account?

A: No, the API always returns all transactions for your account. There is no user-level filtering.

Q: What's the difference between `amount` and `finalAmount` filters?

amount filters the base transaction amount
finalAmount filters amount + fees (the total charged to the user)

Q: How do I filter by date range?

A: Use createdGte and createdLte for creation date:

filter: {
  createdGte: "2025-01-01T00:00:00Z"
  createdLte: "2025-01-31T23:59:59Z"
}

Support

API Status: https://status.fluz.app
Developer Portal: https://developers.fluz.app
Support Email: [email protected]
Slack Community: https://fluz-dev.slack.com

Changelog

v1.0.0 (Branch: 13-fluz-15659-add-transactions-query-and-webhook-to-api)

Initial release of Transactions Query API
Support for comprehensive filtering (15+ filter types)
Pagination with TransactionConnection response type
Balance snapshots included in transaction records
Requires LIST_PAYMENT and LIST_PURCHASES scopes
Account-level transaction access only

Need help? Contact our developer support team at [email protected] or visit our Developer Portal.

Overview

Quick Start

Basic Query

Query Structure

Parameters

Response Structure

TransactionConnection

Filter Options

TransactionFilterInput

Filter Field Details

Record & Status Filters

recordId

status

Amount Filters

amount, amountGte, amountLte

finalAmount, finalAmountGte, finalAmountLte

Cashback Filters

cashbackAmount, cashbackAmountGte, cashbackAmountLte

cashbackPercentage, cashbackPercentageGte, cashbackPercentageLte

Fee Filters

feeAmount, feeAmountGte, feeAmountLte

Date Filters

createdGte, createdLte

updatedGte, updatedLte

Merchant Filters

merchantId

merchant

Transaction Properties

transactionType

channel

category

Virtual Card Filters

virtualCardProgram

virtualCard

Other Filters

fundingSource

referenceId

liabilityId

Pagination

OffsetInput

Transaction Type

Field Descriptions

Core Transaction Fields

Financial Details

Balance Snapshots

Transaction Details

Merchant Information

Virtual Card Information

Currency Conversion

Metadata

Examples

Example 1: Basic Transaction List

Example 2: Filtered by Date Range

Example 3: Purchases Only with Balances

Example 4: High-Cashback Transactions

Example 5: Amount Range Filter

Example 6: Virtual Card Transactions

Example 7: Pagination Example

Error Handling

Common Errors

Missing or Invalid Token

Insufficient Permissions

Invalid Filter Parameters

Rate Limit Exceeded

Best Practices

1. Use Pagination Effectively

2. Request Only Needed Fields

3. Use Date Filters for Historical Queries

4. Cache Settled Transactions

5. Combine Filters Efficiently

Rate Limits

Code Examples

JavaScript/TypeScript

Python

cURL

FAQ

Q: What's the maximum number of transactions I can retrieve in one request?

Q: How far back does transaction history go?

Q: Are pending transactions included?

Q: What timezone are the timestamps in?

`recordId`

`status`

`amount`, `amountGte`, `amountLte`

`finalAmount`, `finalAmountGte`, `finalAmountLte`

`cashbackAmount`, `cashbackAmountGte`, `cashbackAmountLte`

`cashbackPercentage`, `cashbackPercentageGte`, `cashbackPercentageLte`

`feeAmount`, `feeAmountGte`, `feeAmountLte`

`createdGte`, `createdLte`

`updatedGte`, `updatedLte`

`merchantId`

`merchant`

`transactionType`

`channel`

`category`

`virtualCardProgram`

`virtualCard`

`fundingSource`

`referenceId`

`liabilityId`

Q: What's the difference between `amount` and `finalAmount` filters?