Updating an Item

After creating an Item successfully, you'll probably want to continue to collect the products data that continues to appear in the next days.

To achieve this, instead of creating a whole new Item from scratch (in which we collect all the data from the last 365 days) you can instead just trigger an update for your existing Item reference.

This is a much more cost-efficient process, as when doing this we'll only retrieve the institution products data that has been generated right after the last time we did the previous collection process. We'll even collect a few days before that, just to make sure we won't miss any changes or additions that could've happened recently.

📘

Note

We provide automatic Item updates, for Production applications, every 24/12/8 hours, based on your plan.

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 Instutition (such as a 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 a problem with their credentials (Item status: INVALID_CREDENTIALS).
• Items that are not able to auto-sync by Pluggy on our daily synchronization process, due to the connection needing an extra input from the user, such as a MFA parameter.

To open Pluggy Connect in this update mode, you need to:

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

2. Pass it to Connect, both the recently created connectToken, and the corresponding Item id through the updateItem property.

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

👍

Code Example

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

Limitations about item update through the API

When new users create teams and applications this client ids has a limit to update the items directly through the API with PATCH /items endpoint. The updates could not be performed more than once per hour.

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

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 him/her 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 only 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

Syncing the Data after Update

Once an update has been completed, the item will change its status to UPDATED, and will trigger the item/updated webhook.

It's expected that our customers implement a Sync process after the webhook to sync the data.

Usually the most frequent question, is how to sync transactions, check out this guide for more information.