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.

Version numbers are defined per operation. For example, one operation may be on Live version 2 while another is still on Live version 1.

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):

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.

"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.

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.

Unsupported Version Values

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

{"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

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.