Choosing how to initialize products

When you create a Link token, you specify which products to initialize Link with by including those products in the /link/token/create request. Which products you specify in the request parameters will impact many aspects of your Plaid integration, including user conversion, institution availability, the latency your user experiences when connecting their accounts in Link, the latency you experience when retrieving data from the API, and which products you will be billed for.

You can also add products to an Item post-Link, which is discussed below.

The table below summarizes the /link/token/create request parameters that determine product initialization in Link:

If a product was not initialized during Link, calling an endpoint for that product will automatically add that product to the Item. For example, if an Item was not initialized with Transactions during Link, calling /transactions/sync or /transactions/get on that Item for the first time will add the Transactions product to the Item.

In order to use this post-Link flow, you will need to have all required consent to add the product: for example, if the Item is at an OAuth institution that requires users to grant product-specific access, the end user will need to have granted that access to that product during the OAuth consent flow. To require that users provide all consent necessary to use a secondary product, use Required if Supported Products instead of adding the product post-Link.

If you are part of the Data Transparency Messaging beta, you cannot add products post-Link unless you specify them in the Additional Consented Products array.

In either case, if you do not have all the required consent to add a product, you will need to send the user through update mode.

Some additional exceptions to the post-Link product add flow exist: Identity Verification and Payment Initiation cannot be added post-Link. Assets and Bank Income can only be added post-Link via the update mode flow.

If you initialize Link with a product in the Products, Required if Supported Products, or Optional Products array, Plaid will prepare relevant product data during or immediately after Link. Otherwise, Plaid will only begin to fetch data for that product when you call an endpoint for that product, such as /auth/get or /transactions/sync. You can minimize product latency by initializing Link with a given product, as opposed to adding the product to the item post-Link.

Products that retrieve extended account history, such as Transactions and Investments, may take a minute or longer to prepare. If you specify one of these products when calling /link/token/create, and then you add another product immediately after the user has exited Link, you may experience higher latency when calling the secondary product because the first product is still being prepared.

You can avoid this problem by including the secondary product as either an Optional Product or Required if Supported Product when calling /link/token/create, which allows Plaid to optimize how product data is prepared.

If you initialize Link with a product that is billed under a one-time or subscription fee model (such as Auth, Identity, Income, Investments, Liabilities, or Transactions) you will be billed when the Item is created, even if you are not yet using the product's endpoints. There are exceptions:

• If you specify Auth and/or Identity in the Optional Products array, you will not be billed for them until you use their endpoints (e.g., /auth/get).
• You will not be billed for any products in the Additional Consented Products array until you use their endpoints.
• Investments has two different subscriptions that can be associated with it: Investments Holdings and Investments Transactions. Initializing Link with Investments adds only Investments Holdings; the Investments Transactions subscription will not be added until you call /investments/transactions/get for the first time on the Item. Note that Plaid will still pre-fetch investment transaction history when you initialize with Investments, even though you are not yet being billed for Investments Transactions.

To avoid unwanted charges, do not initialize Link with a one-time or subscription fee product in Production unless you are sure you are going to use that product. This instruction applies to the Products, Required if Supported Products, and Optional Products arrays, with the exception of Auth and Identity when used as Optional Products.

To learn more about how Plaid bills each product, see Billing.

The products you specify in the Products array will determine which institutions and accounts are available in Link. If you specify multiple products in the Products array, only institutions and accounts supporting all of those products will be available. See the accounts / product support matrix to learn which account types support which products.

To avoid overly restricting the institution and account list, you can use the Required if Supported Products or Optional Products features, or initialize Link with only your required products in the Products array and then call your other products' endpoints later.

You may want to require one or more secondary products when possible, but avoid excluding users whose financial institution doesn't support those products. To do this, specify the secondary products in the Required if Supported Products array.

When a product is specified in the Required if Supported Products array, Plaid will require that product if possible. If the institution the end user is attempting to link supports the secondary product, and the user grants Plaid access to an account at the institution that is compatible with it, Plaid will treat the product as though it was specified in the Products array. If the institution doesn't support the product, if the user doesn't have accounts compatible with it, or if the user has compatible accounts but doesn't grant access to them, Plaid will ignore the product. (To determine whether a product was successfully added to the Item, you can call /item/get after obtaining your access token and read the Item's Products array.)

