> For the complete documentation index, see [llms.txt](https://easyparser.gitbook.io/easyparser-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyparser.gitbook.io/easyparser-documentation/amazon/operation-versioning.md).

# Operation Versioning

## Overview

Easyparser operations evolve over time: new fields are added, existing fields are restructured, and outdated fields are removed. To introduce these changes without breaking existing integrations, Easyparser uses **operation versioning**.

Each operation has its own version history, controlled by the `operation_version` request parameter. When an operation's response structure changes, the new structure is released as a new version that you can opt into before it becomes the default. This gives you time to test and update your integration on your own schedule.

## Live and Beta Versions

At any given time, an operation has at most two active versions:

* **Live:** The current default version of the operation. It is returned when `operation_version` is not sent.
* **Beta:** The upcoming version of the operation. It is stable and ready for production use, and it becomes the Live version on an announced date. It is returned only when you explicitly send its version number.

Live and Beta are labels, not fixed numbers. When a Beta version is promoted, it becomes the new Live version, and the next change to that operation is released as a new Beta with a higher version number. The version numbers currently behind each label are listed in [Current Operation Versions](#current-operation-versions).

{% hint style="info" %}
Version numbers are defined per operation. For example, one operation may be on Live version `2` while another is still on Live version `1`.
{% endhint %}

### Using `operation_version`

`operation_version` is an optional parameter available in both Real-Time and Bulk Integration. It is sent together with the other request parameters of the operation.

| Parameter           | Type    | Description                                                                                                                                                        |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `operation_version` | Integer | The response version to return for the operation. If omitted, the operation's Live version is returned. Send the Beta version number to receive the Beta response. |

**Real-Time Integration example** (requesting Best Sellers Rank Beta version `2`):

```http
GET /v1/request?
  api_key=YOUR_API_KEY&
  platform=AMZ&
  operation=BEST_SELLERS_RANK&
  domain=.com&
  asin=B09NHWJRFM&
  operation_version=2 HTTP/1.1
Host: realtime.easyparser.com
```

The version applied to the request is echoed back in the response, inside `request_parameters.operation_version`.

```json
"request_parameters": {
    "asin": "B09NHWJRFM",
    "type": "BEST_SELLERS_RANK",
    "operation_version": 2
}
```

#### Version Lifecycle

1. **Beta release:** A new response structure is released as the Beta version of the operation, and the date on which it will become Live is announced. Requests without `operation_version` continue to receive the Live version.
2. **Transition period:** You can test the Beta version by sending its version number and update your integration using the operation's migration guide.
3. **Promotion:** On the announced date, the Beta version becomes the new Live version. From that moment, every request to the operation returns the new Live version, including requests that send an older version number.

{% hint style="warning" %}
After a Beta version is promoted, older versions are no longer returned. Make sure your integration is compatible with the Beta version before its promotion date. 
{% endhint %}

### Unsupported Version Values

If you send a version number that does not exist for the operation, the request fails with the following error:

```json
{"error": "[!] The operation_version is not supported for this operation."}
```

### Current Operation Versions

Operations not listed here have a single version and do not require `operation_version`.

| Operation         | Live | Beta | Beta Becomes Live On | Migration Guide                                                                                                                               |
| ----------------- | ---- | ---- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Best Sellers Rank | `1`  | `2`  | November 1, 2026     | [Migrating from Live to Beta](/easyparser-documentation/real-time-integration/best-sellers-rank/response.md#id-3-migrating-from-live-to-beta) |

#### Best Practices

* **Switch early:** Send the Beta version number as soon as a Beta is released, so your integration is already compatible when the promotion date arrives.
* **Pin the version you built for:** Once you adopt a version, send its number explicitly instead of relying on the default. This makes the response structure your code expects clear and visible in every request.
* **Check the echo:** Read `request_parameters.operation_version` in the response to confirm which version was applied.