Get incremental transaction updates on a processor token
POST /processor/transactions/sync
The /processor/transactions/sync endpoint retrieves transactions associated with an Item and can fetch updates using a cursor to track which updates have already been seen.
For important instructions on integrating with /processor/transactions/sync, see the Transactions integration overview. If you are migrating from an existing integration using /processor/transactions/get, see the Transactions Sync migration guide.
This endpoint supports credit, depository, and some loan-type accounts (only those with account subtype student). For investments accounts, use /investments/transactions/get instead.
When retrieving paginated updates, track both the next_cursor from the latest response and the original cursor from the first call in which has_more was true; if a call to /processor/transactions/sync fails when retrieving a paginated update (e.g due to the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error), the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.
If transactions data is not yet available for the Item, which can happen if the Item was not initialized with transactions during the /link/token/create call or if /processor/transactions/sync was called within a few seconds of Item creation, /processor/transactions/sync will return empty transactions arrays.
Plaid typically checks for new transactions data between one and four times per day, depending on the institution. To find out when transactions were last updated for an Item, use the Item Debugger or call /item/get; the item.status.transactions.last_successful_update field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the /processor/transactions/refresh endpoint.
To be alerted when new transactions are available, listen for the SYNC_UPDATES_AVAILABLE webhook.
To receive Transactions webhooks for a processor token, set its webhook URL via the /processor/token/webhook/update endpoint.
Request Body
Required
ProcessorTransactionsSyncRequest defines the request schema for /processor/transactions/sync
Parameters
client_id
client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
processor_token
processor-<environment>-<identifier>
secret
secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
cursor
count
options
options must not be null.
include_original_description
include_personal_finance_category
include_logo_and_counterparty_beta
personal_finance_category_version
v1 taxonomy and may request v2 by explicitly setting this field to v2.
If you enabled any Financial Insights products on or after October 2025 you may only receive v2 taxonomy.
days_requested
transactions in the products, required_if_supported_products, or optional_products array when calling /link/token/create or by making a previous call to /transactions/sync or /transactions/get). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default.
If you are initializing your Items with transactions during the /link/token/create call (e.g. by including transactions in the /link/token/create products array), you must use the transactions.days_requested field in the /link/token/create request instead of in the /transactions/sync request.
If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via /item/remove and send the user through Link to create a new Item.
Customers using Recurring Transactions should request at least 180 days of history for optimal results.
account_id
account_id returns updates for all accounts under the Item. Note that specifying an account_id effectively creates a separate incremental update stream—and therefore a separate cursor—for that account. If multiple accounts are queried this way, you will maintain multiple cursors, one per account_id.
If you decide to begin filtering by account_id after using no account_id, start fresh with a null cursor and maintain separate (account_id, cursor) pairs going forward. Do not reuse any previously saved cursors, as this can cause pagination errors or incomplete data.
Note: An error will be returned if a provided account_id is not associated with the Item.
Response
ProcessorTransactionsSyncResponse defines the response schema for /processor/transactions/sync
Response Properties
transactions_update_status
TRANSACTIONS_UPDATE_STATUS_UNKNOWN: Unable to fetch transactions update status for Item.
NOT_READY: The Item is pending transaction pull.
INITIAL_UPDATE_COMPLETE: Initial pull for the Item is complete, historical pull is pending.
HISTORICAL_UPDATE_COMPLETE: Both initial and historical pull for Item are complete.
account
added
cursor ordered by ascending last modified time.
modified
cursor ordered by ascending last modified time.
removed
cursor ordered by ascending last modified time.
transaction_id
account_id
next_cursor
has_more being false) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string.
has_more
cursor set to next_cursor. If has_more is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.
request_id