# API Changes

This page explains how The Trade Desk introduces and manages changes to the API (GraphQL and REST), including when we provide advance notice and where you can track upcoming and past changes, so you can plan integration updates with confidence. It applies across our APIs, including Platform API and Data API.

<h2 id="change-examples">Change examples</h2>

A change is any modification to the API. It can be entirely additive (a non-breaking change), or it can cause an existing integration to fail, return errors, or behave incorrectly without code changes on your part (a breaking change). We don't employ a formal versioning policy, and group changes into the following four categories.

<h3 id="additions">Additions</h3>

An addition is an expansion to the API, and does not require code changes on your part to keep your integration working. For example:

- A new endpoint, GraphQL field, query, or mutation.
- A new optional request field or parameter.
- A new field in a response payload.
- A new value in an existing enum.
- A new optional query parameter or request header.
- An expanded error message that keeps the same error code.

>**TIP**: Additions are not expected to disrupt existing integrations, but building clients that tolerate unrecognized fields and new enum values (rather than failing on them) will make your integration more resilient to these changes.

<h3 id="behavior-changes">Behavior changes</h3>

The endpoint doesn't return an error and its status doesn't change; it simply behaves differently. Depending on your use case, this may or may not require code changes to accommodate. Examples are:

- Changing a default value or default behavior, such as switching a setting from opt-in to opt-out.
- Changing the meaning or format of an existing field's response value.

<h3 id="new-requirements">New requirements</h3>

Something that used to be optional becomes required. Depending on your use case and implementation, this may or may not require code changes to accommodate. For example:

- Making a previously optional request field or parameter required.
- Adding new, stricter validation to an existing field or parameter.

<h3 id="removals-and-replacements">Removals and replacements</h3>

An element is removed, renamed, or changed in a way that requires code changes on your part. This typically requires code changes from all callers. For example:

- Removing an endpoint, GraphQL field, query, or mutation.
- Renaming a field, parameter, endpoint, or enum value.
- Removing a value from an existing enum.
- Changing the data type of a field (for example, string to integer).

<!--

<h2 id="endpoint-lifecycle-states">Endpoint lifecycle states</h2>

Separate from the type of change being made, every endpoint, field, or other API element is at all times in one of five lifecycle states listed in the following table.

| State | Description |
| --- | --- |
| Current | Stable and fully supported for existing integrations. New features may be added. No planned shutdown date. |
| Legacy | Stable and fully supported for existing integrations, but closed to new integrations. No new features will be added. No planned shutdown date. |
| Behavior change | Still available and won't return an error, but its behavior has changed. For example, a default value or opt-in/opt-out setting. This doesn't affect the element's Current or Legacy status. |
| Deprecated | Marked for future removal. Closed to new integrations, with a published decommission date. Existing integrations must migrate before that date. |
| Decommissioned | Removed. No longer accepting traffic in any way. |

An element moves to the Deprecated state when we announce it as scheduled for removal, and to Decommissioned after it's actually removed on its decommission date.

-->

<h2 id="advance-notice">Advance notice</h2>

Our guidelines are to communicate at least 3 months before planned changes that require integration changes take effect. Unplanned mandatory changes—such as security, compliance, or business continuity—and non-impacting changes are not communicated ahead of time.

When announcing changes, where practical, we aim to do the following:

- Publish the change with a clearly stated decommission date, at least 3 months out.
- Describe the specific action required to remain unaffected, including a migration target (a replacement field, endpoint, or type) where one exists.
- Support the deprecated and replacement behavior side by side during the notice period, so you can migrate on your own schedule rather than at the last minute.

<h2 id="where-to-track-changes">Where to track changes</h2>

Breaking changes are announced and tracked on the *Upcoming changes* page under the **News** hub, which lists quarterly schedules, the effective date, what's changing, and the action required for each upcoming change.

The following table lists all **News** pages for each user type:

| User | Upcoming changes | Release notes | Archives |
| --- | --- | --- | --- |
| Advertiser | [Upcoming changes](/advertiser/docsApp/AdvertiserNews/news/doc/UpgradeSupport) | [Release notes](/advertiser/docsApp/AdvertiserNews/news/doc/ReleaseNotes) | [News archives](/advertiser/docsApp/AdvertiserNews/news/doc/UpgradeSupportArchives) |
| Provider | [Upcoming changes](/provider/docsApp/ProviderNews/news/doc/UpcomingChangesData) | [Release notes](/provider/docsApp/ProviderNews/news/doc/ReleaseNotesData) | [News archives](/provider/docsApp/ProviderNews/news/doc/ReleaseNotesDataArchives) |
| Seller | [Upcoming changes](/seller/docsApp/NewsSeller/news/doc/UpcomingChangesSeller) | [Release notes](/seller/docsApp/NewsSeller/news/doc/ReleaseNotesSeller)<br>[PDP API release notes](/seller/docsApp/GuidesSeller/pdpapi/doc/ReleaseNotesPdpApi) | [News archives](/seller/docsApp/NewsSeller/news/doc/ArchivesSeller) |

>**TIP**: You can also track all Platform API changes in the [API Usage Dashboard](https://open.thetradedesk.com/advertiser/api-usage). It flags any upcoming breaking changes detected in the API usage associated with your account.