Skip to main content
A refresh pulls the latest balances and transactions for an existing, healthy connection from the underlying service provider. This page is for developers deciding when and how to refresh — and when not to (most of the time, background refresh has you covered).

​
Before you begin

  • You have a connectionId for a connection that is not in RECONNECT_REQUIRED, EXPIRED, DELETED, or IN_PROGRESS (those statuses cannot be refreshed — see Connection Errors and Reasons)
  • You understand that forced refreshes can incur additional charges and may be rate-limited by the provider
  • You have webhooks configured so you can observe the resulting aggregation events

​
Automatic refreshes

Service providers typically refresh connection data (balances and transactions) once or a few times a day, and Meld pulls the latest data at that time. When Meld detects a change, you receive webhooks so you can fetch the latest data. You do not need to schedule refreshes yourself for routine freshness.

​
Forced refreshes

At any time you can call the refresh endpoint to force a live aggregation of all accounts on a connection. You can scope the refresh to specific products. Both forced and automatic refreshes produce webhooks.
Forced refreshes can incur additional charges and providers rate-limit them. For example, MX supports forced refresh only every 3 hours. Use forced refresh only when the customer just performed an action in your app that requires up-to-the-minute data.

​
How to refresh a connection

Call the refresh endpoint with the connectionId and (optionally) the list of products you want to refresh.
For the full request and response schema, refer to the Bank Linking API reference.
After the call returns, listen for the standard aggregation webhooks — BANK_LINKING_ACCOUNTS_UPDATED, BANK_LINKING_TRANSACTIONS_AGGREGATED — to know when fresh data is available.

​
Common errors

HTTP statusLikely causeDeveloper action
404 Not FoundInvalid connectionIdVerify the id and the environment (sandbox vs production).
409 ConflictConnection is in a status that cannot be refreshed (e.g. RECONNECT_REQUIRED, EXPIRED)Check the status; if RECONNECT_REQUIRED, send the customer through the repair flow instead.
429 Too ManyProvider rate limit hit (e.g. MX 3-hour limit)Back off and retry after the provider window. Do not loop on this error.
5xxTransient Meld or provider issueRetry with exponential backoff; if persistent, inspect the next BANK_LINKING_CONNECTION_STATUS_CHANGE webhook to see if the connection moved to DEGRADED or UNDETERMINED.