> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Transactions

> Query and filter payment history with powerful filtering and pagination options

export const FeatureCardGrid = ({cols = 3, children}) => <div className={`not-prose feature-cards-grid feature-cards-cols-${cols}`}>
    {children}
  </div>;

export const FeatureCard = ({icon, title, children, href, linkHref, linkText, color, tag, tagPosition, layout, variant, iconSize}) => {
  const isHorizontal = layout === 'horizontal';
  const isFlat = variant === 'flat';
  const isLargeIcon = iconSize === 'lg';
  const isInlineTag = tagPosition === 'inline';
  const card = <div className={`feature-card ${href ? 'feature-card-link' : ''} ${!icon ? 'feature-card-no-icon' : ''} ${isHorizontal ? 'feature-card-horizontal' : ''} ${isFlat ? 'feature-card-flat' : ''} ${isLargeIcon ? 'feature-card-icon-lg' : ''}`}>
      {icon && <div className="feature-card-icon-wrapper">
          {color ? <div className="feature-card-icon" style={{
    WebkitMaskImage: `url(${icon})`,
    maskImage: `url(${icon})`,
    backgroundColor: color,
    width: '24px',
    height: '24px',
    WebkitMaskSize: 'contain',
    maskSize: 'contain',
    WebkitMaskRepeat: 'no-repeat',
    maskRepeat: 'no-repeat'
  }} /> : <img src={icon} alt="" className="feature-card-icon" />}
        </div>}
      <div className="feature-card-content">
        {isInlineTag ? <div className="feature-card-title-row">
            <span className="feature-card-title">{title}</span>
            {tag && <span className="feature-card-tag">{tag}</span>}
          </div> : <div className="feature-card-title">{title}</div>}
        <div className="feature-card-desc">{children}</div>
        {tag && !isInlineTag && <div className="feature-card-tag-row"><span className="feature-card-tag">{tag}</span></div>}
        {linkText && <div className="feature-card-link-row">
            {linkHref ? <a href={linkHref} className="feature-card-text-link" style={{
    color: color
  }}>
                {linkText}
              </a> : <span className="feature-card-text-link feature-card-coming-soon" style={{
    color: color,
    opacity: 0.6
  }}>
                {linkText}
              </span>}
          </div>}
      </div>
    </div>;
  return href ? <a href={href} className="feature-card-anchor">{card}</a> : card;
};

Retrieve transaction history with flexible filtering options. Transactions are returned in descending order (most recent first) with a default limit of 20 per page.

```bash cURL theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

{
  "data": [
    {
      "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
      "status": "COMPLETED",
      "type": "OUTGOING",
      "source": {
        "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "currency": "USD"
      },
      "destination": {
        "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
        "currency": "EUR"
      },
      "sentAmount": {
        "amount": 10000,
        "currency": {
          "code": "USD",
          "symbol": "$",
          "decimals": 2
        }
      },
      "receivedAmount": {
        "amount": 9200,
        "currency": {
          "code": "EUR",
          "symbol": "€",
          "decimals": 2
        }
      },
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "platformCustomerId": "customer_12345",
      "description": "Payment for services - Invoice #1234",
      "exchangeRate": 0.92,
      "settledAt": "2025-10-03T15:30:00Z",
      "createdAt": "2025-10-03T15:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6IlRyYW5zYWN0aW9uOjAxOTU0MmY1LWIzZTctMWQwMi0wMDAwLTAwMDAwMDAwMDAzMCJ9",
  "totalCount": 45
}
```

## Filtering transactions

Use query parameters to filter and narrow down transaction results.

### Filter by customer

Get all transactions for a specific customer:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

Or use your platform's customer ID:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=customer_12345' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

### Filter by transaction type

Get only incoming or outgoing transactions:

<Tabs>
  <Tab title="Outgoing Only">
    ```bash theme={null}
    curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=OUTGOING' \
      -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
    ```
  </Tab>

  <Tab title="Incoming Only">
    ```bash theme={null}
    curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=INCOMING' \
      -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
    ```
  </Tab>
</Tabs>

### Filter by status

Get transactions in a specific status:

```bash theme={null}
# Get all pending transactions
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=PENDING' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Get all completed transactions
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=COMPLETED' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

**Available statuses:**

* `PENDING` - Transaction initiated, awaiting processing
* `PROCESSING` - Transaction in progress
* `COMPLETED` - Transaction successfully completed
* `FAILED` - Transaction failed
* `EXPIRED` - Quote expired before execution

### Filter by date range

Get transactions within a specific date range:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

<Tip>Dates must be in ISO 8601 format (e.g., `2025-10-03T15:00:00Z`).</Tip>

### Filter by account

Get transactions for a specific account:

```bash theme={null}
# Any transactions involving this account (sent or received)
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?accountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Only transactions sent FROM this account
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?senderAccountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'

