# 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.

```bash
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:

```javascript
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:

```jsx
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](/recipes/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](/docs/connections/connectors-coverage) 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.

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

### When to Use This Option

| Scenario | Why `forceAskForCredentials` helps |
|----------|-----------------------------------|
| The user changed their banking password | Ensures the new password is captured instead of retrying with stale credentials |
| Your flow requires explicit credential confirmation for compliance or security | Guarantees the user actively re-enters credentials, creating an intentional re-authorization step |
| You suspect stored credentials may be outdated | Forces a fresh input rather than relying on an automatic reconnection attempt that may fail |

### Behavior Summary

| `forceAskForCredentials` | Item state | Widget behavior |
|--------------------------|------------|-----------------|
| `false` (default) | Valid / connected | May skip the credentials form and attempt reconnection automatically |
| `true` | Valid / connected | Always shows the credentials form before proceeding |
| `true` or `false` | Any | No effect if `updateItem` is not set |

## 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](/docs/connections/item#auto-sync) 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