Transactions
API reference for Transactions endpoints and webhooks
Retrieve and refresh up to 24 months of historical transaction data, including geolocation, merchant, and category information.
Endpoints | |
---|---|
/transactions/sync | Get transaction data or incremental transaction updates |
/transactions/get | Fetch transaction data |
/transactions/recurring/get | Fetch recurring transaction data |
/transactions/refresh | Refresh transaction data |
/categories/get | Fetch all transaction categories |
See also | |
---|---|
/processor/transactions/sync | Get transaction data or incremental transaction updates |
/processor/transactions/get | Fetch transaction data |
/processor/transactions/recurring/get | Fetch recurring transaction data |
/processor/transactions/refresh | Refresh transaction data |
Webhooks | |
---|---|
SYNC_UPDATES_AVAILABLE | New updates available |
RECURRING_TRANSACTIONS_UPDATE | New recurring updates available |
INITIAL_UPDATE | Initial transactions ready |
HISTORICAL_UPDATE | Historical transactions ready |
DEFAULT_UPDATE | New transactions available |
TRANSACTIONS_REMOVED | Deleted transactions detected |
Endpoints
/transactions/sync
If you are migrating to /transactions/sync
from an existing /transactions/get
integration, also refer to the Transactions Sync migration guide.
Get incremental transaction updates on an Item
The /transactions/sync
endpoint allows developers to subscribe to all transactions associated with an Item and get updates synchronously in a stream-like manner, using a cursor to track which updates have already been seen./transactions/sync
provides the same functionality as /transactions/get
and can be used instead of /transactions/get
to simplify the process of tracking transactions updates. To learn more about migrating from /transactions/get
, see the Transactions Sync migration guide.
This endpoint provides user-authorized transaction data for credit
, depository
, and some loan-type accounts (only those with account subtype student
; coverage may be limited). For transaction history from investments
accounts, use /investments/transactions/get
instead.
Returned transactions data is grouped into three types of update, indicating whether the transaction was added, removed, or modified since the last call to the API.
In the first call to /transactions/sync
for an Item, the endpoint will return all historical transactions data associated with that Item up until the time of the API call (as "adds"), which then generates a next_cursor
for that Item. In subsequent calls, send the next_cursor
to receive only the changes that have occurred since the previous call.
Due to the potentially large number of transactions associated with an Item, results are paginated. The has_more
field specifies if additional calls are necessary to fetch all available transaction updates. Call /transactions/sync
with the new cursor, pulling all updates, until has_more
is false
.
When retrieving paginated updates, track both the next_cursor
from the latest response and the original cursor from the first call in which has_more
was true
; if a call to /transactions/sync
fails due to the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION
error, the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed.
Whenever new or updated transaction data becomes available, /transactions/sync
will provide these updates. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To find out when the Item was last updated, use the Item Debugger or call /item/get
; the item.status.transactions.last_successful_update
field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the /transactions/refresh
endpoint.
For newly created Items, data may not be immediately available to /transactions/sync
. Plaid begins preparing transactions data when the Item is created, but the process can take anywhere from a few seconds to several minutes to complete, depending on the number of transactions available.
To be alerted when new data is available, listen for the SYNC_UPDATES_AVAILABLE
webhook.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.access_token
secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.cursor
"now"
, which can be used to fast-forward the cursor as part of migrating an existing Item from /transactions/get
to /transactions/sync
. For more information, see the Transactions sync migration guide. Note that using the "now"
value is not supported for any use case other than migrating existing Items from /transactions/get
.The upper-bound length of this cursor is 256 characters of base64.
count
100
1
500
false
options
options
must not be null
.include_original _description
false
days_requested
transactions
in the products
, required_if_supported_products
, or optional_products
array when calling /link/token/create
or by making a previous call to /transactions/sync
or /transactions/get
). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default.If you are initializing your Items with transactions during the
/link/token/create
call (e.g. by including transactions
in the /link/token/create
products
array), you must use the transactions.days_requested
field in the /link/token/create
request instead of in the /transactions/sync
request.If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via
/item/remove
and send the user through Link to create a new Item. Customers using Recurring Transactions should request at least 180 days of history for optimal results.
1
730
90
1// Provide a cursor from your database if you've previously2// received one for the Item. Leave null if this is your3// first sync call for this Item. The first request will4// return a cursor.5let cursor = database.getLatestCursorOrNull(itemId);67// New transaction updates since "cursor"8let added: Array<Transaction> = [];9let modified: Array<Transaction> = [];10// Removed transaction ids11let removed: Array<RemovedTransaction> = [];12let hasMore = true;1314// Iterate through each page of new transaction updates for item15while (hasMore) {16 const request: TransactionsSyncRequest = {17 access_token: accessToken,18 cursor: cursor,19 };20 const response = await client.transactionsSync(request);21 const data = response.data;2223 // Add this page of results24 added = added.concat(data.added);25 modified = modified.concat(data.modified);26 removed = removed.concat(data.removed);2728 hasMore = data.has_more;2930 // Update cursor to the next cursor31 cursor = data.next_cursor;32}3334// Persist cursor and updated data35database.applyUpdates(itemId, added, modified, removed, cursor);
Response fields and example
transactions_update _status
TRANSACTIONS_UPDATE_STATUS_UNKNOWN
: Unable to fetch transactions update status for Item.
NOT_READY
: The Item is pending transaction pull.
INITIAL_UPDATE_COMPLETE
: Initial pull for the Item is complete, historical pull is pending.
HISTORICAL_UPDATE_COMPLETE
: Both initial and historical pull for Item are complete.TRANSACTIONS_UPDATE_STATUS_UNKNOWN
, NOT_READY
, INITIAL_UPDATE_COMPLETE
, HISTORICAL_UPDATE_COMPLETE
accounts
account_id
account_id
will be assigned to the account.The
account_id
can also change if the access_token
is deleted and the same credentials that were used to generate that access_token
are used to generate a new access_token
on a later date. In that case, the new account_id
will be different from the old account_id
.If an account with a specific
account_id
disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.Like all Plaid identifiers, the
account_id
is case sensitive.balances
/accounts/balance/get
.available
For
credit
-type accounts, the available
balance typically equals the limit
less the current
balance, less any pending outflows plus any pending inflows.For
depository
-type accounts, the available
balance typically equals the current
balance less any pending outflows plus any pending inflows. For depository
-type accounts, the available
balance does not include the overdraft limit.For
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier), the available
balance is the total cash available to withdraw as presented by the institution.Note that not all institutions calculate the
available
balance. In the event that available
balance is unavailable, Plaid will return an available
balance value of null
.Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by
/accounts/balance/get
.If
current
is null
this field is guaranteed not to be null
.double
current
For
credit
-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.For
loan
-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944
). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.For
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.Note that balance information may be cached unless the value was returned by
/accounts/balance/get
; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available
balance as provided by /accounts/balance/get
.When returned by
/accounts/balance/get
, this field may be null
. When this happens, available
is guaranteed not to be null
.double
limit
credit
-type accounts, this represents the credit limit.For
depository
-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.In North America, this field is typically only available for
credit
-type accounts.double
iso_currency_code
unofficial_currency_code
is non-null.unofficial_currency _code
iso_currency_code
is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
unofficial_currency_code
s.last_updated_datetime
YYYY-MM-DDTHH:mm:ssZ
) indicating the oldest acceptable balance when making a request to /accounts/balance/get
.This field is only used and expected when the institution is
ins_128026
(Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID_REQUEST
error with the code of INVALID_FIELD
will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types.If the balance that is pulled is older than the given timestamp for Items with this field required, an
INVALID_REQUEST
error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE
will be returned with the most recent timestamp for the requested account contained in the response.date-time
mask
name
official_name
type
investment:
Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage
instead.credit:
Credit carddepository:
Depository accountloan:
Loan accountother:
Non-specified account typeSee the Account type schema for a full listing of account types and corresponding subtypes.
investment
, credit
, depository
, loan
, brokerage
, other
subtype
401a
, 401k
, 403B
, 457b
, 529
, auto
, brokerage
, business
, cash isa
, cash management
, cd
, checking
, commercial
, construction
, consumer
, credit card
, crypto exchange
, ebt
, education savings account
, fixed annuity
, gic
, health reimbursement arrangement
, home equity
, hsa
, isa
, ira
, keogh
, lif
, life insurance
, line of credit
, lira
, loan
, lrif
, lrsp
, money market
, mortgage
, mutual fund
, non-custodial wallet
, non-taxable brokerage account
, other
, other insurance
, other annuity
, overdraft
, paypal
, payroll
, pension
, prepaid
, prif
, profit sharing plan
, rdsp
, resp
, retirement
, rlif
, roth
, roth 401k
, rrif
, rrsp
, sarsep
, savings
, sep ira
, simple ira
, sipp
, stock plan
, student
, thrift savings plan
, tfsa
, trust
, ugma
, utma
, variable annuity
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.automatically_verified
: The Item has successfully been automatically verified manually_verified
: The Item has successfully been manually verifiedverification_expired
: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.verification_failed
: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.database_matched
: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.database_insights_pass
: The Item's numbers have been verified using Plaid's data sources and have strong signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.database_insights_pass_with_caution
: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.database_insights_fail
: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.automatically_verified
, pending_automatic_verification
, pending_manual_verification
, manually_verified
, verification_expired
, verification_failed
, database_matched
, database_insights_pass
, database_insights_pass_with_caution
, database_insights_fail
verification_insights
network_status
has_numbers_match
is_numbers_match _verified
previous_returns
has_previous _administrative_return
account_number_format
valid
: indicates that the account number has a correct format for the institution.invalid
: indicates that the account number has an incorrect format for the institution.unknown
: indicates that there was not enough information to determine whether the format is correct for the institution.valid
, invalid
, unknown
persistent_account_id
holder_category
business
, personal
, unrecognized
added
cursor
ordered by ascending last modified time.account_id
amount
iso_currency_code
or unofficial_currency_code
. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income.double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_code
s.category
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.category_id
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.check_number
date
YYYY-MM-DD
). To receive information about the date that a posted transaction was initiated, see the authorized_date
field.date
location
address
city
region
state
.postal_code
zip
.country
lat
double
lon
double
store_number
name
Note: This is a legacy field that is not actively maintained. Use
merchant_name
instead for the merchant name.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, this field will always appear. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.merchant_name
name
field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null
.original_description
/transactions/sync
or /transactions/get
, this field will only be included if the client has set options.include_original_description
to true
.payment_meta
null
.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, the payment_meta
key will always appear, but no data elements are guaranteed. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.reference_number
ppd_id
payee
by_order_of
null
if the transaction is not a wire transfer.payer
payment_method
payment_processor
reason
pending
true
, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.pending_transaction_id
account_owner
transaction_id
transaction_id
is case sensitive.transaction_type
payment_channel
field, transaction_type
will be deprecated in the future.digital:
transactions that took place online.place:
transactions that were made at a physical location.special:
transactions that relate to banks, e.g. fees or deposits.unresolved:
transactions that do not fit into the other three types.digital
, place
, special
, unresolved
logo_url
website
authorized_date
date
field will indicate the posted date, but authorized_date
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date
, when available, is generally preferable to use over the date
field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD
).date
authorized_datetime
YYYY-MM-DDTHH:mm:ssZ
). For posted transactions, the datetime
field will indicate the posted date, but authorized_datetime
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime
, when available, is generally preferable to use over the datetime
field for posted transactions, as it will generally represent the date the user actually made the transaction.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
datetime
YYYY-MM-DDTHH:mm:ssZ
). For the date that the transaction was initiated, rather than posted, see the authorized_datetime
field.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
payment_channel
online:
transactions that took place online.in store:
transactions that were made at a physical location.other:
transactions that relate to banks, e.g. fees or deposits.This field replaces the
transaction_type
field.online
, in store
, other
personal_finance _category
See the
taxonomy CSV file
for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide
.primary
detailed
confidence_level
VERY_HIGH
: We are more than 98% confident that this category reflects the intent of the transaction.
HIGH
: We are more than 90% confident that this category reflects the intent of the transaction.
MEDIUM
: We are moderately confident that this category reflects the intent of the transaction.
LOW
: This category may reflect the intent, but there may be other categories that are more accurate.
UNKNOWN
: We don’t know the confidence level for this category.transaction_code
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to
null
.adjustment:
Bank adjustmentatm:
Cash deposit or withdrawal via an automated teller machinebank charge:
Charge or fee levied by the institutionbill payment
: Payment of a billcash:
Cash deposit or withdrawalcashback:
Cash withdrawal while making a debit card purchasecheque:
Document ordering the payment of money to another person or organizationdirect debit:
Automatic withdrawal of funds initiated by a third party at a regular intervalinterest:
Interest earned or incurredpurchase:
Purchase made with a debit or credit cardstanding order:
Payment instructed by the account holder to a third party at a regular intervaltransfer:
Transfer of money between accountsadjustment
, atm
, bank charge
, bill payment
, cash
, cashback
, cheque
, direct debit
, interest
, purchase
, standing order
, transfer
, null
personal_finance _category_icon_url
counterparties
name
entity_id
type
merchant
: a provider of goods or services for purchase
financial_institution
: a financial entity (bank, credit union, BNPL, fintech)
payment_app
: a transfer or P2P app (e.g. Zelle)
marketplace
: a marketplace (e.g DoorDash, Google Play Store)
payment_terminal
: a point-of-sale payment terminal (e.g Square, Toast)
income_source
: the payer in an income transaction (e.g., an employer, client, or government agency)merchant
, financial_institution
, payment_app
, marketplace
, payment_terminal
, income_source
website
logo_url
confidence_level
VERY_HIGH
: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction.
HIGH
: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction.
MEDIUM
: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records.
LOW
: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description.
UNKNOWN
: We don’t know the confidence level for this counterparty.merchant_entity_id
modified
cursor
ordered by ascending last modified time.account_id
amount
iso_currency_code
or unofficial_currency_code
. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income.double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_code
s.category
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.category_id
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.check_number
date
YYYY-MM-DD
). To receive information about the date that a posted transaction was initiated, see the authorized_date
field.date
location
address
city
region
state
.postal_code
zip
.country
lat
double
lon
double
store_number
name
Note: This is a legacy field that is not actively maintained. Use
merchant_name
instead for the merchant name.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, this field will always appear. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.merchant_name
name
field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null
.original_description
/transactions/sync
or /transactions/get
, this field will only be included if the client has set options.include_original_description
to true
.payment_meta
null
.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, the payment_meta
key will always appear, but no data elements are guaranteed. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.reference_number
ppd_id
payee
by_order_of
null
if the transaction is not a wire transfer.payer
payment_method
payment_processor
reason
pending
true
, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.pending_transaction_id
account_owner
transaction_id
transaction_id
is case sensitive.transaction_type
payment_channel
field, transaction_type
will be deprecated in the future.digital:
transactions that took place online.place:
transactions that were made at a physical location.special:
transactions that relate to banks, e.g. fees or deposits.unresolved:
transactions that do not fit into the other three types.digital
, place
, special
, unresolved
logo_url
website
authorized_date
date
field will indicate the posted date, but authorized_date
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date
, when available, is generally preferable to use over the date
field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD
).date
authorized_datetime
YYYY-MM-DDTHH:mm:ssZ
). For posted transactions, the datetime
field will indicate the posted date, but authorized_datetime
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime
, when available, is generally preferable to use over the datetime
field for posted transactions, as it will generally represent the date the user actually made the transaction.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
datetime
YYYY-MM-DDTHH:mm:ssZ
). For the date that the transaction was initiated, rather than posted, see the authorized_datetime
field.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
payment_channel
online:
transactions that took place online.in store:
transactions that were made at a physical location.other:
transactions that relate to banks, e.g. fees or deposits.This field replaces the
transaction_type
field.online
, in store
, other
personal_finance _category
See the
taxonomy CSV file
for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide
.primary
detailed
confidence_level
VERY_HIGH
: We are more than 98% confident that this category reflects the intent of the transaction.
HIGH
: We are more than 90% confident that this category reflects the intent of the transaction.
MEDIUM
: We are moderately confident that this category reflects the intent of the transaction.
LOW
: This category may reflect the intent, but there may be other categories that are more accurate.
UNKNOWN
: We don’t know the confidence level for this category.transaction_code
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to
null
.adjustment:
Bank adjustmentatm:
Cash deposit or withdrawal via an automated teller machinebank charge:
Charge or fee levied by the institutionbill payment
: Payment of a billcash:
Cash deposit or withdrawalcashback:
Cash withdrawal while making a debit card purchasecheque:
Document ordering the payment of money to another person or organizationdirect debit:
Automatic withdrawal of funds initiated by a third party at a regular intervalinterest:
Interest earned or incurredpurchase:
Purchase made with a debit or credit cardstanding order:
Payment instructed by the account holder to a third party at a regular intervaltransfer:
Transfer of money between accountsadjustment
, atm
, bank charge
, bill payment
, cash
, cashback
, cheque
, direct debit
, interest
, purchase
, standing order
, transfer
, null
personal_finance _category_icon_url
counterparties
name
entity_id
type
merchant
: a provider of goods or services for purchase
financial_institution
: a financial entity (bank, credit union, BNPL, fintech)
payment_app
: a transfer or P2P app (e.g. Zelle)
marketplace
: a marketplace (e.g DoorDash, Google Play Store)
payment_terminal
: a point-of-sale payment terminal (e.g Square, Toast)
income_source
: the payer in an income transaction (e.g., an employer, client, or government agency)merchant
, financial_institution
, payment_app
, marketplace
, payment_terminal
, income_source
website
logo_url
confidence_level
VERY_HIGH
: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction.
HIGH
: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction.
MEDIUM
: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records.
LOW
: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description.
UNKNOWN
: We don’t know the confidence level for this counterparty.merchant_entity_id
removed
cursor
ordered by ascending last modified time.transaction_id
account_id
next_cursor
has_more
being false
) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string.has_more
cursor
set to next_cursor
. If has_more
is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination.request_id
1{2 "accounts": [3 {4 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",5 "balances": {6 "available": 110.94,7 "current": 110.94,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "0000",13 "name": "Plaid Checking",14 "official_name": "Plaid Gold Standard 0% Interest Checking",15 "subtype": "checking",16 "type": "depository"17 }18 ],19 "added": [20 {21 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",22 "account_owner": null,23 "amount": 72.1,24 "iso_currency_code": "USD",25 "unofficial_currency_code": null,26 "category": [27 "Shops",28 "Supermarkets and Groceries"29 ],30 "category_id": "19046000",31 "check_number": null,32 "counterparties": [33 {34 "name": "Walmart",35 "type": "merchant",36 "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",37 "website": "walmart.com",38 "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",39 "confidence_level": "VERY_HIGH"40 }41 ],42 "date": "2023-09-24",43 "datetime": "2023-09-24T11:01:01Z",44 "authorized_date": "2023-09-22",45 "authorized_datetime": "2023-09-22T10:34:50Z",46 "location": {47 "address": "13425 Community Rd",48 "city": "Poway",49 "region": "CA",50 "postal_code": "92064",51 "country": "US",52 "lat": 32.959068,53 "lon": -117.037666,54 "store_number": "1700"55 },56 "name": "PURCHASE WM SUPERCENTER #1700",57 "merchant_name": "Walmart",58 "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",59 "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",60 "website": "walmart.com",61 "payment_meta": {62 "by_order_of": null,63 "payee": null,64 "payer": null,65 "payment_method": null,66 "payment_processor": null,67 "ppd_id": null,68 "reason": null,69 "reference_number": null70 },71 "payment_channel": "in store",72 "pending": false,73 "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",74 "personal_finance_category": {75 "primary": "GENERAL_MERCHANDISE",76 "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",77 "confidence_level": "VERY_HIGH"78 },79 "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",80 "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",81 "transaction_code": null,82 "transaction_type": "place"83 }84 ],85 "modified": [86 {87 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",88 "account_owner": null,89 "amount": 28.34,90 "iso_currency_code": "USD",91 "unofficial_currency_code": null,92 "category": [93 "Food and Drink",94 "Restaurants",95 "Fast Food"96 ],97 "category_id": "13005032",98 "check_number": null,99 "counterparties": [100 {101 "name": "DoorDash",102 "type": "marketplace",103 "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",104 "website": "doordash.com",105 "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",106 "confidence_level": "HIGH"107 },108 {109 "name": "Burger King",110 "type": "merchant",111 "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",112 "website": "burgerking.com",113 "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",114 "confidence_level": "VERY_HIGH"115 }116 ],117 "date": "2023-09-28",118 "datetime": "2023-09-28T15:10:09Z",119 "authorized_date": "2023-09-27",120 "authorized_datetime": "2023-09-27T08:01:58Z",121 "location": {122 "address": null,123 "city": null,124 "region": null,125 "postal_code": null,126 "country": null,127 "lat": null,128 "lon": null,129 "store_number": null130 },131 "name": "Dd Doordash Burgerkin",132 "merchant_name": "Burger King",133 "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",134 "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",135 "website": "burgerking.com",136 "payment_meta": {137 "by_order_of": null,138 "payee": null,139 "payer": null,140 "payment_method": null,141 "payment_processor": null,142 "ppd_id": null,143 "reason": null,144 "reference_number": null145 },146 "payment_channel": "online",147 "pending": true,148 "pending_transaction_id": null,149 "personal_finance_category": {150 "primary": "FOOD_AND_DRINK",151 "detailed": "FOOD_AND_DRINK_FAST_FOOD",152 "confidence_level": "VERY_HIGH"153 },154 "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",155 "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",156 "transaction_code": null,157 "transaction_type": "digital"158 }159 ],160 "removed": [161 {162 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",163 "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"164 }165 ],166 "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV",167 "has_more": false,168 "request_id": "Wvhy9PZHQLV8njG",169 "transactions_update_status": "HISTORICAL_UPDATE_COMPLETE"170}
Was this helpful?
/transactions/get
Get transaction data
Note: All new implementations are encouraged to use /transactions/sync
rather than /transactions/get
. /transactions/sync
provides the same functionality as /transactions/get
and improves developer ease-of-use for handling transactions updates.
The /transactions/get
endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype student
; coverage may be limited). For transaction history from investments accounts, use the Investments endpoint instead. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.
Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in /transactions/get
. For more details, see Pending and posted transactions.
Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the count
and offset
parameters in conjunction with the total_transactions
response body field to fetch all available transactions.
Data returned by /transactions/get
will be the data available for the Item as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To find out when the Item was last updated, use the Item Debugger or call /item/get
; the item.status.transactions.last_successful_update
field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, you can use the /transactions/refresh
endpoint.
Note that data may not be immediately available to /transactions/get
. Plaid will begin to prepare transactions data upon Item link, if Link was initialized with transactions
, or upon the first call to /transactions/get
, if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the INITIAL_UPDATE
and HISTORICAL_UPDATE
webhooks. If no transaction history is ready when /transactions/get
is called, it will return a PRODUCT_NOT_READY
error.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.options
options
must not be null
.account_ids
account_ids
to retrieve for the ItemNote: An error will be returned if a provided
account_id
is not associated with the Item.count
100
1
500
false
offset
0
0
include_original _description
false
days_requested
transactions
in the products
, optional_products
, or required_if_consented_products
array when calling /link/token/create
or by making a previous call to /transactions/sync
or /transactions/get
). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. If a value under 30 is provided, a minimum of 30 days of history will be requested.If you are initializing your Items with transactions during the
/link/token/create
call (e.g. by including transactions
in the /link/token/create
products
array), you must use the transactions.days_requested
field in the /link/token/create
request instead of in the /transactions/get
request.If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via
/item/remove
and send the user through Link to create a new Item. Customers using Recurring Transactions should request at least 180 days of history for optimal results.
1
730
90
access_token
secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.start_date
date
end_date
date
1const request: TransactionsGetRequest = {2 access_token: accessToken,3 start_date: '2018-01-01',4 end_date: '2020-02-01'5};6try {7 const response = await client.transactionsGet(request);8 let transactions = response.data.transactions;9 const total_transactions = response.data.total_transactions;10 // Manipulate the offset parameter to paginate11 // transactions and retrieve all available data12 while (transactions.length < total_transactions) {13 const paginatedRequest: TransactionsGetRequest = {14 access_token: accessToken,15 start_date: '2018-01-01',16 end_date: '2020-02-01',17 options: {18 offset: transactions.length19 },20 };21 const paginatedResponse = await client.transactionsGet(paginatedRequest);22 transactions = transactions.concat(23 paginatedResponse.data.transactions,24 );25 }26} catch((err) => {27 // handle error28}
Response fields and example
accounts
accounts
associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account_id
field.account_id
account_id
will be assigned to the account.The
account_id
can also change if the access_token
is deleted and the same credentials that were used to generate that access_token
are used to generate a new access_token
on a later date. In that case, the new account_id
will be different from the old account_id
.If an account with a specific
account_id
disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.Like all Plaid identifiers, the
account_id
is case sensitive.balances
/accounts/balance/get
.available
For
credit
-type accounts, the available
balance typically equals the limit
less the current
balance, less any pending outflows plus any pending inflows.For
depository
-type accounts, the available
balance typically equals the current
balance less any pending outflows plus any pending inflows. For depository
-type accounts, the available
balance does not include the overdraft limit.For
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier), the available
balance is the total cash available to withdraw as presented by the institution.Note that not all institutions calculate the
available
balance. In the event that available
balance is unavailable, Plaid will return an available
balance value of null
.Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by
/accounts/balance/get
.If
current
is null
this field is guaranteed not to be null
.double
current
For
credit
-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.For
loan
-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944
). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.For
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.Note that balance information may be cached unless the value was returned by
/accounts/balance/get
; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available
balance as provided by /accounts/balance/get
.When returned by
/accounts/balance/get
, this field may be null
. When this happens, available
is guaranteed not to be null
.double
limit
credit
-type accounts, this represents the credit limit.For
depository
-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.In North America, this field is typically only available for
credit
-type accounts.double
iso_currency_code
unofficial_currency_code
is non-null.unofficial_currency _code
iso_currency_code
is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
unofficial_currency_code
s.last_updated_datetime
YYYY-MM-DDTHH:mm:ssZ
) indicating the oldest acceptable balance when making a request to /accounts/balance/get
.This field is only used and expected when the institution is
ins_128026
(Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID_REQUEST
error with the code of INVALID_FIELD
will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types.If the balance that is pulled is older than the given timestamp for Items with this field required, an
INVALID_REQUEST
error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE
will be returned with the most recent timestamp for the requested account contained in the response.date-time
mask
name
official_name
type
investment:
Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage
instead.credit:
Credit carddepository:
Depository accountloan:
Loan accountother:
Non-specified account typeSee the Account type schema for a full listing of account types and corresponding subtypes.
investment
, credit
, depository
, loan
, brokerage
, other
subtype
401a
, 401k
, 403B
, 457b
, 529
, auto
, brokerage
, business
, cash isa
, cash management
, cd
, checking
, commercial
, construction
, consumer
, credit card
, crypto exchange
, ebt
, education savings account
, fixed annuity
, gic
, health reimbursement arrangement
, home equity
, hsa
, isa
, ira
, keogh
, lif
, life insurance
, line of credit
, lira
, loan
, lrif
, lrsp
, money market
, mortgage
, mutual fund
, non-custodial wallet
, non-taxable brokerage account
, other
, other insurance
, other annuity
, overdraft
, paypal
, payroll
, pension
, prepaid
, prif
, profit sharing plan
, rdsp
, resp
, retirement
, rlif
, roth
, roth 401k
, rrif
, rrsp
, sarsep
, savings
, sep ira
, simple ira
, sipp
, stock plan
, student
, thrift savings plan
, tfsa
, trust
, ugma
, utma
, variable annuity
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit.automatically_verified
: The Item has successfully been automatically verified manually_verified
: The Item has successfully been manually verifiedverification_expired
: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.verification_failed
: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.database_matched
: The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match.database_insights_pass
: The Item's numbers have been verified using Plaid's data sources and have strong signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.database_insights_pass_with_caution
: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.database_insights_fail
: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Only returned for Auth Items created via Database Insights. Note: Database Insights is currently a beta feature, please contact your account manager for more information.automatically_verified
, pending_automatic_verification
, pending_manual_verification
, manually_verified
, verification_expired
, verification_failed
, database_matched
, database_insights_pass
, database_insights_pass_with_caution
, database_insights_fail
verification_insights
network_status
has_numbers_match
is_numbers_match _verified
previous_returns
has_previous _administrative_return
account_number_format
valid
: indicates that the account number has a correct format for the institution.invalid
: indicates that the account number has an incorrect format for the institution.unknown
: indicates that there was not enough information to determine whether the format is correct for the institution.valid
, invalid
, unknown
persistent_account_id
holder_category
business
, personal
, unrecognized
transactions
count
parameter.account_id
amount
iso_currency_code
or unofficial_currency_code
. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income.double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_code
s.category
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.category_id
/categories/get
.All Transactions implementations are recommended to use the new
personal_finance_category
instead of category
, as it provides greater accuracy and more meaningful categorization.If the
transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.check_number
date
YYYY-MM-DD
). To receive information about the date that a posted transaction was initiated, see the authorized_date
field.date
location
address
city
region
state
.postal_code
zip
.country
lat
double
lon
double
store_number
name
Note: This is a legacy field that is not actively maintained. Use
merchant_name
instead for the merchant name.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, this field will always appear. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.merchant_name
name
field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null
.original_description
/transactions/sync
or /transactions/get
, this field will only be included if the client has set options.include_original_description
to true
.payment_meta
null
.If the
transactions
object was returned by a Transactions endpoint such as /transactions/sync
or /transactions/get
, the payment_meta
key will always appear, but no data elements are guaranteed. If the transactions
object was returned by an Assets endpoint such as /asset_report/get/
or /asset_report/pdf/get
, this field will only appear in an Asset Report with Insights.reference_number
ppd_id
payee
by_order_of
null
if the transaction is not a wire transfer.payer
payment_method
payment_processor
reason
pending
true
, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions.pending_transaction_id
account_owner
transaction_id
transaction_id
is case sensitive.transaction_type
payment_channel
field, transaction_type
will be deprecated in the future.digital:
transactions that took place online.place:
transactions that were made at a physical location.special:
transactions that relate to banks, e.g. fees or deposits.unresolved:
transactions that do not fit into the other three types.digital
, place
, special
, unresolved
logo_url
website
authorized_date
date
field will indicate the posted date, but authorized_date
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_date
, when available, is generally preferable to use over the date
field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an ISO 8601 format ( YYYY-MM-DD
).date
authorized_datetime
YYYY-MM-DDTHH:mm:ssZ
). For posted transactions, the datetime
field will indicate the posted date, but authorized_datetime
will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the authorized_datetime
, when available, is generally preferable to use over the datetime
field for posted transactions, as it will generally represent the date the user actually made the transaction.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
datetime
YYYY-MM-DDTHH:mm:ssZ
). For the date that the transaction was initiated, rather than posted, see the authorized_datetime
field.This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later.
date-time
payment_channel
online:
transactions that took place online.in store:
transactions that were made at a physical location.other:
transactions that relate to banks, e.g. fees or deposits.This field replaces the
transaction_type
field.online
, in store
, other
personal_finance _category
See the
taxonomy CSV file
for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide
.primary
detailed
confidence_level
VERY_HIGH
: We are more than 98% confident that this category reflects the intent of the transaction.
HIGH
: We are more than 90% confident that this category reflects the intent of the transaction.
MEDIUM
: We are moderately confident that this category reflects the intent of the transaction.
LOW
: This category may reflect the intent, but there may be other categories that are more accurate.
UNKNOWN
: We don’t know the confidence level for this category.transaction_code
This field is only populated for European institutions. For institutions in the US and Canada, this field is set to
null
.adjustment:
Bank adjustmentatm:
Cash deposit or withdrawal via an automated teller machinebank charge:
Charge or fee levied by the institutionbill payment
: Payment of a billcash:
Cash deposit or withdrawalcashback:
Cash withdrawal while making a debit card purchasecheque:
Document ordering the payment of money to another person or organizationdirect debit:
Automatic withdrawal of funds initiated by a third party at a regular intervalinterest:
Interest earned or incurredpurchase:
Purchase made with a debit or credit cardstanding order:
Payment instructed by the account holder to a third party at a regular intervaltransfer:
Transfer of money between accountsadjustment
, atm
, bank charge
, bill payment
, cash
, cashback
, cheque
, direct debit
, interest
, purchase
, standing order
, transfer
, null
personal_finance _category_icon_url
counterparties
name
entity_id
type
merchant
: a provider of goods or services for purchase
financial_institution
: a financial entity (bank, credit union, BNPL, fintech)
payment_app
: a transfer or P2P app (e.g. Zelle)
marketplace
: a marketplace (e.g DoorDash, Google Play Store)
payment_terminal
: a point-of-sale payment terminal (e.g Square, Toast)
income_source
: the payer in an income transaction (e.g., an employer, client, or government agency)merchant
, financial_institution
, payment_app
, marketplace
, payment_terminal
, income_source
website
logo_url
confidence_level
VERY_HIGH
: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction.
HIGH
: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction.
MEDIUM
: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records.
LOW
: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description.
UNKNOWN
: We don’t know the confidence level for this counterparty.merchant_entity_id
total_transactions
total_transactions
is larger than the size of the transactions
array, more transactions are available and can be fetched via manipulating the offset
parameter.item
item_id
item_id
is always unique; linking the same account at the same institution twice will result in two Items with different item_id
values. Like all Plaid identifiers, the item_id
is case-sensitive.institution_id
null
for Items created via Same Day Micro-deposits.webhook
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
available_products
billed_products
.assets
, auth
, balance
, balance_plus
, beacon
, identity
, identity_match
, investments
, investments_auth
, liabilities
, payment_initiation
, identity_verification
, transactions
, credit_details
, income
, income_verification
, standing_orders
, transfer
, employment
, recurring_transactions
, signal
, statements
, processor_payments
, processor_identity
, profile
, cra_base_report
, cra_income_insights
, cra_partner_insights
, cra_network_insights
, cra_cashflow_insights
, layer
, pay_by_bank
billed_products
available_products
. Note - billed_products
is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance
, will not appear here.assets
, auth
, balance
, balance_plus
, beacon
, identity
, identity_match
, investments
, investments_auth
, liabilities
, payment_initiation
, identity_verification
, transactions
, credit_details
, income
, income_verification
, standing_orders
, transfer
, employment
, recurring_transactions
, signal
, statements
, processor_payments
, processor_identity
, profile
, cra_base_report
, cra_income_insights
, cra_partner_insights
, cra_network_insights
, cra_cashflow_insights
, layer
, pay_by_bank
products
billed_products
field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset_report/create
has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products
but not in billed_products
.assets
, auth
, balance
, balance_plus
, beacon
, identity
, identity_match
, investments
, investments_auth
, liabilities
, payment_initiation
, identity_verification
, transactions
, credit_details
, income
, income_verification
, standing_orders
, transfer
, employment
, recurring_transactions
, signal
, statements
, processor_payments
, processor_identity
, profile
, cra_base_report
, cra_income_insights
, cra_partner_insights
, cra_network_insights
, cra_cashflow_insights
, layer
, pay_by_bank
consented_products
assets
, auth
, balance
, balance_plus
, beacon
, identity
, identity_match
, investments
, investments_auth
, liabilities
, transactions
, income
, income_verification
, transfer
, employment
, recurring_transactions
, signal
, statements
, processor_payments
, processor_identity
, cra_base_report
, cra_income_insights
, cra_partner_insights
, cra_cashflow_insights
, layer
consent_expiration _time
date-time
update_type
background
- Item can be updated in the backgrounduser_present_required
- Item requires user interaction to be updatedbackground
, user_present_required
request_id
1{2 "accounts": [3 {4 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",5 "balances": {6 "available": 110.94,7 "current": 110.94,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "0000",13 "name": "Plaid Checking",14 "official_name": "Plaid Gold Standard 0% Interest Checking",15 "subtype": "checking",16 "type": "depository"17 }18 ],19 "transactions": [20 {21 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",22 "account_owner": null,23 "amount": 28.34,24 "iso_currency_code": "USD",25 "unofficial_currency_code": null,26 "category": [27 "Food and Drink",28 "Restaurants",29 "Fast Food"30 ],31 "category_id": "13005032",32 "check_number": null,33 "counterparties": [34 {35 "name": "DoorDash",36 "type": "marketplace",37 "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png",38 "website": "doordash.com",39 "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm",40 "confidence_level": "HIGH"41 },42 {43 "name": "Burger King",44 "type": "merchant",45 "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",46 "website": "burgerking.com",47 "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",48 "confidence_level": "VERY_HIGH"49 }50 ],51 "date": "2023-09-28",52 "datetime": "2023-09-28T15:10:09Z",53 "authorized_date": "2023-09-27",54 "authorized_datetime": "2023-09-27T08:01:58Z",55 "location": {56 "address": null,57 "city": null,58 "region": null,59 "postal_code": null,60 "country": null,61 "lat": null,62 "lon": null,63 "store_number": null64 },65 "name": "Dd Doordash Burgerkin",66 "merchant_name": "Burger King",67 "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1",68 "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png",69 "website": "burgerking.com",70 "payment_meta": {71 "by_order_of": null,72 "payee": null,73 "payer": null,74 "payment_method": null,75 "payment_processor": null,76 "ppd_id": null,77 "reason": null,78 "reference_number": null79 },80 "payment_channel": "online",81 "pending": true,82 "pending_transaction_id": null,83 "personal_finance_category": {84 "primary": "FOOD_AND_DRINK",85 "detailed": "FOOD_AND_DRINK_FAST_FOOD",86 "confidence_level": "VERY_HIGH"87 },88 "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png",89 "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",90 "transaction_code": null,91 "transaction_type": "digital"92 },93 {94 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",95 "account_owner": null,96 "amount": 72.1,97 "iso_currency_code": "USD",98 "unofficial_currency_code": null,99 "category": [100 "Shops",101 "Supermarkets and Groceries"102 ],103 "category_id": "19046000",104 "check_number": null,105 "counterparties": [106 {107 "name": "Walmart",108 "type": "merchant",109 "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",110 "website": "walmart.com",111 "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",112 "confidence_level": "VERY_HIGH"113 }114 ],115 "date": "2023-09-24",116 "datetime": "2023-09-24T11:01:01Z",117 "authorized_date": "2023-09-22",118 "authorized_datetime": "2023-09-22T10:34:50Z",119 "location": {120 "address": "13425 Community Rd",121 "city": "Poway",122 "region": "CA",123 "postal_code": "92064",124 "country": "US",125 "lat": 32.959068,126 "lon": -117.037666,127 "store_number": "1700"128 },129 "name": "PURCHASE WM SUPERCENTER #1700",130 "merchant_name": "Walmart",131 "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM",132 "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png",133 "website": "walmart.com",134 "payment_meta": {135 "by_order_of": null,136 "payee": null,137 "payer": null,138 "payment_method": null,139 "payment_processor": null,140 "ppd_id": null,141 "reason": null,142 "reference_number": null143 },144 "payment_channel": "in store",145 "pending": false,146 "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",147 "personal_finance_category": {148 "primary": "GENERAL_MERCHANDISE",149 "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",150 "confidence_level": "VERY_HIGH"151 },152 "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png",153 "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",154 "transaction_code": null,155 "transaction_type": "place"156 }157 ],158 "item": {159 "available_products": [160 "balance",161 "identity",162 "investments"163 ],164 "billed_products": [165 "assets",166 "auth",167 "liabilities",168 "transactions"169 ],170 "consent_expiration_time": null,171 "error": null,172 "institution_id": "ins_3",173 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",174 "update_type": "background",175 "webhook": "https://www.genericwebhookurl.com/webhook"176 },177 "total_transactions": 1,178 "request_id": "45QSn"179}
Was this helpful?
/transactions/recurring/get
Fetch recurring transaction streams
The /transactions/recurring/get
endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments.
This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
This endpoint can only be called on an Item that has already been initialized with Transactions (either during Link, by specifying it in /link/token/create
; or after Link, by calling /transactions/get
or /transactions/sync
).
When using Recurring Transactions, for best results, make sure to use the days_requested
parameter to request at least 180 days of history when initializing Items with Transactions. Once all historical transactions have been fetched, call /transactions/recurring/get
to receive the Recurring Transactions streams and subscribe to the RECURRING_TRANSACTIONS_UPDATE
webhook. To know when historical transactions have been fetched, if you are using /transactions/sync
listen for the SYNC_UPDATES_AVAILABLE
webhook and check that the historical_update_complete
field in the payload is true
. If using /transactions/get
, listen for the HISTORICAL_UPDATE
webhook.
After the initial call, you can call /transactions/recurring/get
endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the RECURRING_TRANSACTIONS_UPDATE
webhook to be notified when new updates are available.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.access_token
secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.account_ids
account_ids
to retrieve for the Item. Retrieves all active accounts on item if no account_id
s are provided.Note: An error will be returned if a provided
account_id
is not associated with the Item.1const request: TransactionsGetRequest = {2 access_token: accessToken,3 account_ids : accountIds4};5try {6 const response = await client.transactionsRecurringGet(request);7 let inflowStreams = response.data.inflowStreams;8 let outflowStreams = response.data.outflowStreams;9 }10} catch((err) => {11 // handle error12}
Response fields and example
inflow_streams
account_id
stream_id
category
All implementations are encouraged to use the new
personal_finance_category
instead of category
. personal_finance_category
provides more meaningful categorization and greater accuracy.category_id
All implementations are encouraged to use the new
personal_finance_category
instead of category
. personal_finance_category
provides more meaningful categorization and greater accuracy.description
merchant_name
first_date
date
last_date
date
predicted_next_date
date
frequency
WEEKLY
: Assigned to a transaction stream that occurs approximately every week.BIWEEKLY
: Assigned to a transaction stream that occurs approximately every 2 weeks.SEMI_MONTHLY
: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.MONTHLY
: Assigned to a transaction stream that occurs approximately every month.ANNUALLY
: Assigned to a transaction stream that occurs approximately every year.UNKNOWN
: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.UNKNOWN
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
, ANNUALLY
transaction_ids
average_amount
amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.See the currency code schema for a full listing of supported
iso_currency_code
s.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.last_amount
amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.See the currency code schema for a full listing of supported
iso_currency_code
s.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.is_active
status
MATURE
: A MATURE
recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE
after 2 instances).EARLY_DETECTION
: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION
.TOMBSTONED
: A stream that was previously in the EARLY_DETECTION
status will move to the TOMBSTONED
status when no further transactions were found at the next expected date.UNKNOWN
: A stream is assigned an UNKNOWN
status when none of the other statuses are applicable.UNKNOWN
, MATURE
, EARLY_DETECTION
, TOMBSTONED
personal_finance _category
See the
taxonomy CSV file
for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide
.primary
detailed
confidence_level
VERY_HIGH
: We are more than 98% confident that this category reflects the intent of the transaction.
HIGH
: We are more than 90% confident that this category reflects the intent of the transaction.
MEDIUM
: We are moderately confident that this category reflects the intent of the transaction.
LOW
: This category may reflect the intent, but there may be other categories that are more accurate.
UNKNOWN
: We don’t know the confidence level for this category.is_user_modified
true
if the stream has been modified by request to a /transactions/recurring/streams
endpoint. It will be false
for all other streams.last_user_modified _datetime
is_user_modified
is true
.date-time
outflow_streams
account_id
stream_id
category
All implementations are encouraged to use the new
personal_finance_category
instead of category
. personal_finance_category
provides more meaningful categorization and greater accuracy.category_id
All implementations are encouraged to use the new
personal_finance_category
instead of category
. personal_finance_category
provides more meaningful categorization and greater accuracy.description
merchant_name
first_date
date
last_date
date
predicted_next_date
date
frequency
WEEKLY
: Assigned to a transaction stream that occurs approximately every week.BIWEEKLY
: Assigned to a transaction stream that occurs approximately every 2 weeks.SEMI_MONTHLY
: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams.MONTHLY
: Assigned to a transaction stream that occurs approximately every month.ANNUALLY
: Assigned to a transaction stream that occurs approximately every year.UNKNOWN
: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.UNKNOWN
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
, ANNUALLY
transaction_ids
average_amount
amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.See the currency code schema for a full listing of supported
iso_currency_code
s.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.last_amount
amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.See the currency code schema for a full listing of supported
iso_currency_code
s.unofficial_currency _code
null
if iso_currency_code
is non-null
. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.is_active
status
MATURE
: A MATURE
recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it MATURE
after 2 instances).EARLY_DETECTION
: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be EARLY_DETECTION
.TOMBSTONED
: A stream that was previously in the EARLY_DETECTION
status will move to the TOMBSTONED
status when no further transactions were found at the next expected date.UNKNOWN
: A stream is assigned an UNKNOWN
status when none of the other statuses are applicable.UNKNOWN
, MATURE
, EARLY_DETECTION
, TOMBSTONED
personal_finance _category
See the
taxonomy CSV file
for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the migration guide
.primary
detailed
confidence_level
VERY_HIGH
: We are more than 98% confident that this category reflects the intent of the transaction.
HIGH
: We are more than 90% confident that this category reflects the intent of the transaction.
MEDIUM
: We are moderately confident that this category reflects the intent of the transaction.
LOW
: This category may reflect the intent, but there may be other categories that are more accurate.
UNKNOWN
: We don’t know the confidence level for this category.is_user_modified
true
if the stream has been modified by request to a /transactions/recurring/streams
endpoint. It will be false
for all other streams.last_user_modified _datetime
is_user_modified
is true
.date-time
updated_datetime
YYYY-MM-DDTHH:mm:ssZ
) indicating the last time transaction streams for the given account were updated ondate-time
request_id
1{2 "updated_datetime": "2022-05-01T00:00:00Z",3 "inflow_streams": [4 {5 "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",6 "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc",7 "category": [8 "Transfer",9 "Payroll"10 ],11 "category_id": "21009000",12 "description": "Platypus Payroll",13 "merchant_name": null,14 "personal_finance_category": {15 "primary": "INCOME",16 "detailed": "INCOME_WAGES",17 "confidence_level": "UNKNOWN"18 },19 "first_date": "2022-02-28",20 "last_date": "2022-04-30",21 "predicted_next_date": "2022-05-15",22 "frequency": "SEMI_MONTHLY",23 "transaction_ids": [24 "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw",25 "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL",26 "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd",27 "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK",28 "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF"29 ],30 "average_amount": {31 "amount": -800,32 "iso_currency_code": "USD",33 "unofficial_currency_code": null34 },35 "last_amount": {36 "amount": -1000,37 "iso_currency_code": "USD",38 "unofficial_currency_code": null39 },40 "is_active": true,41 "status": "MATURE",42 "is_user_modified": true,43 "last_user_modified_datetime": "2023-01-19T10:34:50Z"44 }45 ],46 "outflow_streams": [47 {48 "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",49 "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd",50 "category": [51 "Service",52 "Utilities",53 "Electric"54 ],55 "category_id": "18068005",56 "description": "ConEd Bill Payment",57 "merchant_name": "ConEd",58 "personal_finance_category": {59 "primary": "RENT_AND_UTILITIES",60 "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY",61 "confidence_level": "UNKNOWN"62 },63 "first_date": "2022-02-04",64 "last_date": "2022-05-02",65 "predicted_next_date": "2022-06-02",66 "frequency": "MONTHLY",67 "transaction_ids": [68 "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0",69 "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR",70 "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L",71 "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l"72 ],73 "average_amount": {74 "amount": 85,75 "iso_currency_code": "USD",76 "unofficial_currency_code": null77 },78 "last_amount": {79 "amount": 100,80 "iso_currency_code": "USD",81 "unofficial_currency_code": null82 },83 "is_active": true,84 "status": "MATURE",85 "is_user_modified": false86 },87 {88 "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff",89 "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC",90 "category": [91 "Shops",92 "Warehouses and Wholesale Stores"93 ],94 "category_id": "19051000",95 "description": "Costco Annual Membership",96 "merchant_name": "Costco",97 "personal_finance_category": {98 "primary": "GENERAL_MERCHANDISE",99 "detailed": "GENERAL_MERCHANDISE_SUPERSTORES",100 "confidence_level": "UNKNOWN"101 },102 "first_date": "2022-01-23",103 "last_date": "2023-01-22",104 "predicted_next_date": "2024-01-22",105 "frequency": "ANNUALLY",106 "transaction_ids": [107 "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4",108 "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ"109 ],110 "average_amount": {111 "amount": 120,112 "iso_currency_code": "USD",113 "unofficial_currency_code": null114 },115 "last_amount": {116 "amount": 120,117 "iso_currency_code": "USD",118 "unofficial_currency_code": null119 },120 "is_active": true,121 "status": "MATURE",122 "is_user_modified": true,123 "last_user_modified_datetime": "2023-01-19T10:34:50Z"124 }125 ],126 "request_id": "tbFyCEqkU775ZGG"127}
Was this helpful?
/transactions/refresh
Refresh transaction data
/transactions/refresh
is an optional endpoint that initiates an on-demand extraction to fetch the newest transactions for an Item. The on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Transactions-enabled Item. The Item must already have Transactions added as a product in order to call /transactions/refresh
.
If changes to transactions are discovered after calling /transactions/refresh
, Plaid will fire a webhook: for /transactions/sync
users, SYNC_UPDATES_AVAILABLE
will be fired if there are any transactions updated, added, or removed. For users of both /transactions/sync
and /transactions/get
, TRANSACTIONS_REMOVED
will be fired if any removed transactions are detected, and DEFAULT_UPDATE
will be fired if any new transactions are detected. New transactions can be fetched by calling /transactions/get
or /transactions/sync
.
Note that the /transactions/refresh
endpoint is not supported for Capital One (ins_128026
) non-depository accounts and will result in a PRODUCTS_NOT_SUPPORTED
error if called on an Item that contains only non-depository accounts from that institution.
As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests./transactions/refresh
is offered as an optional add-on to Transactions and has a separate fee model. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.access_token
secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.1const request: TransactionsRefreshRequest = {2 access_token: accessToken,3};4try {5 await plaidClient.transactionsRefresh(request);6} catch (error) {7 // handle error8}
Response fields and example
request_id
1{2 "request_id": "1vwmF5TBQwiqfwP"3}
Was this helpful?
/categories/get
Get categories
Send a request to the /categories/get
endpoint to get detailed information on categories returned by Plaid. This endpoint does not require authentication.
All implementations are recommended to use the newer personal_finance_category
taxonomy instead of the older category
taxonomy supported by this endpoint. The personal_finance_category taxonomy
CSV file is available for download and is not accessible via API.
1try {2 const response = await plaidClient.categoriesGet({});3 const categories = response.data.categories;4} catch (error) {5 // handle error6}
Response fields and example
categories
category_id
category_id
is a Plaid-specific identifier and does not necessarily correspond to merchant category codes.group
place
for physical transactions or special
for other transactions such as bank charges.hierarchy
category_id
belongs.request_id
1{2 "categories": [3 {4 "category_id": "10000000",5 "group": "special",6 "hierarchy": [7 "Bank Fees"8 ]9 },10 {11 "category_id": "10001000",12 "group": "special",13 "hierarchy": [14 "Bank Fees",15 "Overdraft"16 ]17 },18 {19 "category_id": "12001000",20 "group": "place",21 "hierarchy": [22 "Community",23 "Animal Shelter"24 ]25 }26 ],27 "request_id": "ixTBLZGvhD4NnmB"28}
Was this helpful?
Webhooks
You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid’s initial and historical transaction pull are completed. All webhooks related to transactions have a webhook_type
of TRANSACTIONS
.
SYNC_UPDATES_AVAILABLE
Fired when an Item's transactions change. This can be due to any event resulting in new changes, such as an initial 30-day transactions fetch upon the initialization of an Item with transactions, the backfill of historical transactions that occurs shortly after, or when changes are populated from a regularly-scheduled transactions update job. It is recommended to listen for the SYNC_UPDATES_AVAILABLE
webhook when using the /transactions/sync
endpoint. Note that when using /transactions/sync
the older webhooks INITIAL_UPDATE
, HISTORICAL_UPDATE
, DEFAULT_UPDATE
, and TRANSACTIONS_REMOVED
, which are intended for use with /transactions/get
, will also continue to be sent in order to maintain backwards compatibility. It is not necessary to listen for and respond to those webhooks when using /transactions/sync
.
After receipt of this webhook, the new changes can be fetched for the Item from /transactions/sync
.
Note that to receive this webhook for an Item, /transactions/sync
must have been called at least once on that Item. This means that, unlike the INITIAL_UPDATE
and HISTORICAL_UPDATE
webhooks, it will not fire immediately upon Item creation. If /transactions/sync
is called on an Item that was not initialized with Transactions, the webhook will fire twice: once the first 30 days of transactions data has been fetched, and a second time when all available historical transactions data has been fetched.
This webhook will fire in the Sandbox environment as it would in Production. It can also be manually triggered in Sandbox by calling /sandbox/item/fire_webhook
.
webhook_type
TRANSACTIONS
webhook_code
SYNC_UPDATES_AVAILABLE
item_id
item_id
of the Item associated with this webhook, warning, or errorinitial_update _complete
historical_update _complete
environment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "SYNC_UPDATES_AVAILABLE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "initial_update_complete": true,6 "historical_update_complete": false,7 "environment": "production"8}
Was this helpful?
RECURRING_TRANSACTIONS_UPDATE
Fired when recurring transactions data is updated. This includes when a new recurring stream is detected or when a new transaction is added to an existing recurring stream. The RECURRING_TRANSACTIONS_UPDATE
webhook will also fire when one or more attributes of the recurring stream changes, which is usually a result of the addition, update, or removal of transactions to the stream.
After receipt of this webhook, the updated data can be fetched from /transactions/recurring/get
.
webhook_type
TRANSACTIONS
webhook_code
RECURRING_TRANSACTIONS_UPDATE
item_id
item_id
of the Item associated with this webhook, warning, or erroraccount_ids
account_ids
for accounts that have new or updated recurring transactions data.environment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "RECURRING_TRANSACTIONS_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "account_ids": [6 "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",7 "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff"8 ],9 "environment": "production"10}
Was this helpful?
INITIAL_UPDATE
Fired when an Item's initial transaction pull is completed. Once this webhook has been fired, transaction data for the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with new_transactions
set to the number of net new transactions pulled after the account selection update.
This webhook is intended for use with /transactions/get
; if you are using the newer /transactions/sync
endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE
webhook instead.
webhook_type
TRANSACTIONS
webhook_code
INITIAL_UPDATE
error
new_transactions
item_id
item_id
of the Item associated with this webhook, warning, or errorenvironment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "INITIAL_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "new_transactions": 19,7 "environment": "production"8}
Was this helpful?
HISTORICAL_UPDATE
Fired when an Item's historical transaction pull is completed and Plaid has prepared as much historical transaction data as possible for the Item. Once this webhook has been fired, transaction data beyond the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with new_transactions
set to the number of net new transactions pulled after the account selection update.
This webhook is intended for use with /transactions/get
; if you are using the newer /transactions/sync
endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE
webhook instead.
webhook_type
TRANSACTIONS
webhook_code
HISTORICAL_UPDATE
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
new_transactions
item_id
item_id
of the Item associated with this webhook, warning, or errorenvironment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "HISTORICAL_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "new_transactions": 231,7 "environment": "production"8}
Was this helpful?
DEFAULT_UPDATE
Fired when new transaction data is available for an Item. Plaid will typically check for new transaction data several times a day.
This webhook is intended for use with /transactions/get
; if you are using the newer /transactions/sync
endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE
webhook instead.
webhook_type
TRANSACTIONS
webhook_code
DEFAULT_UPDATE
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
new_transactions
item_id
item_id
of the Item the webhook relates to.environment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "DEFAULT_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "new_transactions": 3,7 "environment": "production"8}
Was this helpful?
TRANSACTIONS_REMOVED
Fired when transaction(s) for an Item are deleted. The deleted transaction IDs are included in the webhook payload. Plaid will typically check for deleted transaction data several times a day.
This webhook is intended for use with /transactions/get
; if you are using the newer /transactions/sync
endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the SYNC_UPDATES_AVAILABLE
webhook instead.
webhook_type
TRANSACTIONS
webhook_code
TRANSACTIONS_REMOVED
error
error_code
and categorized by error_type
. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null
error object will only be part of an API response when calling /item/get
to view Item status. Otherwise, error fields will be null
if no error has occurred; if an error has occurred, an error code will be returned instead.error_type
INVALID_REQUEST
, INVALID_RESULT
, INVALID_INPUT
, INSTITUTION_ERROR
, RATE_LIMIT_EXCEEDED
, API_ERROR
, ITEM_ERROR
, ASSET_REPORT_ERROR
, RECAPTCHA_ERROR
, OAUTH_ERROR
, PAYMENT_ERROR
, BANK_TRANSFER_ERROR
, INCOME_VERIFICATION_ERROR
, MICRODEPOSITS_ERROR
, SANDBOX_ERROR
, PARTNER_ERROR
, TRANSACTIONS_ERROR
, TRANSACTION_ERROR
, TRANSFER_ERROR
error_code
error_code_reason
null
will be returned otherwise. Safe for programmatic use.Possible values:
OAUTH_INVALID_TOKEN
: The user’s OAuth connection to this institution has been invalidated.OAUTH_CONSENT_EXPIRED
: The user's access consent for this OAuth connection to this institution has expired.OAUTH_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
causes
will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes
will only be provided for the error_type
ASSET_REPORT_ERROR
. causes
will also not be populated inside an error nested within a warning
object.status
documentation_url
suggested_action
removed_transactions
transaction_ids
corresponding to the removed transactionsitem_id
item_id
of the Item associated with this webhook, warning, or errorenvironment
sandbox
, production
1{2 "webhook_type": "TRANSACTIONS",3 "webhook_code": "TRANSACTIONS_REMOVED",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "removed_transactions": [6 "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",7 "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"8 ],