Over its lifetime, a connection may need to be refreshed, repaired, updated, deleted, or imported. This section is for developers building lifecycle handling on top of Meld bank linking. The four most-confused operations — refresh, repair, update, and import — all mutate the connection in different ways. The terminology matters: using the wrong endpoint will either no-op or charge for an operation that wasn’t needed.
Refresh vs. repair vs. update vs. delete vs. import
| Operation | What it does | When to use it | Customer involved? | Status before | Status after | Endpoint |
|---|
| Refresh | Pulls the latest balances and transactions from the underlying provider for an existing, healthy connection. | The customer just took an action in your app and you want up-to-the-minute data. Don’t use for routine polling — background refresh handles that. | No | ACTIVE, PARTIALLY_ACTIVE, DEGRADED, UNDETERMINED | Same status; new aggregation webhooks | Refreshing Connections |
| Repair | Generates a new connect token that takes the customer straight to the institution login so they can re-authenticate. Brings a broken connection back online. | The customer changed their bank password, MFA changed, or the provider consent expired. The connection moved to RECONNECT_REQUIRED. | Yes — they go through the widget again | RECONNECT_REQUIRED, DEGRADED, UNRECOVERABLE, or ACTIVE (when ACCESS_EXPIRING_SOON / NEW_ACCOUNTS_AVAILABLE) | ACTIVE | Repairing Connections |
| Update | Adds new products (e.g., INVESTMENT_HOLDINGS) to an existing connection. New products are added as optionalProducts and aggregated on a best-effort basis. | You initially requested BALANCES and TRANSACTIONS, and now you want investment data on the same connection without a fresh widget flow. | No (provider-dependent — may require repair flow) | Any non-terminal | Same status; new product aggregation kicks off | Updating Connection Products |
| Delete | Severs the connection on Meld and the underlying provider. No more webhooks, no more billing. Cannot be undone. | The customer no longer wants this account linked, or you are cleaning up duplicates. | No | Any | DELETED | Deleting Connections |
| Import | Brings an existing provider connection into Meld without sending the customer through the widget. | You already have Plaid or Akoya connections and you are migrating to Meld. | No | n/a (new in Meld) | ACTIVE | Importing Connections |
Quick guide
- Refresh a connection. Use for one-off data pulls. Background refreshes run automatically; do not refresh on a schedule from your code.
- Repair a connection. Use when the connection is in
RECONNECT_REQUIRED (or DEGRADED with a customer-actionable reason).
- Update a connection’s products. Use to add
BALANCES, INVESTMENT_HOLDINGS, etc. retroactively without re-prompting the customer.
- Delete a connection. Use when the customer revokes, when cleaning up duplicates, or when the institution is no longer supported.
- Import a connection. Use to migrate existing Plaid or Akoya connections into Meld.
Terminology matters. “Refresh” pulls new data on a working connection. “Repair” (sometimes called “reconnect”) fixes a broken connection by re-authenticating the customer. “Update” adds new products. These are distinct endpoints with distinct billing implications.