For example, if you initialize Link with both Auth and Identity in the Products array, a user will only be able to link an account if both Auth and Identity are supported by their institution, and they will not be able to use flows like Same-day Micro-deposits that require Auth to be initialized by itself. But if you specify Auth in the Products array and Identity in the Required if Supported Products array, users will be able to link checking and savings accounts at any institution that supports Auth, even if the institution does not support Identity. They will also be able to access flows that require Auth to be initialized by itself, like Same-day Micro-deposits.

If the institution does support both Auth and Identity, Plaid will attempt to initialize the Item with both products. If the institution has an OAuth flow where Identity access can be configured as a separate permission, and the user does not grant access to Identity, the Link attempt will error and the user will be prompted to retry the OAuth flow.

As another example, if Transactions and Auth are both specified in the Products array, users will only be able to link checking or savings accounts, because specifying Auth limits acceptable accounts to checking and savings accounts. However, if Transactions is specified in the Products array and Auth is specified in the Required if Supported Products array, users will be able to link other Transactions-compatible account types, such as credit cards and money market accounts. If they do link a checking or savings account, Plaid will fetch Auth data for that account.

Optional Products is similar to Required if Supported Products, except that products specified in the Optional Products array are treated as best-effort. If an institution supports the selected products but they cannot be added to the Item (e.g., because of a temporary institution error impacting only some products, or because the user did not grant the required product-specific OAuth permissions), Item creation will succeed in spite of these failures.

Like the Required if Supported Products array, the Optional Products array does not affect institution filtering or account filtering, which means there are no guarantees around product data availability. For example, if you initialize Link with Transactions in the Products array and Auth in the Optional Products array, the Item is guaranteed to support Transactions, but it will also allow linking account types that are incompatible with Auth, like credit cards.

Unlike Required if Supported Products, Optional Products will not fail the Link attempt if the necessary OAuth permissions are not granted. If the user does not grant access to the data needed to support an Optional Product in the OAuth linking flow, they will not be required to go through the OAuth flow again to update their permissions. Instead, the Item will be successfully created and the Optional Product will be unavailable until you have prompted the user to fix their permissions via Update Mode.

If Auth is specified in the Optional Products array, Auth will only be added to the Item if the institution supports Instant Auth.

If you specify Auth and/or Identity in the Optional Products array, you will only be billed for these products if you call their endpoints.

If your only reason for omitting a product from the Products array is to increase the number of institutions covered, you should specify the product in the Required if Supported Products array rather than adding the product by calling its endpoint. Initializing both products during Link will make it easier to obtain the consent required at institutions that use OAuth, because the user will be prompted to fix their selections during the OAuth flow if they do not grant the required consent for all products. Initializing both products upfront can also reduce latency, because it allows Plaid to begin fetching data immediately and to optimize the order in which different types of data are requested.

For example, one common pattern for payments customers is to use Auth in the Products array, and Identity in the Required if Supported Products array. This means you will get Identity coverage for all accounts where it's available, but you won't block customers from linking their accounts if their institution doesn't support Identity.

Required if Supported Products is recommended over Optional Products if it is important to your use case that your user not be able to link an account if they've opted out of using certain products in the OAuth flow. For example, if you're accepting ACH payments, you might not want to let a user link their account while opting out of products used for risk mitigation, like Identity or Signal.

If you think that you may want to use Auth and/or Identity for an Item, but it isn't necessary for all users, you should specify the product in the Optional Products array, because doing so will significantly reduce API latency when you call the product's endpoints later on.

As an example of when to use the Optional Products array, if your app primarily uses Transactions for budgeting but also uses Auth to transfer funds for a small percentage of users (e.g., paid users), you should specify Transactions in the Products array and Auth in the Optional Products array. This will ensure that all Items support Transactions, while also ensuring that Plaid will collect Auth data for as many users as possible without affecting Link conversion or increasing your Auth bill.

