Available in other SDKs

`usePaymentAttempts()`

Warning

This API is experimental and subject to change while Clerk Billing is under Beta. To mitigate potential disruptions, we recommend pinning your SDK and clerk-js package versions.

The usePaymentAttempts() hook provides access to the payment attempts associated with a user or organization. It returns a paginated list of payment attempts and includes methods for managing them.

Parameters

usePaymentAttempts() accepts a single object with the following properties:

Name
for?
Type
'user' | 'organization'
Description
Specifies whether to fetch payment attempts for the current user or organization. Defaults to 'user'.
Name
pageSize?
Type
number
Description
The number of payment attempts to fetch per page. Defaults to 10.
Name
initialPage?
Type
number
Description
The page number to start fetching from. Defaults to 1.
Name
infinite?
Type
boolean
Description
When true, enables infinite pagination mode where new pages are appended to existing data. When false, each page replaces the previous data. Defaults to false.
Name
keepPreviousData?
Type
boolean
Description
When true, the previous data will be kept while loading the next page. This helps prevent layout shifts. Defaults to false.

Returns

usePaymentAttempts() returns an object with the following properties:

Name
data
Type
[] | null
Description
An array of payment attempts, or null if the data hasn't been loaded yet.
Name
isLoading
Type
boolean
Description
A boolean that is true if there is an ongoing request and there is no fetched data.
Name
isFetching
Type
boolean
Description
A boolean that is true if there is an ongoing request or a revalidation.
Name
hasNextPage
Type
boolean
Description
A boolean that indicates if there are available pages to be fetched.
Name
hasPreviousPage
Type
boolean
Description
A boolean that indicates if there are available pages to be fetched.
Name
fetchNext
Type
() => void
Description
A function that triggers the next page to be loaded. This is the same as fetchPage(page => Math.min(pageCount, page + 1)).
Name
fetchPrevious
Type
() => void
Description
A function that triggers the previous page to be loaded. This is the same as fetchPage(page => Math.max(0, page - 1)).
Name
pageCount
Type
number
Description
The total amount of pages. It is calculated based on count, initialPage, and pageSize.
Name
count
Type
number
Description
The total number of payment attempts available.
Name
error
Type
| null
Description
Returns an error object if any part of the process fails.
Name
fetchPage
Type
(page: number) => void
Description
A function that triggers a specific page to be loaded.
Name
isError
Type
boolean
Description
A boolean that indicates the request failed.
Name
page
Type
number
Description
The current page.
Name
revalidate
Type
() => Promise<void>
Description
A function that triggers a revalidation of the current page.
Name
setData
Type
(data: any[]) => void
Description
A function that allows you to set the data manually.

Examples

Basic usage

The following example demonstrates how to fetch and display a user's payment attempts.

import { usePaymentAttempts } from '@clerk/nextjs/experimental'

function PaymentAttemptsList() {
  const { data, isLoading } = usePaymentAttempts({
    for: 'user',
    pageSize: 10,
  })

  if (isLoading) {
    return <div>Loading payment attempts...</div>
  }

  if (!data || data.length === 0) {
    return <div>No payment attempts found.</div>
  }

  return (
    <ul>
      {data?.map((attempt) => (
        <li key={attempt.id}>
          Payment #{attempt.id} - {attempt.status}
          <br />
          Amount: {attempt.amount.amountFormatted} on {new Date(attempt.updatedAt).toLocaleString()}
        </li>
      ))}
    </ul>
  )
}

Infinite pagination

The following example demonstrates how to implement infinite scrolling with payment attempts.

import { usePaymentAttempts } from '@clerk/nextjs/experimental'

function InfinitePaymentAttempts() {
  const { data, isLoading, hasNextPage, fetchNext } = usePaymentAttempts({
    for: 'user',
    infinite: true,
    pageSize: 20,
  })

  if (isLoading) {
    return <div>Loading...</div>
  }

  if (!data || data.length === 0) {
    return <div>No payment attempts found.</div>
  }

  return (
    <div>
      <ul>
        {data?.map((attempt) => (
          <li key={attempt.id}>
            Payment attempt for {attempt.amount.amountFormatted}
            <br />
            Status: {attempt.status}
            <br />
            {attempt.status === 'failed' && attempt.failedAt && (
              <span>Failed At: {new Date(attempt.failedAt).toLocaleString()}</span>
            )}
          </li>
        ))}
      </ul>

      {hasNextPage && <button onClick={() => fetchNext()}>Load more payment attempts</button>}
    </div>
  )
}

Payment attempts history table

The following example demonstrates how to use usePaymentAttempts() to display a detailed payment history table.

import { usePaymentAttempts } from '@clerk/nextjs/experimental'

function PaymentAttemptsHistory() {
  const { data, isLoading } = usePaymentAttempts({ for: 'user' })

  if (isLoading) {
    return <div>Loading payment attempts...</div>
  }

  if (!data || data.length === 0) {
    return <div>No payment attempts found.</div>
  }

  const getStatusColor = (status: string) => {
    switch (status) {
      case 'paid':
        return 'green'
      case 'failed':
        return 'red'
      case 'pending':
        return 'orange'
      default:
        return 'gray'
    }
  }

  return (
    <table>
      <thead>
        <tr>
          <th>Payment ID</th>
          <th>Amount</th>
          <th>Status</th>
          <th>Date</th>
          <th>Payment Method</th>
        </tr>
      </thead>
      <tbody>
        {data?.map((attempt) => (
          <tr key={attempt.id}>
            <td>{attempt.id}</td>
            <td>{attempt.amount.amountFormatted}</td>
            <td style={{ color: getStatusColor(attempt.status) }}>{attempt.status}</td>
            <td>{attempt.paidAt ? new Date(attempt.paidAt).toLocaleDateString() : '-'}</td>
            <td>
              {attempt.paymentSource.cardType} ****{attempt.paymentSource.last4}
            </td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}

Edit this page on GitHub

Last updated on Aug 19, 2025

usePaymentAttempts()