# Item

As we've introduced [before](/docs/glossary), an Item is the representation of a connection with a specific Connector of an Institution and serves as the entry point to access the set of products recovered from the user who gave his consent to collect his/her data.

## Creating an Item: Institution authentication flow

To create an Item, the easiest, most polished, battle-tested, and least error-prone way for a user, is to interact with our [Pluggy Connect Widget](/docs/pluggy-connect-introduction), where they can provide consent, follow through the Institution authentication steps, and quickly have their products available in our API.

Otherwise, you can develop an application that implements the Item creation flow yourself, although this can be a daunting, complex task, and difficult to get right; so it's not the preferred choice we recommend.

When an Item is created and the institution sync finishes successfully, we'll retrieve all the latest financial products data, for up to the last 365 days.

### Accessing Item collected data

To access the data of the Item collected products, you'll have to interact with our API using the related endpoints. To help reduce development times, we provide several [Server side SDKs](/docs/server-side-sdks). If none suits you please let us know! We'll be happy to help.

> **Avoid reinventing the wheel, use our SDKs!**
>
> We strongly recommend that if there is an existing SDK for your language, that you use it, since its fully supported by our development team and error proof.
>
> If you end up creating your own integration, we won't be providing support for that specific implementation.

### Products

When *Pluggy* creates an Item, it automatically collects all the products requested as a step-by-step execution, pulling the information from the FI and storing it on our DB. *By default will collect all the products enabled on your team's subscription.*

When recovering an item, you will find the list of products enabled for this item, and you can specify this value as well on creation.

