/v1/ prefix, no X-API-Version header, no version pinning in your
account settings, and no scheduled migration to plan for. The API you integrated against today is the same API you’ll be
using next year.
That promise only holds if Treasury Prime is careful about how the API evolves, and if your integration is written with
a small amount of forward-looking discipline. This page covers both sides: what Treasury Prime treats as a breaking
change and what it doesn’t, how Treasury Prime handles the breaking changes that do end up being unavoidable, and what
your code should do to stay unaffected by as many of the changes as possible.
What this policy covers
If it’s documented, Treasury Prime treats it as part of the compatibility promise. That includes the REST endpoints in this reference, the webhook event types and payload schemas, and any behavior described in the public documentation: guides, individual reference pages, and the changelog. A few things sit outside the promise:- Undocumented fields and behavior. Responses sometimes include JSON fields that aren’t in the reference schema. These may be under development or have restricted use cases, and can change at any time. The same applies to any behavior not explicitly documented: field ordering, error message wording, and nullability patterns aren’t part of the contract unless the docs say they are. Don’t build against any of it.
- The Treasury Prime Console. The Console UI and any Console-only APIs are not covered by this policy.
- Anything marked beta or experimental. Preview features can change or disappear without notice while they’re in preview.
How Treasury Prime classifies changes
Every change to the API is in one of three buckets. The bucket determines whether Treasury Prime communicates the change and whether your integration has to react.Non-breaking changes
These are additive changes that can’t break an integration written against the HTTP and JSON standards. Adding a new endpoint is the obvious example: nothing existing changes, and code that isn’t calling the new endpoint doesn’t notice. Treasury Prime ships non-breaking changes at any time. Significant ones show up in the changelog; the smallest ones may not.Compatible changes
Compatible changes preserve the API contract as written, but can still break an integration that assumes more than the contract actually promises. The most common example is a new value in an enum field: a status field, an event type, or any other enumeration growing a new possible value. The contract for those fields does not guarantee a fixed set of values, so adding one isn’t a contract change. But the new value does show up in the API response, and if your code hard-codes the current set of values (in a database constraint, a strict deserializer, or a switch statement without a default branch), it can crash on the new value even though nothing about the field’s schema changed. Treasury Prime ships compatible changes at any time and documents them in the changelog. See How to build a forward-compatible integration.Breaking changes
Breaking changes alter or remove behavior the API contract currently promises. Treasury Prime avoids them as much as possible. When one is genuinely unavoidable, it doesn’t ship as a surprise: the change goes through the deprecation process below, with a minimum of 90 days between the public announcement and the change date.Changes Treasury Prime considers non-breaking
These ship without ceremony. Treasury Prime does not treat any of the following as breaking:- Adding a new endpoint. Your existing code isn’t calling it.
- Adding a new optional request parameter where omitting it preserves the existing behavior. If you don’t set the parameter, you get the old behavior.
- Adding a new field to a response. Well-written JSON parsers ignore fields they don’t recognize.
- Adding a new webhook event type. Subscribers only receive event types they’ve explicitly subscribed to, so new types don’t arrive unannounced.
- Adding a new field to a webhook event payload that was itself just introduced. No existing code can depend on a payload shape that didn’t exist yet.
- Reducing latency or improving reliability of an existing endpoint.
- Correcting behavior that was inconsistent with the documentation. If the docs said “X” and the API was doing “Y”, making it actually do “X” is a bug fix, not a contract change. If the discrepancy was long-standing enough that customers might have written code against the buggy behavior, the fix lands with a changelog entry anyway.
- Expanding documentation, adding examples, and clarifying wording.
Changes Treasury Prime considers compatible
These preserve the contract but can still trip up existing integrations. Treasury Prime ships them at any time and always documents them in the changelog:- A new value in an existing enum field. A status field, an event type, or an error code enumeration grows a new possible value. The set of values on these fields is not contractually fixed, so the addition isn’t a contract change. It does show up in the API response though, and a client that assumes the current set is exhaustive can fail on the new value.
- A new field in an existing webhook event payload. Existing subscribers keep working as long as they ignore fields they don’t recognize.
- Populating a field that had historically been null in some scenarios. A field documented as nullable can start carrying a value at any time. Older records may keep their previous value (including null) indefinitely while newer records reflect the current behavior. Both shapes can coexist in the same response, particularly for read-only historical data.
- A new documented error code returned from an existing endpoint. New error conditions can be exposed as new codes over time. Clients that handle unknown errors gracefully absorb this without a change.
Changes Treasury Prime considers breaking
None of these ship without going through the deprecation process. The minimum public notice is 90 days, often longer:- Removing an endpoint, response field, request parameter, enum value, or webhook event type.
- Renaming any of the above.
- Changing the type of a field (for example, integer to string, or string to object).
- Changing the semantic meaning of a field or status without changing its name.
- Making an optional request parameter required.
- Tightening validation on an existing input so that previously accepted values are now rejected. (See Urgent corrections for the exception when the previously accepted value fails downstream.)
- Changing the HTTP status code returned for an existing condition.
- Requiring a new authentication scope on an existing endpoint.
How Treasury Prime handles a breaking change
When Treasury Prime concludes that a breaking change genuinely has to happen, it doesn’t just ship. The change goes through a process designed to give your program a concrete alternative, a firm timeline, and enough runway to actually migrate.Before the announcement
Treasury Prime identifies which programs are actively using the affected endpoint, field, or behavior. If your program is one of them, expect direct outreach from your Treasury Prime contact before anything is announced publicly. The outreach covers the change, the reason behind it, the recommended alternative, and the proposed timeline.The public announcement
The deprecation goes into the changelog. Where it applies, the affected surface is markeddeprecated: true in the
OpenAPI specification and annotated as deprecated in the API reference. The announcement includes:
- The specific endpoint, field, event, or behavior being deprecated.
- The recommended alternative.
- The change date.
Notice period
The minimum notice between the public announcement and the change date is 90 days. That’s a floor, not a target. Widely-used functionality and changes that require substantial rework by the integrator may get longer than that, sometimes considerably.At the change date
On the change date, Treasury Prime stops supporting the deprecated surface. From there, one of two things happens, depending on the change:- The surface is removed outright. Requests to a removed endpoint fail; a removed field or enum value stops appearing in responses.
- The surface is preserved in a read-only or reduced-capability form. This is common when historical data depends on the deprecated surface. For example, a status value that only ever appeared on records created before the deprecation may continue to appear on those historical records even after new records stop using it. Whichever behavior applies is called out in the original deprecation announcement, not decided later.
After the change date
Treasury Prime does not promise or support any specific behavior of a deprecated surface past the change date. If a deprecated endpoint or field appears to continue working, that appearance may change or disappear at any time without notice. The correct assumption is that anything not migrated by the change date is out of scope.Urgent corrections
Treasury Prime sits between your program and a lot of downstream systems: multiple partner banks with different cores, payment networks like ACH and Fedwire, regulators, and third-party providers. Each has its own validation rules. Treasury Prime’s own validation aims for the intersection (the lowest common denominator of what every downstream system will accept), so that a value your program submits works everywhere Treasury Prime sends it. Occasionally Treasury Prime discovers that its validation has been more permissive than that intersection actually allows. A value gets through the API and then fails downstream: a special character in a name field that renders the resulting NACHA file unreadable to the Federal Reserve, a value in a wire memo that violates ISO 20022 encoding, or a payload that a partner bank’s core rejects. Leaving those cases open produces files that fail at settlement, payments that bounce, and programs that keep submitting invalid data because the API tells them it’s accepted. Closing the validation gap in a case like this is technically a breaking change under this policy, but the 90-day notice doesn’t apply. Waiting causes worse harm than the change does. Instead:- The change ships as soon as it’s safe to.
- The changelog announces the change immediately, with the specific value or pattern that’s now rejected and the reason.
- Affected programs (those that have submitted the now-invalid value, or whose usage suggests they might) get direct outreach.
- Treasury Prime provides guidance on identifying and cleaning affected data in your existing records.
Changes that come from outside Treasury Prime
Not every change that reaches your integration originates in Treasury Prime’s systems. Partner banks, banking cores, payment networks, and regulatory bodies all impose changes that flow through the Treasury Prime API without Treasury Prime having chosen the timeline, the scope, or the notice. Examples of what falls in this category:- Regulatory or payment-network changes. The ISO 20022 migration for wire messaging is a recent one.
- Partner bank changes. A partner bank switching to a different banking core, a bank running a maintenance event that changes core API behavior, or a bank altering the products it offers.
- Third-party provider changes. A card processor, KYC vendor, or other provider that Treasury Prime partners with may require additional data, change response shapes, or discontinue a capability that Treasury Prime uses to deliver a feature.
- Communicating as early as possible after becoming aware of the change.
- Providing guidance on an alternative approach where one exists.
- Working to minimize the impact on active integrations.
How to build a forward-compatible integration
Some things you can do to minimize the chances of a Treasury Prime update causing a problem in your integration:- Ignore fields you don’t recognize in a response. Response payloads gain new fields over time. Decode the fields your code needs and leave the rest alone. Don’t reject a response that contains fields your parser hasn’t seen before.
- Handle unknown enum values with a fallback. If your code branches on the value of a status field, an event type, an error code, or any other enumeration, include a default branch that treats unrecognized values as “unknown, keep going.” Don’t raise, crash, or reject the payload. If your code genuinely needs to handle every possible value exhaustively (a rules engine dispatching on the value, or a strictly typed switch that can’t fall through), pick the safest behavior for that path when an unknown value arrives, and alert on it. For most systems the safest behavior is to hold the record in an intermediate state or route it to manual review, rather than automatically completing or rejecting it. Emit a metric or a log line so your team learns about the new value. That’s enough. You don’t need elaborate fallback machinery.
- Assume nullable fields may become populated. A field documented as nullable can carry a value at any time. That value can appear only on newly created records while historical records keep their previous value (including null) indefinitely. Both shapes can coexist in the same response. The observed pattern today is not a permanent property of the field.
- Don’t rely on undocumented ordering or presence. If the reference doesn’t promise a specific ordering of items in a list, a specific set of fields in a response, or specific error message wording, don’t build against those observations. They can change without notice.
- Subscribe to the changelog. Compatible changes are documented in the changelog. Subscribing keeps your team ahead of anything that might affect your integration.
Reporting a compatibility concern
If a change appears to have broken your integration, or you believe a proposed change will be more disruptive than this policy allows, contact Treasury Prime:- For anything time-sensitive or production-impacting, reach out to your Treasury Prime contact directly.
- For everything else, email support@treasuryprime.com. Include the request or endpoint affected, a timestamp or request ID if you have one, and what behavior you observed compared to what you expected.