Introduction to Transactions

Retrieve up to 24 months of transaction data and stay up-to-date with webhooks.

Link an account

Fetch transactions

Show transactions

Transactions data can be useful for many different applications, including personal finance management, expense reporting, cash flow modeling, risk analysis, and more. Plaid's Transactions product allows you to access a user's transaction history for depository type accounts such as checking and savings accounts, credit type accounts such as credit cards, and student loan accounts. For transaction history from investment accounts, use Plaid's Investments product.

Transactions data available via /transactions/sync includes transaction date, amount, category, merchant, location, and more. Transaction data is lightly cleaned to populate the name field, and more thoroughly processed to populate the merchant_name field. For example data, see the Transactions API reference.

Below are typical fill rates for selected fields returned by Transactions. Not all fields are included in the table below.

*Denominator excludes transactions that do not have an associated merchant, such as cash transactions, direct deposits, or bank fees.

The steps below show an overview of how to integrate Transactions. For a detailed, step-by-step view, you can also watch our full-length, comprehensive tutorial walkthrough.

1. Call /link/token/create. Along with any other parameters you specify, make sure to include the following:

   • The products array should include transactions.
   • Specify a webhook to receive transactions updates.
   • Specify a value for transactions.days_requested corresponding to the amount of transaction history your integration needs. The more transaction history is requested, the longer the historical update poll will take. The default value is 90; the maximum value is 730.

2. On the client side, create an instance of Link using the link_token returned by /link/token/create; for more details, see the Link documentation.

3. Once the end user has completed the Link flow, exchange the public_token for an access_token by calling /item/public_token/exchange.

4. Create a method to call /transactions/sync. This method must do the following:

   • The first time /transactions/sync is called on an Item, call /transactions/sync with no cursor value specified
   • Save the next_cursor value returned by /transactions/sync to use as an input parameter in the next call to /transactions/sync
   • If has_more in the /transactions/sync response is true, handle paginated results by temporarily preserving the current cursor, then calling /transactions/sync with the newly returned cursor. After each /transactions/sync call, call /transactions/sync with the newly returned cursor from the previous /transactions/sync call until has_more is false.
   • When handling paginated results, if TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error is returned during pagination, restart the process in the previous bullet with the old cursor that was temporarily preserved. Once has_more is false, it is safe to stop preserving the old cursor.

   For an example, see fetchNewSyncData and syncTransactions.

5. Call the /transactions/sync wrapper you created in the previous step, passing in the access_token, in order to activate the Item for the SYNC_UPDATES_AVAILABLE webhook. It is common that no transactions will be returned during this first call, as it takes Plaid some time to fetch initial transactions.

6. (Optional) Wait for the SYNC_UPDATES_AVAILABLE webhook to fire with the initial_update_complete field set to true and the historical_update_complete set to false. When this occurs, you may optionally call your /transactions/sync wrapper to obtain the most recent 30 days of data. If your end-user is expecting to see data load into your app in real-time, this can help improve the responsiveness of your app.

7. Wait for the SYNC_UPDATES_AVAILABLE webhook to fire with the historical_update_complete field set to true. Once it does, call your /transactions/sync wrapper to obtain all available updates.

8. From this point forward, Plaid will periodically check for transactions data for your Item. When it detects that new transactions data is available, the SYNC_UPDATES_AVAILABLE webhook will fire again. When it does, call your /transactions/sync wrapper to receive all updates since the next_cursor value. In addition to added transactions, these subsequent updates may also include removed or modified transactions. For details, see Transactions updates.

9. (Optional) If you would like to check for updates more frequently than Plaid's default schedule, call /transactions/refresh to force an on-demand update. If any new transaction data is available, a SYNC_UPDATES_AVAILABLE webhook will fire.

Transactions data is not static. As time passes, your users will make new transactions, and transactions they made in the past will change as they are processed by the financial institution. To learn more about how transactions are processed and can change, see Transaction states.

Plaid checks for updated transactions regularly, and uses webhooks to notify you of any changes so you can keep your app up to date. For more detail on how to listen and respond to transaction update webhooks, see Transaction webhooks.

The frequency of transactions update checks is typically one or more times a day. The exact frequency will depend on the institution. To learn when an Item was last checked for updates, you can view the Item in the Item Debugger. If you would like to display this information in your app's UI to help users understand the freshness of their data, it can also be retrieved via API, using the /item/get endpoint.

You can also request an update on-demand via the /transactions/refresh endpoint, which is available as an add-on for Transactions customers. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

If your app involves personal financial management functionality, you may want to view a summary of a user's inflows and outflows. The /transactions/recurring/get endpoint provides a summary of the recurring outflow and inflow streams and includes insights about each recurring stream including the category, merchant, last amount, and more. /transactions/recurring/get is available as an add-on for Transactions customers in the US, Canada, and UK. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

The Transactions sample app is a simple app designed to accompany the Transactions YouTube tutorial.

Try out the Pattern Demo for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case to calculate and display a customer's net worth and spending habits and allows them to link multiple financial institutions.

For a more robust example of an app that incorporates transactions, along with sample code for transactions reconciliation, see the Node-based Plaid Pattern sample app.

If you've already built an app using Plaid's /transactions/get endpoint, see the Transactions Sync migration guide to learn about Plaid's latest Transactions endpoint and how to simplify your integration by migrating to /transactions/sync.

For Sandbox transactions testing, it is recommended to use the special user_transactions_dynamic user (password: any non-blank password), instead of the standard user_good test user. You can create a public token for this user using /sandbox/public_token/create; if using the interactive Link flow, you must use a non-OAuth test institution such as First Platypus Bank (ins_109508). Unlike user_good, user_transactions_dynamic contains realistic, dynamic transactions data and can be used together with the /transactions/refresh endpoint to simulate Transactions updates and trigger webhooks in Sandbox. For more details on how to simulate transaction activity with this user, see Testing pending and posted transactions. If you are using the optional Recurring Transactions add-on, you can also use the user_transactions_dynamic user to test Recurring Transactions in Sandbox. This user has six months of recurring transactions.

Additionally, you may add your own custom transactions with /sandbox/transactions/create under the user_transactions_dynamic user. This simulates a /transactions/refresh call where Plaid will see those custom transactions as new transactions. All correponding webhooks will fire.

Transactions and the optional Recurring Transactions add-on are billed on a subscription model. The optional Transactions Refresh add-on is billed on a per-request model. To view the exact pricing you may be eligible for, apply for Production access or contact Sales. For more details about pricing and billing models, see Plaid billing.

To get started building with Transactions, see Add Transactions to your App.

If you're ready to launch to Production, see the Launch Center.