To customize which products you want to collect for a specific `item` you can send the `products` parameter (using the product type in uppercase) when [creating](/reference/items-create) the `item` (if you integrate through api) or the [widget's configuration](/docs/environments-and-configurations#available-configurations) using the `products` property.

## Updating an Item

The process to update an Item is quite similar to the creation one. The recommended way to do it, is also using our Pluggy Connect widget, as explained [here](/docs/updating-an-item). It can also be done via API: [Update an Item](/reference/items-update) (also review: [Item Send MFA](/reference/items-send-mfa)).

When an Item update is successful, we retrieve all the products data since the last time we did a data collection, and merge it with the previously collected data.

Also, data for *up to 4 days before* the last successful update date will be collected and merged too, to make up for any possible changes or additions that could have occurred in the institution data and not lose track of them.

### Auto-sync

Once created, an **Item** will have a reference to the stored user parameters and credentials needed to execute the data collection from the institution. Note that all credentials are encrypted, and can **never** be retrieved from the API.

This enables *Pluggy* to run our auto-sync process: on a schedule agreed with you, we'll collect the transaction data of the last few days and automatically add it on top of the existing collected data.

This way, you'll always have up-to-date access to the product data of the connected Institution, and you **won't be required to set up any batch process** to update your connections, just listen to webhook notifications of new updates.

#### Choosing a schedule

Auto-sync can follow one of two schedules. Both are configured by Pluggy on your application — reach out to your account manager to set one up or change it.

- **Every N hours.** Syncs run at a fixed interval, counted from the end of the previous sync. Available intervals are 6, 8, 12, 24, 30, 48 and 96 hours. Optionally, we can anchor the daily cycle to a starting hour, so the first sync of each day lands close to a time you choose. Because each sync is counted from when the previous one finished, the exact time of day drifts. If you need syncs to land at predictable times, use the option below.
- **At specific times of day.** Syncs run at up to **4 fixed times a day** — for example 09:00, 11:00, 13:00 and 18:00. This is the better fit when your product depends on data being fresh at particular moments — for example, reconciling during business hours, or checking for incoming transfers before a daily cut-off. Within each window, individual syncs are spread across the hour rather than all firing at the exact minute. On an account with many connections, expect them to complete progressively through the window rather than all at once.

When there is an error in an auto-sync update, two things can happen:

- If it was a `LOGIN_ERROR` (for example, when the credentials are invalid), the update will not be retried and the Item will no longer be updated by auto-sync. Auto-syncing will only resume when the client connects the Item successfully again.
- If it was a different error, we retry the update every 1 hour up to 5 attempts, after that, the Item is also dropped from auto-sync.

The `nextAutoSyncAt` in the [GET /items/\{id\}](/reference/items-retrieve) endpoint indicates when is the next auto-sync update for the Item, or null if it does not have auto-sync. Remember that this is the **minimum** date at which the next auto-sync update will run: it can be slightly delayed depending on the load of the institution's connector at the time.

> **Premium Feature**
>
> The auto-sync feature is only available for **Production** applications. It can be configured to run every 24, 12, or 8 hours based on your subscription.
>
> If you require to maintain the connections in sync, the only way would be using our Auto-Sync, batch update process will be mitigated and should never be created.

#### Meu Pluggy connections are a separate case

[Meu Pluggy](https://meu.pluggy.ai) is a standalone service for end users connecting their own accounts, and it has its own rules. Connections made **inside Meu Pluggy** are refreshed automatically **every 24 hours**, for free -- that cadence belongs to the service itself and does not depend on any application's subscription.

This matters when your application connects through the **MeuPluggy connector**, because there are then **two distinct Items**:

| Item | Where it lives | How it refreshes |
|---|---|---|
| The original Item | Inside Meu Pluggy | Automatically, every 24 hours |
| The proxy Item | In your application | Reflects the original Item; it does **not** run its own auto-sync |

So both of these statements are true at the same time, and they are not in conflict: *"Meu Pluggy connections are updated daily"* (the original Item) and *"MeuPluggy proxy Items are not auto-synced"* (the proxy Item). They are different objects.

For any other connector, the Item in your application follows the auto-sync rules described above.

> **Reading `nextAutoSyncAt`**
>
> `nextAutoSyncAt` is only returned when the application has auto-sync enabled. A `null` there means *"this application has no auto-sync configured"*, not *"the connection is broken"*.

## Webhook Notifications

It's possible to listen to Webhook Notifications to recover all events related to a specific `Item`. For this, you'll only need to provide a valid URL in the `webhookUrl` parameter, either when creating a [Connect Token](/reference/connect-token-create), or in the [Item creation request](/reference/items-create) itself.

You can find more information in the [Webhook](/docs/webhooks) section.

> **Multiple webhooks**
>
> If you create multiple webhooks for an item using the `webhookUrl` and the client-level Webhook configuration, you will receive multiple notifications.

### Avoiding duplicates

To avoid a user from connecting more than once his account at Pluggy, we provide a configuration while creating your connection, that will validate if the credentials already exist before going through the authentication process.

Using this configuration, the user will receive an error from the API specifying that there is already an Item created for those credentials.

You can set it up in two ways:

- If you are using *Pluggy Connect* you can [create the token](/reference/connect-token-create) with the item options for `avoidDuplicates` in true, and all items generated with that `connectToken` will be validated.
- If you are connected directly through API, you [can create the item](/reference/items-create) with the same option in the payload.

When creating an item that already exists will recover a 400 HTTP error.

```json
{
  "code": 400,
  "codeDescription": "ITEM_USER_ALREADY_EXISTS",
  "message": "There are other items with the same credentials, you can't create a new one",
  "data": {
    "items": [
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d93",
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d94"
    ]
  }
}
```

The `data.items` array holds the ids of the existing items that already use those
credentials, so you can point your user at the connection they already have
instead of asking them to try again. Note the ids are nested under `data` — they
are not returned at the root of the response body.

These connectors support the Avoid duplicates feature:

- Pluggy direct connectors: all
- Open Finance connectors:
  - Nubank

### Referencing your user

When you create an `Item` you can use the `clientUserId` as an external identifier from your systems. This will help you identify an item with your user.

You can setup this up in two ways:

- Using our Pluggy Connect widget, you can create a connectToken with the value for `clientUserId`. All items created with that connect token will have that value.
- When creating Items through our API, the payload has an `clientUserId` parameter to receive this reference.

### Searching and listing items

You can retrieve the connections that belong to your account with [GET /v2/items](/reference/items-list-by-cursor), most recently created first. Results can be narrowed with `clientUserId` — the external identifier you assigned when creating the Item — or with `connectorId`, to list only the connections to a given institution.

This endpoint is **opt-in and disabled by default**. Listing lets an API key enumerate every connection you hold, which is a wider level of access than retrieving a known Item by its id, so it is enabled per agreement: contact support if you want it for your team. Until then the endpoint responds `403` with `LIST_ITEMS_FEATURE_NOT_ENABLED`.

Responses are cursor-paginated. Instead of a page number, each response carries a `next` value pointing at the following page: append it as-is to the endpoint path, and stop once it comes back `null`. Any filters you sent are already part of `next`, so there is no need to repeat them.

```javascript
let next = ''
const items = []

do {
  const response = await fetch(`https://api.pluggy.ai/v2/items${next}`, {
    headers: { 'X-API-KEY': apiKey },
  })
  const page = await response.json()

  items.push(...page.results)
  next = page.next
} while (next !== null)
```

The `after` parameter takes only the cursor value. Sending the whole `next` string as `after` is rejected with `INVALID_CURSOR`.

Listing is a convenience, not a replacement for your own bookkeeping: we still recommend tracking your connections in your datasource by their `itemId`, and keeping those references in sync.