Fluz API Overview
API ReferenceFluz
Start typing to search…

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 {
      record_id
      transaction_type
      amount
      status
      created_at
    }
    totalCount
    hasNextPage
  }
}

With Authentication

curl -X POST https://api.fluz.app/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { getTransactions { transactions { record_id amount transaction_type status created_at } totalCount hasNextPage } }"
  }'

Query Structure

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

Parameters

ParameterTypeRequiredDescription
filterTransactionFilterInputNoFiltering criteria for transactions
paginateOffsetInputNoPagination parameters (default: limit=20, offset=0)

Response Structure

TransactionConnection

type TransactionConnection {
  transactions: [Transaction]
  totalCount: Int!
  hasNextPage: Boolean!
}
FieldTypeDescription
transactions[Transaction]Array of transaction records
totalCountInt!Total count of transactions matching filter (for pagination)
hasNextPageBoolean!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]
  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:

  • GIFT_CARD_PURCHASE - Gift card purchases
  • DEPOSIT - Cash balance deposits
  • WITHDRAWAL - Withdrawals to bank or PayPal
  • TRANSFER - P2P transfers
  • BILL_PAYMENT - Bill payments
  • VIRTUAL_CARD_PURCHASE - Virtual card transactions
  • REFUND - Refunds or returns
  • CASHBACK - Cashback rewards
  • FEE - Service fees
  • ADJUSTMENT - Balance adjustments

Example:

filter: {
  transactionType: ["GIFT_CARD_PURCHASE", "DEPOSIT"]
}
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
}
FieldTypeDefaultMaxDescription
limitInt2020Number of transactions to return per page
offsetInt0-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
  created_at: DateTime
  updated_at: DateTime
}

Field Descriptions

Core Transaction Fields

FieldTypeDescription
record_idUUIDUnique identifier for this transaction record
userStringDisplay name of the user associated with transaction
account_idUUIDAccount that owns this transaction
user_idUUIDUser who initiated the transaction
transaction_typeStringType of transaction (PURCHASE, DEPOSIT, etc.)
amountFloatPrimary transaction amount in USD
sourceStringWhere the funds came from (e.g., "Bank Card ****1234")
destinationStringWhere the funds went (e.g., merchant name)
statusTransactionStatusCurrent status (PENDING or SETTLED)

Financial Details

FieldTypeDescription
external_funding_source_activityFloatChange to external funding sources (bank cards/accounts)
fluz_balance_activityFloatChange to Fluz internal balances
feeFloatFees charged for this transaction
cashbackFloatCashback earned from this transaction
cashback_rateFloatCashback rate percentage
bonus_cashback_rateFloatAdditional bonus cashback rate

Balance Snapshots

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

FieldDescription
cash_balance_available_balanceAvailable cash balance after transaction
cash_balance_total_balanceTotal cash balance after transaction
seat_balance_available_balanceAvailable rewards balance after transaction
seat_balance_total_balanceTotal rewards balance after transaction
gift_card_prepayment_balance_available_balanceAvailable prepayment balance after transaction
gift_card_prepayment_balance_total_balanceTotal prepayment balance after transaction
reserve_balance_available_balanceAvailable reserve balance after transaction
reserve_balance_total_balanceTotal reserve balance after transaction
other_cash_balance_available_balanceOther cash available balance after transaction
other_cash_balance_total_balanceOther cash total balance after transaction

Transaction Details

FieldTypeDescription
reference_idStringExternal reference (e.g., purchase display ID)
descriptionStringHuman-readable description
noteStringAdditional notes
categoryStringTransaction category
card_last_fourStringLast 4 digits of card used (if applicable)
card_display_nameStringDisplay name of payment method

Merchant Information

FieldTypeDescription
merchant_idUUIDMerchant identifier
descriptor_idUUIDTransaction descriptor ID
logo_urlStringURL to merchant/source logo

Virtual Card Information

FieldTypeDescription
virtual_card_programStringVirtual card program (LITHIC, MARQETA, etc.)

Currency Conversion

FieldTypeDescription
original_currency_amountFloatAmount in original currency (for foreign transactions)
original_currency_codeStringOriginal currency code (e.g., "EUR")
conversion_rateFloatExchange rate applied

Metadata

FieldTypeDescription
channelStringPlatform channel (WEB, MOBILE, API)
source_typeStringType of funding source
liability_idUUIDAssociated liability (for bill payments)
transfer_idUUIDAssociated transfer (for P2P)
used_user_cash_balance_idUUIDSpecific cash balance used
is_gift_card_balance_affectedBooleanWhether gift card balance changed
is_cash_balance_affectedBooleanWhether cash balance changed
is_seat_balance_affectedBooleanWhether rewards balance changed
is_reserve_balance_affectedBooleanWhether reserve balance changed
created_atDateTimeWhen transaction was created
updated_atDateTimeWhen 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

ResourceLimitWindow
Queries per user1001 minute
Queries per IP3001 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?

A:

  • 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

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.

Updated about 6 hours ago