> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/deprecation-schedule-policy/api-deprecation-policy.md). # API Deprecation Policy ## Why we deprecate Here at Epsilon Retail Media we constantly iterate and introduce new products and features. As such, changes to our APIs will be inevitable. To help our users to plan for changes, we follow a deprecation policy where a better version is available or a feature is nearing or at the end of support. The deprecation period for a version begins on the announcement date for the deprecation. The versions marked for deprecation will continue to be available throughout the deprecation period of 3 months. Once the deprecation period has elapsed, the version is expected to be decommissioned, and Epsilon Retail Media can no longer guarantee it will be available from the sunset date. ## Deprecation enforced rules for our APIs 1. Breaking changes such as removed API elements are only introduced through incrementing the version of the API. * Once an API element has been added at a particular version, it can not be removed from that version or have its behaviour significantly changed 2. API objects must be able to round-trip between API versions in a given release with minimal to no information loss, with the exception of whole REST resources that do not exist in some versions. * Example, an object can be written as v1 and then read back as v2 and converted to v1, and the resulting v1 resource will be identical to the original. The representation in v2 might be different from v1, but the system knows how to convert between them in both directions. Additionally, any new field added in v2 must be able to round-trip to v1 and back, which means v1 might have to add an equivalent field, map to an equivalent field or represent it as an annotation. * With Significant product feature changes we will make every effort to design our APIs to be backwards compatible but there may be exceptional circumstances where this may not be possible. We will discuss these exceptions with our partners. 3. An API version may not be deprecated in favour of a less stable API version. * A General Availability (GA) API version can replace the less stable Alpha and Beta versions * Beta versions can replace earlier Beta or Alpha versions but may not be used to replace a GA API version * Alpha versions can replace earlier Alpha versions but may not be used to replace a Beta or the GA version 4. API versions marked for deprecation will be supported for up to 3 months from the notice date. We will announce when the support and availability of the version will end. Alpha and Beta versions may be deprecated sooner as a preferred GA API version is introduced. * New API versions will only be introduced as part of a release that supports both the new version and the previous version * This allows time for users to migrate to the latest version or roll back when needed within the period of time that the previous version is no longer available and has been decommissioned 5. Calling on a decommissioned version can result in unpredictable behaviour or invalid response. ## Exceptions A policy cannot cover every possible situation. This is a living document, and will always evolve with time. Where there are situations that do not fit neatly into this policy, or for which this policy becomes a serious impediment, discuss the challenge with the team at to find the best solutions for those specific cases. Epsilon Retail Media is committed to providing a stable integration that, as much as possible, does not disrupt our users. Exceptions will always be announced in all relevant release notes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/partner/deprecation-schedule-policy/api-deprecation-policy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.