Other Guides
Services
About
Plugins
Plaid Item Errors
For almost all use cases (payments-only use cases being the exception), you will want to remain connected to your user's bank account to obtain updated data over time. In this guide, we show you how to handle authentication and other lifecycle scenarios that can occur throughout the life of a connected account.
Implementing these steps is CRITICAL for any application that wishes to remain connected to user's financial institution accounts over a longer period of time.
Implementing these steps is CRITICAL for any application that wishes to remain connected to user's financial institution accounts over a longer period of time.
Before You Begin
Free Video Tutorial - Item Errors
Update Webhooks
On the Plaid Link page, you set up a basic webhook in your Bubble app. Now, you need to add additional functionality to this webhook to handle all Plaid use cases.
The below JSON snipped will be used to add the whole set of potential fields Plaid will send to your app's webhook. Not all of these fields are covered in this guide, and are instead covered in the product-specific page.
The below JSON snipped will be used to add the whole set of potential fields Plaid will send to your app's webhook. Not all of these fields are covered in this guide, and are instead covered in the product-specific page.
{
"webhook_type": "ITEM",
"webhook_code": "ERROR",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"consent_expiration_time": "2020-01-15T13:25:17.766Z",
"new_webhook_url": "https://plaid.com/example/webhook",
"new_transactions": 19,
"removed_transactions": [
"yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
"kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
],
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
"new_holdings": 19,
"updated_holdings": 0,
"new_investments_transactions": 16,
"canceled_investments_transactions": 0,
"account_ids_with_new_liabilities": [
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
"BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
],
"account_ids_with_updated_liabilities": {
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
"past_amount_due"
]
},
"payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
"new_payment_status": "PAYMENT_STATUS_INITIATED",
"old_payment_status": "PAYMENT_STATUS_PROCESSING",
"original_reference": "Account Funding 99744",
"adjusted_reference": "Account Funding 99",
"original_start_date": "2017-09-14",
"adjusted_start_date": "2017-09-15",
"timestamp": "2017-09-14T14:42:19.350Z",
"income_verification_id": "f6f5132f-853b-421c-8c41-d24f93ebc39f",
"verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE",
"state": "completed",
"deposit_switch_id": "f6f5132f-853b-421c-8c41-d24f93ebc39f",
"error": {
"display_message": "User Friendly Messa",
"error_code": "ITEM_LOGIN_REQUIRED",
"error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state",
"error_type": "ITEM_ERROR"
}
}
For readability, the below JSON is annotated with a brief explanation of what each field is.
{
"webhook_type": "ITEM", // Comnmon to all webhooks - tells you what Product is involved. Can be "ITEM", "TRANSACTIONS", "AUTH", "ASSETS", "HOLDINGS", "INVESTMENTS_TRANSACTIONS", "LIABILITIES", "PAYMENT_INITIATION", "BANK_TRANSFERS", "INCOME", "DEPOSIT_SWITCH"
"webhook_code": "ERROR", // Common to all webhooks
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", // Used in all except Assets, Incomes, and Deposit Switch webhooks. Helps you figure out what Item (Institution) the webhook applies to
"consent_expiration_time": "2020-01-15T13:25:17.766Z", // Item Error type webhooks, warning up upcoming expiration
"new_webhook_url": "https://plaid.com/example/webhook", // Only used for confirmation that a webhook update was completed; is sent to the new webhook URL
"new_transactions": 19, // Transactions product only
"removed_transactions": [
"yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
"kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
], // Transactions product only to handle cases like Pending to Finalized transactions
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", // Auth product when micro-deposits are used for verification or when micro deposit verification times out
"asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05", // Assets product. No item_id will be included. Use this id to identify the institution you requested an asset report for - this will match the id returned at report creation.
"new_holdings": 19, // Investments product
"updated_holdings": 0, // Investments product
"new_investments_transactions": 16, // Investments Product
"canceled_investments_transactions": 0, // Investments product
"account_ids_with_new_liabilities": [
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
"BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
], // Accounts with new liabilities/lines of credit/etc. Use to get Loan and Credit Details for this account.
"account_ids_with_updated_liabilities": {
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
"past_amount_due"
]
}, // tells you what fields changed in an existing account_id; use this, for instance, to keep your database in sync with Plaid data.
"payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2", // Payment Initiation
"new_payment_status": "PAYMENT_STATUS_INITIATED", // Payment Initiation
"old_payment_status": "PAYMENT_STATUS_PROCESSING", // Payment Initiation
"original_reference": "Account Funding 99744", // Payment Initiation
"adjusted_reference": "Account Funding 99", // Payment Initiation
"original_start_date": "2017-09-14", // Payment Initiation
"adjusted_start_date": "2017-09-15", // Payment Initiation
"timestamp": "2017-09-14T14:42:19.350Z", // Payment Initiation
"income_verification_id": "f6f5132f-853b-421c-8c41-d24f93ebc39f", //Income Verification Product
"verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE", //Income Verification Product
"state": "completed", // Deposit Switch Product
"deposit_switch_id": "f6f5132f-853b-421c-8c41-d24f93ebc39f", // Deposit Switch Product
"error": {
"display_message": null, // If included, will be a user-friendly representation of the message. Do not use for programatic use/logic.
"error_code": "ITEM_LOGIN_REQUIRED", // Safe for programatic use/logic. See Plaid Docs for full set of possible values.
"error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state", // Developer friendly message about the error. Do not use for programatic use/logic.
"error_type": "ITEM_ERROR", // See Plaid Webhook docs for full set of possible values. This field is safe to set up logic based upon.
"status": 400 // You can probably ignore this field - very narrow use case that's handled better elsewhere.
} // Included whenever the webhook_code is 'ERROR', primarily Item Errors and Assets product.
}
Step 1
First, we want to update the backend workflow to expect all possible fields that Plaid may send.
To do so, open the backend workflow and select Modify Types.
To do so, open the backend workflow and select Modify Types.
Item Errors
On occasion, banks will require your user to re-authenticate for your app to continue receiving data about their account. In these cases, Plaid sends an Item Error webhook to your app.
Step 1
Next, set up a new database trigger that will run when your app is notified by Plaid that an Item needs to be updated.
To do so, create a new database trigger using the Plaid Webhooks type. Set it to run only when the type is ITEM and the code is ERROR.
You may also want to handle two other types of webhooks at this point y creating their own triggers. One is type ITEM and code USER_PERMISSION_REVOKED, which indicates that you should remove the item from your database. The other is type ITEM and code PENDING_EXPIRATION which indicates that an ERROR will be sent in the coming days; you can handle these the same as ERROR webhook types, as your user will need to re-authenticate.
To do so, create a new database trigger using the Plaid Webhooks type. Set it to run only when the type is ITEM and the code is ERROR.
You may also want to handle two other types of webhooks at this point y creating their own triggers. One is type ITEM and code USER_PERMISSION_REVOKED, which indicates that you should remove the item from your database. The other is type ITEM and code PENDING_EXPIRATION which indicates that an ERROR will be sent in the coming days; you can handle these the same as ERROR webhook types, as your user will need to re-authenticate.
Plaid Link Update Mode
To resolve an Item Error, your user must complete authentication via Plaid Link's "Update" mode.
Step 1
The first step to setting up Update Mode is creating a Link Token specifically for Update mode. Importantly, the Institution that you are trying to update will need to be known for this step.
In this screenshot, we create a new Custom Event in the Plaid Actions reusable element (see the video lessons for more about setting up this reusable element). This Custom Event is of a type Plaid Institution, which will enable us to use that institution for steps within the custom event.
In this screenshot, we create a new Custom Event in the Plaid Actions reusable element (see the video lessons for more about setting up this reusable element). This Custom Event is of a type Plaid Institution, which will enable us to use that institution for steps within the custom event.
Remove Items from Billing
Finally, you may want to setup a workflow that tells Plaid when you want to remove an item. For instance, when a user deletes an item or deletes their account. If you don't remove an item, you will continue to be billed for it by Plaid.
Step 1
To remove an institution, simply trigger the Item - Remove (Stops Billing) action with the access token of the Institution you wish to remove. After this action runs, no further data will be received from Plaid for this institution and you'll no longer be billed for it by Plaid.
See It In Action
View this page in Edit mode to see the workflows.Institution Name:
Institution Needs Update: No
Further Resources
As mentioned above, you should work to handle USER_PERMISSION_REVOKED type errors. Learn more at https://plaid.com/docs/api/webhooks/#item-webhooks
Still Have Questions?
Email support for the Lost Sheep Advisory plugins and templates is included.
Email us at info@lostsheep.dev
Plugin & Template Support is complementary but subject to the Lost Sheep Advisory terms of service available at https://lostsheep.dev/terms
Email us at info@lostsheep.dev
Plugin & Template Support is complementary but subject to the Lost Sheep Advisory terms of service available at https://lostsheep.dev/terms
LOST SHEEP ADVISORY
About UsIRS Form W9Get In Touch/Support
Copyright 2025 IvyCo Incorporated, dba Lost Sheep Advisory
Bubble and the Bubble logo are trademarks of Bubble Group, Inc. Lost Sheep Advisory is an independent corporation and is not affiliated with Bubble.
Bubble and the Bubble logo are trademarks of Bubble Group, Inc. Lost Sheep Advisory is an independent corporation and is not affiliated with Bubble.