As an example of when not to use the Optional Products array, if your app primarily uses Auth for funds transfers but also offers an optional budgeting add-on that uses Transactions, you should specify Auth in the Products array and then add Transactions to the Item by calling /transactions/sync only once your user opts in to using the budgeting tool. This will prevent you from being billed for Transactions before you are sure you need to use it.

If you have opted in to the Data Transparency Messaging beta, then depending on the permissions that were granted during the original Link flow, you may not be able to initialize an Item with an additional product post-Link simply by calling a product endpoint, as you will need to have obtained the proper consent for that product.

Instead, you should specify this product in the Additional Consented Products array when first calling /link/token/create. If the Item has already been created and the product you need is not in the Item's Consented Products field (which can be checked by calling /item/get, you need to obtain additional user consent, which you can do by sending the user through Update Mode with the Products array updated to include the full set of products you would like to obtain consent for.

Both the Additional Consented Products array and Update Mode methods obtain consent for a product without adding the product to that Item, avoiding any billing or performance implications.

There are some exceptions to the ability to initialize products by calling their endpoints:

• Bank Income and Assets can both be initialized post-Link, but may require re-launching Link to obtain additional consent. See Verifying Bank Income for existing Items and Adding Assets to existing Items.
• Identity Verification and Payment Initiation cannot be initialized post-Link.
• When Auth is initialized post-Link, the main Instant Auth flow can be used, but the less common Instant Match, Automated Micro-deposits, or Same Day Micro-deposits flows cannot be initialized post-Link, as these are interactive flows that require user input.

Some products cannot be initialized alongside other products in the same Link session:

• To use Same Day Micro-deposits, Auth must be the only product Link is initialized with.
• Income can only be initialized alongside other products if using Bank Income; Payroll Income and Document Income cannot be initialized alongside other products.
• Identity Verification and Payment Initiation cannot be initialized alongside any other products. If you need to use these products along with other Plaid products, your user will need to launch the Link flow a second time.

Initialize Link with Auth and Signal in the Products array and Identity in the Required if Supported Products array. Specifying Identity in the Required if Supported Products array will increase conversion while minimizing latency when calling Identity endpoints.

For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool.

If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it.

Initialize Link with Assets in the Products array and Auth in the Required if Supported Products array. This will allow your user to link any account type, not just checking or savings accounts, which is important for getting their full financial picture.

If Transactions is the primary product, initialize with Transactions in the Products array, Auth in the Optional Products array, and Identity in the Required if Supported Products array. This will reduce latency when calling the Auth and/or Identity endpoints while maximizing institution coverage. It will also prevent you from being charged for Auth unless you end up calling its endpoints.

For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool.

If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it.

For personal finance use cases, initialize Link with Transactions. Then call Liabilities or Investments endpoints after the Item has been linked, based on the account type that was linked. Because virtually all Items that support Liabilities or Investments also support Transactions, this will maximize conversion. If you call an endpoint that is not applicable to the Item (for example, if you call /liabilities/get on a checking account, or /investments/transactions/get on a credit card account), the call will fail and you will not be billed for it.

Initialize with Income Verification, then call Transactions endpoints later, after the Item has been linked. Because Bank Income must fetch transaction data in order to verify the user's income, initializing with Transactions is not necessary. (Even though Bank Income uses transaction data, you will not be billed for Transactions on a Bank Income Item unless you add Transactions to the Item, either during or after Link.)

Initialize Link with both Income Verification and Assets in the Products array. Because institutions that support one of these products almost always support both of them, and because you will not be billed for Assets until you call the Assets endpoints, this is safe to do even if you aren't sure if you will use Assets. Assets can't be added to an Item post-Link without sending the user through Update Mode, so including Assets upfront will increase conversion.

If you already have an Item enabled with one of these products and want to add the other: see the instructions on Verifying Bank Income for existing Items to add Bank Income to the Item. See the instructions on Getting an Asset Report for an existing Item to add Assets.