Updating an Item

Overview#

After creating an Item successfully, you can continue to collect products data that appears in the following days by triggering an update for your existing Item reference, instead of creating a whole new Item from scratch.

Updating an existing Item is more cost-efficient, as it only retrieves institution products data generated after the last collection process.

How to Update an Item#

To update an existing Item using Pluggy Connect, follow these steps:

1. Create a Connect Token with the Item ID#

Create a new Connect Token, specifying the itemId parameter of the corresponding Item connection you want to refresh. This is necessary to let Pluggy properly validate that you are authorized to access and update this specific Item.

curl --request POST \
  --url https://api.pluggy.ai/connect_token \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "itemId": "ITEM_ID_TO_UPDATE"
  }'

2. Pass the Connect Token and Item ID to the Widget#

Pass to Connect both the recently created connectToken and the corresponding Item id through the updateItem property:

import PluggyConnect from 'pluggy-connect-sdk';
 
const pluggyConnect = new PluggyConnect({
  connectToken: 'your-connect-token',
  updateItem: 'ITEM_ID_TO_UPDATE',
  onSuccess: (itemData) => {
    console.log('Item updated successfully!', itemData);
  },
  onError: (error) => {
    console.error('Update error:', error);
  },
});
 
pluggyConnect.init();

Or with React:

import { PluggyConnect } from 'react-pluggy-connect';
 
function UpdateWidget({ connectToken, itemId }) {
  return (
    <PluggyConnect
      connectToken={connectToken}
      updateItem={itemId}
      onSuccess={({ item }) => console.log('Updated!', item.id)}
      onError={({ message }) => console.error(message)}
    />
  );
}

Widget Behavior During Update#

• If there is no further input from the user required, Pluggy Connect will just start the update process automatically.
• Otherwise, when new credentials and/or a MFA parameter is required, Pluggy Connect will prompt the user to complete them before the update process begins.

Code Example

Check out a full standalone HTML example in our recipe: Update an Item using Pluggy Connect.

When User Input Is Required#

In most cases, you can simply start the Item update process without any problem or further input from the user. However, there are some scenarios where this is not possible, due to limitations related to extra authentication requirements from the institution (such as an MFA requirement), or due to the Item having an invalid credentials state which requires new credentials input from the user.

These scenarios are the following:

• Items that could not succeed due to a problem with their credentials (Item status: INVALID_CREDENTIALS).
• Items that are not able to be auto-synced by Pluggy on our daily synchronization process, due to the connection needing an extra input from the user, such as a MFA parameter.

Case: INVALID_CREDENTIALS#

This happens when:

• The credentials provided by the user have not been correct, for example due to an incorrect input.
• The credentials were correct, but when we tried to auto-sync the Item by reusing the last valid credentials, we found an invalid login error.

For any of these situations, the user will need to use Pluggy Connect to update this Item and provide new credentials.

After this, if the login step succeeded, any further update of this Item will just reuse the newly provided credentials, and our auto-sync process will resume working again.

Case: Item Not Auto-Syncheable#

This is the case for institutions that require an extra MFA login step.

In this scenario, the only option for the Item to be updated is to have the user open Pluggy Connect configured for the corresponding Item, and have them solve the required MFA challenge as needed.

Some examples are:

• XP
• Bradesco
• Easynvest

You can find in the complete list of Connectors which ones require an MFA.

Note

There are some institutions that only require an initial verification or device authorization as a MFA for the first time. After this, no more manual input is needed from the user, so we'll be able to auto-sync these Items as well.

Forcing Credential Re-entry with forceAskForCredentials#

By default, when updating an Item that is already in a valid/connected state, the widget may attempt to re-execute the connection automatically — without showing the credentials form — since the credentials are already stored.

Setting forceAskForCredentials: true overrides this behavior and always presents the credentials form to the user, requiring them to explicitly re-enter their credentials before the update proceeds.

Note

forceAskForCredentials only has a meaningful effect when updateItem is also set. It is intended exclusively for Item update flows, not for new Item creation.

pluggyConnect.init({
  updateItem: "<item-id>",
  forceAskForCredentials: true,
  // ...other options
});

When to Use This Option#

Behavior Summary#

Limitations When Updating Items Through the API#

When new users create teams and applications, these client IDs have a limit for updating Items directly through the API with the PATCH /items endpoint: updates cannot be performed more than once per hour.

This limitation does not affect manual updates done through the widget — there are no limitations there. Also, when you are about to move your application to production, we recommend talking with our support team to remove this limitation.

Automatic Updates#

Pluggy provides automatic Item updates for Production applications, every 24, 12 or 8 hours depending on your plan.

Completion and Webhooks#

Once an update has been completed:

1. The Item changes its status to UPDATED
2. The item/updated webhook is triggered
3. It is expected that customers implement a sync process after the webhook to sync the data

Best Practices#

• Always create a new Connect Token with the specific itemId before triggering an update
• Listen for the onSuccess callback to confirm the update was completed
• Implement webhook handlers to process updated data asynchronously
• Use the item/updated webhook event to trigger your data synchronization process