{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/partner-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Versioning and deprecation policy","description":"Jiko Technologies' external APIs for integrators.","lang":"en-US","siteUrl":"https://docs.jiko.io","projectTitle":"Jiko Technologies API Documentation","jsonLd":{"@context":"https://schema.org","@type":"Organization","name":"Jiko Technologies","url":"https://docs.jiko.io","logo":"https://docs.jiko.io/static/jiko-logo-blue.svg"},"llmstxt":{"hide":false,"title":"Jiko Technologies API Documentation","description":"External APIs for integrators","sections":[{"title":"Customer API","includeFiles":["products/customer-api/**/*.md"]},{"title":"Partner API","includeFiles":["products/partner-api/**/*.md"]}]},"meta":[{"name":"robots","content":"index,follow,max-image-preview:large"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"versioning-and-deprecation-policy","__idx":0},"children":["Versioning and deprecation policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the commitment we make to partners about how the Partner API changes"," ","over time, and the process we follow internally to honour it. It is written to"," ","be quotable in a diligence questionnaire."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-we-consider-a-breaking-change","__idx":1},"children":["What we consider a breaking change"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A change is breaking if a correct integration built against the documented"," ","contract could stop working because of it. That includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["removing an endpoint, or changing its path or method"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["removing a response field, or narrowing its type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding a required request field, or making an optional one required"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["tightening validation so that a previously accepted request is rejected"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," breaking, and ship without notice:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding an endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding an optional request field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding a response field"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adding a value to a request enum"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["relaxing validation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partners should parse responses permissively — ignore unknown fields rather"," ","than rejecting them — so that additive changes stay non-breaking in practice."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-deprecation-process","__idx":2},"children":["The deprecation process"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every removal follows the same four steps."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"1-announce","__idx":3},"children":["1. Announce"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The deprecation is recorded in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/changelog"},"children":["changelog"]}," ","on the day it takes effect, naming the endpoint or field, the replacement, and"," ","the earliest date it may be removed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"2-mark","__idx":4},"children":["2. Mark"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint is marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deprecated"]}," in the OpenAPI schema, so it renders struck"," ","through in the API reference and is flagged by generated clients and linters."," ","Its description names the replacement. A deprecated field carries the same"," ","marker on the field itself."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"3-wait","__idx":5},"children":["3. Wait"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A deprecated endpoint remains callable for a minimum of three months from the"," ","changelog announcement."]}," In practice most live far longer; three months is the"," ","floor, not the target. Nothing is removed inside that window."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We may hide a deprecated endpoint from the published reference before removing"," ","it, once it has been deprecated for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["six months or more"]},". Hiding is a"," ","documentation change only — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["a hidden endpoint still works"]},". It exists to stop"," ","new integrations adopting a route that is on its way out, without disturbing"," ","partners already calling it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"4-contact-then-remove","__idx":6},"children":["4. Contact, then remove"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before an endpoint is removed we identify every partner we can observe calling"," ","it and contact them directly. We do not rely on the partner having read the"," ","changelog. If a partner is still calling a deprecated endpoint at the end of the"," ","window, we work with them on a migration date rather than removing it underneath"," ","them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"versioning","__idx":7},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Partner API is versioned in the URL path (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/"]},"). A new"," ","major version is introduced when a domain is redesigned rather than extended —"," ","for example V2 Pockets replacing V1 Accounts."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Introducing V2 of a domain does not deprecate V1 of every other domain."]}," The"," ","two versions run side by side, and V1 continues to receive new endpoints in"," ","domains where no V2 equivalent exists. A partner integrating today will use a"," ","mix of V1 and V2 routes, and that is expected and supported."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An endpoint in V1 is deprecated only when its V2 replacement has reached"," ","functional parity. At that point it follows the process above."]}]},"headings":[{"value":"Versioning and deprecation policy","id":"versioning-and-deprecation-policy","depth":1},{"value":"What we consider a breaking change","id":"what-we-consider-a-breaking-change","depth":3},{"value":"The deprecation process","id":"the-deprecation-process","depth":3},{"value":"1. Announce","id":"1-announce","depth":4},{"value":"2. Mark","id":"2-mark","depth":4},{"value":"3. Wait","id":"3-wait","depth":4},{"value":"4. Contact, then remove","id":"4-contact-then-remove","depth":4},{"value":"Versioning","id":"versioning","depth":3}],"frontmatter":{"seo":{"title":"Versioning and deprecation policy"}},"lastModified":"2026-09-10T11:31:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/partner-api/guides/building/deprecation-policy","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}