# Only transactions sent TO this account
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?receiverAccountIdentifier=ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

## Combining filters

You can combine multiple filters to narrow down results:

```bash theme={null}
# Get completed outgoing transactions for a customer in October 2025
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&type=OUTGOING&status=COMPLETED&startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

## Pagination

Handle large result sets with cursor-based pagination:

<Steps>
  <Step title="Get first page">
    ```bash theme={null}
    curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20' \
      -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
    ```

    Response:

    ```json theme={null}
    {
      "data": [
        /* 20 transactions */
      ],
      "hasMore": true,
      "nextCursor": "eyJpZCI6IlRyYW5z...",
      "totalCount": 150
    }
    ```
  </Step>

  <Step title="Get next page">
    Use the `nextCursor` from the previous response:

    ```bash theme={null}
    curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20&cursor=eyJpZCI6IlRyYW5z...' \
      -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
    ```
  </Step>

  <Step title="Continue until done">
    Keep paginating while `hasMore` is `true`:

    ```javascript theme={null}
    async function getAllTransactions() {
      const allTransactions = [];
      let cursor = null;
      let hasMore = true;

      while (hasMore) {
        const url = cursor
          ? `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100&cursor=${cursor}`
          : `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100`;

        const response = await fetch(url, {
          headers: { Authorization: `Basic ${credentials}` },
        });

        const { data, hasMore: more, nextCursor } = await response.json();

        allTransactions.push(...data);
        hasMore = more;
        cursor = nextCursor;
      }

      return allTransactions;
    }
    ```
  </Step>
</Steps>

<Info>The maximum `limit` is 100 transactions per request. Default is 20.</Info>

## Get a single transaction

Retrieve details for a specific transaction by ID:

```bash theme={null}
curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000030' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET'
```

## Best practices

<AccordionGroup>
  <Accordion title="Use pagination for large datasets">
    Always implement pagination when fetching transactions to avoid timeouts and memory issues:

    ```javascript theme={null}
    // Good: Paginated approach
    async function fetchWithPagination(filters) {
      const transactions = [];
      let cursor = null;

      do {
        const page = await fetchTransactionPage(filters, cursor);
        transactions.push(...page.data);
        cursor = page.nextCursor;
      } while (cursor);

      return transactions;
    }

    // Bad: Trying to fetch everything at once
    async function fetchAll() {
      const response = await fetch("/transactions?limit=10000"); // Don't do this!
      return response.json();
    }
    ```
  </Accordion>

  <Accordion title="Cache results when appropriate">
    For data that doesn't change frequently (like completed transactions), implement caching:

    ```javascript theme={null}
    const cache = new Map();

    async function getCompletedTransactions(customerId, month) {
      const cacheKey = `${customerId}-${month}`;

      if (cache.has(cacheKey)) {
        return cache.get(cacheKey);
      }

      const transactions = await fetchMonthlyTransactions(customerId, month);
      cache.set(cacheKey, transactions);

      return transactions;
    }
    ```
  </Accordion>

  <Accordion title="Use specific filters to reduce result sets">
    Apply filters to get only the data you need:

    ```javascript theme={null}
    // Good: Specific filters
    const recentFailed = await fetch(
      "/transactions?status=FAILED&startDate=2025-10-01T00:00:00Z&type=OUTGOING"
    );

    // Bad: Fetch everything and filter in code
    const all = await fetch("/transactions");
    const filtered = all.data.filter(
      (tx) =>
        tx.status === "FAILED" &&
        tx.type === "OUTGOING" &&
        new Date(tx.createdAt) > new Date("2025-10-01")
    );
    ```
  </Accordion>

  <Accordion title="Handle rate limits gracefully">
    Implement exponential backoff for rate limit errors:

    ```javascript theme={null}
    async function fetchWithRetry(url, retries = 3) {
      for (let i = 0; i < retries; i++) {
        const response = await fetch(url, {
          headers: { Authorization: `Basic ${credentials}` },
        });

        if (response.status === 429) {
          const retryAfter = parseInt(
            response.headers.get("Retry-After") || "1",
            10
          );
          await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
          continue;
        }

        return response.json();
      }

      throw new Error("Max retries exceeded");
    }
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<FeatureCardGrid cols={2}>
  <FeatureCard icon="/images/icons/paper-plane-top-right.svg" title="Send Payments" href="/payouts-and-b2b/payment-flow/send-payment">
    Learn how to send payments from internal accounts
  </FeatureCard>

  <FeatureCard icon="/images/icons/receipt-check.svg" title="Reconciliation" href="/payouts-and-b2b/payment-flow/reconciliation">
    Match payments with your internal accounting systems
  </FeatureCard>

  <FeatureCard icon="/images/icons/square-info.svg" title="Error Handling" href="/payouts-and-b2b/payment-flow/error-handling">
    Handle transaction failures and errors
  </FeatureCard>
</FeatureCardGrid>