Investments async update migration guide
Learn how to migrate to asynchronous updates for investment transactions
Overview
Plaid supports asynchronous updates for Investments, which reduce the time users spend waiting in Link. With asynchronous updates, Plaid fetches the last 30 days of investment transactions during Link. After Link, Plaid fetches the rest of the history (up to 24 months) in the background, usually within a few minutes, and fires the INVESTMENTS_TRANSACTIONS: HISTORICAL_UPDATE webhook when the full history is ready. Holdings are still fetched during Link, so /investments/holdings/get is not affected.
Asynchronous updates are on by default for Plaid teams created on or after November 18, 2026. If your Plaid team was created before that date, Plaid keeps fetching up to 24 months of investment transactions during Link until you opt in by setting investments.async_update. There is currently no deadline to opt in.
This guide explains how to update an existing Investments integration to use asynchronous updates. It also covers changes for Items with Investments in required_if_supported_products or optional_products, which apply to all Plaid teams.
New Plaid teams
Plaid teams created on or after November 18, 2026 always use asynchronous updates, so they don't need to opt in and investments.async_update is ignored. This also applies when you add Investments to an Item after Link: /investments/transactions/get returns a PRODUCT_NOT_READY error until the history is ready, regardless of options.async_update, and Plaid fires HISTORICAL_UPDATE when it is. If you're creating a new Plaid team for an existing integration that relies on having the full history when Link ends, contact your account manager to request synchronous updates for the new team.
Changes for all Plaid teams
Beginning November 18, 2026, the following changes apply to all Plaid Items, whether or not you set investments.async_update:
- For Items with Investments in
required_if_supported_products, Plaid fetches 30 days of investment transactions history synchronously during the Link session, then fetches the rest of the history (up to 24 months) shortly after Link and firesHISTORICAL_UPDATEwhen the full history is ready. - For Items with Investments in
optional_products, Plaid already fetches investment transaction history after Link, and that doesn't change. When that first fetch finishes, Plaid now firesHISTORICAL_UPDATEin place ofINVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE. Scheduled updates fireDEFAULT_UPDATEas before.
If you use either array, see Update webhook handlers.
Update your client library
If you are using client libraries, you may need to update your current library to set investments.async_update. The following are the minimum Plaid client library versions required to support investments.async_update for each language:
- Python: 47.0.0
- Node: 50.0.0
- Ruby: 54.0.0
- Java: 48.0.0
- Go: 50.0.0
Detailed upgrade notes are language-specific and may be found in the README and Changelog of the specific library. See the library's repo on the Plaid GitHub for more information.
Update webhook handlers
When the full history is available, Plaid fires the INVESTMENTS_TRANSACTIONS: HISTORICAL_UPDATE webhook. When you receive it, call /investments/transactions/get for the full date range you need, paginating through all results.
app.post('/server/receive_webhook', async (req, res, next) => {
const { webhook_type, webhook_code, item_id } = req.body;
const isInvestmentsHistoricalUpdate =
webhook_type === 'INVESTMENTS_TRANSACTIONS' &&
webhook_code === 'HISTORICAL_UPDATE';
if (isInvestmentsHistoricalUpdate) {
// Look up the access_token for item_id, then call
// /investments/transactions/get and paginate through all results.
}
// Handle other types of webhooks
});The webhook fires even if Plaid didn't find any older investment transactions. If Plaid finishes fetching the history before you call /item/public_token/exchange, the webhook fires after the exchange. If the Item's holdings changed, Plaid also fires HOLDINGS: DEFAULT_UPDATE.
Plaid sends webhooks to the URL you provide in the webhook field when calling /link/token/create. To receive HISTORICAL_UPDATE, set this field.
Update logic that runs after Link
Until HISTORICAL_UPDATE fires, /investments/transactions/get returns only the investment transactions fetched during Link, even if you request an earlier start_date. It does not return a PRODUCT_NOT_READY error in this case.
For example, you can show the user their last 30 days of investment transactions right after Link, then load the rest when the webhook fires. Responses after the webhook also include the investment transactions you already fetched, so use investment_transaction_id to skip ones you already have.
Opt in when creating a Link token
To opt in, set investments.async_update to true when calling /link/token/create. The field applies only when investments is in the products array. If you omit the field or set it to false, Plaid keeps fetching up to 24 months of investment transactions before the Link session ends.
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
"client_id": "${PLAID_CLIENT_ID}",
"secret": "${PLAID_SECRET}",
"client_name": "Plaid Test App",
"user_id": "${PLAID_USER_ID}",
"products": ["investments"],
"country_codes": ["US"],
"language": "en",
"webhook": "https://webhook.example.com",
"investments": {
"async_update": true
}
}'The setting applies only to Items created with that Link token.
Opting in doesn't affect existing Items or their history, and Plaid doesn't send HISTORICAL_UPDATE for them.
Test your integration
To test your webhook handler, call /sandbox/item/fire_webhook with INVESTMENTS_TRANSACTIONS as the webhook_type and HISTORICAL_UPDATE as the webhook_code. The webhook reports 0 new and 0 canceled investment transactions.
Sandbox Items created through Link follow the same rules as in Production. For example, if you set investments.async_update to true, Plaid fetches the last 30 days of investment transactions during Link and fires HISTORICAL_UPDATE after fetching the rest. Items created with /sandbox/public_token/create have their full history available as soon as they're created.
