> 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/real-time-integration/best-sellers-rank/response.md).

# Response

The response for the Best Sellers Rank (BSR) operation provides a snapshot of a product's sales performance and its category standing. The system processes live data from Amazon and delivers a clean, structured, analysis-ready JSON output.

{% hint style="warning" %}
**Two versions are currently available.** The structure of the `result` object depends on the `operation_version` request parameter:

* **Live (`operation_version=1`):** Returned when `operation_version` is omitted or set to `1`.
* **Beta (`operation_version=2`):** Returned when `operation_version=2` is sent. It becomes Live on **November 1, 2026**, after which all requests return it regardless of the value sent.

The top-level meta fields are identical in both versions. To prepare your integration, see [3 - Migrating from Live to Beta](#id-3-migrating-from-live-to-beta). For general rules, see [Operation Versioning](/easyparser-documentation/amazon/operation-versioning.md).
{% endhint %}

## API Response Structure Overview

The JSON response is organized into four primary sections:

1. `request_info`: The success status of the API call and credit usage details.
2. `request_parameters`: Echoes the parameters you sent (ASIN, operation type, and response version) to confirm what was processed.
3. `request_metadata`: Timestamps and processing duration for the request.
4. `result`: The core payload containing the product's ranking data and product details. Its structure depends on `operation_version`.

## 1 - Top-Level Meta Fields (Outside of `result`)

These fields provide essential information about the transaction status, parameters, and processing timing. They are the same for the Live and Beta versions.

### `request_info` (object)

Contains the status of the API call and credit usage details.

| Field                      | Type              | Description                                                                              |
| -------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `id`                       | String            | A unique identifier for this specific request. Provide it when contacting support.       |
| `success`                  | Boolean           | Indicates whether the request was successfully processed.                                |
| `status_code`              | Integer           | Standard HTTP status code (e.g., `200` for success).                                     |
| `error_details`            | Array             | An array of error messages if the request failed. Empty `[]` on success.                 |
| `credits_used`             | Integer           | The total cumulative credits used by your account to date.                               |
| `credit_used_this_request` | Integer           | The credits deducted for this call (`1` for `BEST_SELLERS_RANK`, in both Live and Beta). |
| `credits_remaining`        | Integer           | Your current remaining credit balance.                                                   |
| `credits_reset_at`         | String (ISO Date) | The date and time when your credit limit will reset.                                     |

```json
"request_info": {
    "id": "437a2cea-cae7-40a7-b96c-30780beba220",
    "success": true,
    "status_code": 200,
    "error_details": [],
    "credits_used": 9752,
    "credit_used_this_request": 1,
    "credits_remaining": 990248,
    "credits_reset_at": "2028-12-09T08:46:47.000Z"
}
```

### `request_parameters` (object)

Echoes back the parameters sent in the request to confirm what was processed.

| Field               | Type    | Description                                                                                                                                                            |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asin`              | String  | The Amazon Standard Identification Number used for the query.                                                                                                          |
| `type`              | String  | The operation type executed (`BEST_SELLERS_RANK`).                                                                                                                     |
| `operation_version` | Integer | The response version applied to this request. If the parameter was omitted, this shows the Live version number (`1`); if `operation_version=2` was sent, it shows `2`. |

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

### `request_metadata` (object)

Captures timestamps and duration for the lifecycle of the request.

| Field              | Type              | Description                                                             |
| ------------------ | ----------------- | ----------------------------------------------------------------------- |
| `created_at`       | String (ISO Date) | The timestamp when the request was received by the system.              |
| `processed_at`     | String (ISO Date) | The timestamp when the processing was completed.                        |
| `total_time_taken` | Number            | The total duration (in seconds) the system took to process the request. |

```json
"request_metadata": {
    "created_at": "2026-09-29T11:40:48.332Z",
    "processed_at": "2026-09-29T11:40:51.648Z",
    "total_time_taken": 3.316
}
```

## 2 - Core Response Payload – `result` Section

The `result` object contains the product's ranking data and core product details. Its structure depends on the `operation_version` you send: requests without it receive the **Live** structure shown in the first tab.

{% tabs %}
{% tab title="Live (operation\_version=1)" %}
This is the response you receive when `operation_version` is omitted or set to `1`.

{% hint style="warning" %}
The Live version is replaced by the Beta version on **November 1, 2026**. If you are building a new integration, we recommend starting directly with the Beta version (`operation_version=2`) to avoid a migration later.
{% endhint %}

The `result` object contains:

1. `country_code`: The marketplace the data was retrieved from.
2. `product`: Product identification and commercial details, with the nested `bestseller`, `media`, and `reviews` objects.

#### A- Result Root (`result`)

| Field          | Type   | Description                                                            |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `country_code` | String | The ISO alpha-2 country code of the Amazon marketplace (e.g., `"US"`). |
| `product`      | Object | The product's details and ranking data (see below).                    |

```json
"result": {
    "country_code": "US",
    "product": { ... }
}
```

#### B- Product (`result.product`)

Primary identification and commercial details of the product.

| Field        | Type   | Description                                               |
| ------------ | ------ | --------------------------------------------------------- |
| `asin`       | String | The Amazon Standard Identification Number of the product. |
| `title`      | String | The full title of the product as shown on the listing.    |
| `brand_name` | String | The brand associated with the product.                    |
| `price`      | Number | The current selling price at the time of the request.     |
| `currency`   | String | The three-letter ISO currency code for the marketplace.   |
| `link`       | String | The direct URL to the product's detail page on Amazon.    |

```json
"product": {
    "asin": "B09NHWJRFM",
    "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange | Includes Pouring Shield for Mess-Free Mixing, 10 Speed Settings, Easily add Ingredients with the Tilt-Head Design",
    "brand_name": "KitchenAid",
    "price": 379.99,
    "currency": "USD",
    "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
    "bestseller": { ... },
    "media": { ... },
    "reviews": { ... }
}
```

#### C- Best Seller Ranking (`result.product.bestseller`)

The product's rank in its main category.

| Field             | Type    | Description                                          |
| ----------------- | ------- | ---------------------------------------------------- |
| `rank`            | Integer | The product's ranking position in its main category. |
| `context_name`    | String  | The display name of the main category.               |
| `sub_category_id` | String  | The browse node ID of the product's sub-category.    |

```json
"bestseller": {
    "context_name": "Kitchen & Dining",
    "rank": 393,
    "sub_category_id": "7904803"
}
```

#### D- Media (`result.product.media`)

Links to the product's primary image.

| Field       | Type   | Description                                            |
| ----------- | ------ | ------------------------------------------------------ |
| `image_url` | String | The URL of the primary product image.                  |
| `thumb_url` | String | The URL of the thumbnail version of the primary image. |

```json
"media": {
    "image_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_.jpg",
    "thumb_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_SL80_.jpg"
}
```

#### E- Reviews (`result.product.reviews`)

Aggregated customer rating metrics.

| Field             | Type    | Description                                            |
| ----------------- | ------- | ------------------------------------------------------ |
| `rating_value`    | Number  | The average rating score out of 5.                     |
| `rating_text`     | String  | The textual representation of the average rating.      |
| `full_star_count` | Integer | The number of fully shaded stars in the rating visual. |
| `total_count`     | Integer | The total number of customer ratings.                  |

```json
"reviews": {
    "full_star_count": 4,
    "rating_text": "4.7 out of 5 stars",
    "rating_value": 4.7,
    "total_count": 23203
}
```

#### Sample JSON Output

A complete Live (`operation_version=1`) response for the example request.

{% code overflow="wrap" expandable="true" %}

```json
{
    "request_info": {
        "id": "161ac5ec-8e7e-4610-940d-0b7297f5170e",
        "success": true,
        "status_code": 200,
        "error_details": [],
        "credits_used": 9751,
        "credit_used_this_request": 1,
        "credits_remaining": 990249,
        "credits_reset_at": "2028-12-09T08:46:47.000Z"
    },
    "request_parameters": {
        "asin": "B09NHWJRFM",
        "type": "BEST_SELLERS_RANK",
        "operation_version": 1
    },
    "request_metadata": {
        "created_at": "2026-09-29T11:21:45.401Z",
        "processed_at": "2026-09-29T11:21:49.759Z",
        "total_time_taken": 4.358
    },
    "result": {
        "country_code": "US",
        "product": {
            "asin": "B09NHWJRFM",
            "bestseller": {
                "context_name": "Kitchen & Dining",
                "rank": 393,
                "sub_category_id": "7904803"
            },
            "brand_name": "KitchenAid",
            "currency": "USD",
            "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
            "media": {
                "image_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_.jpg",
                "thumb_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_SL80_.jpg"
            },
            "price": 379.99,
            "reviews": {
                "full_star_count": 4,
                "rating_text": "4.7 out of 5 stars",
                "rating_value": 4.7,
                "total_count": 23203
            },
            "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange | Includes Pouring Shield for Mess-Free Mixing, 10 Speed Settings, Easily add Ingredients with the Tilt-Head Design"
        }
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="Beta (operation\_version=2)" %}
Returned when `operation_version=2` is sent. Becomes Live on November 1, 2026. The `result` object contains:

1. `country_code`: The marketplace the data was retrieved from.
2. `product`: Product identification details, with the nested `bestseller`, `bestsellers`, and `image` objects.

#### A- Result Root (`result`)

| Field          | Type   | Description                                                            |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `country_code` | String | The ISO alpha-2 country code of the Amazon marketplace (e.g., `"US"`). |
| `product`      | Object | The product's details and ranking data (see below).                    |

```json
"result": {
    "country_code": "US",
    "product": { ... }
}
```

#### B- Product (`result.product`)

Primary identification details of the product.

| Field          | Type   | Description                                                                     |
| -------------- | ------ | ------------------------------------------------------------------------------- |
| `asin`         | String | The Amazon Standard Identification Number of the product.                       |
| `title`        | String | The product's short title.                                                      |
| `brand_name`   | String | The brand associated with the product.                                          |
| `manufacturer` | String | The manufacturer of the product.                                                |
| `link`         | String | The direct URL to the product's detail page on Amazon.                          |
| `bestseller`   | Object | The product’s main category rank (see C- Best Seller Ranking).                  |
| `bestsellers`  | Array  | Every Best Sellers list the product is ranked in (see D- Best Seller Rankings). |

```json
"product": {
    "asin": "B09NHWJRFM",
    "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange",
    "brand_name": "KitchenAid",
    "manufacturer": "KitchenAid",
    "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
    "bestseller": { ... },
    "bestsellers": [ ... ],
    "image": { ... }
}
```

#### C- Best Seller Ranking (`result.product.bestseller`)

A summary of the product’s rank in its main category and its primary sub-category, each with the category title and a link to the corresponding Amazon Best Sellers list. For every list the product is ranked in, see [D- Bestsellers](#d-bestsellers-result.product.bestsellers).

| Field                | Type    | Description                                          |
| -------------------- | ------- | ---------------------------------------------------- |
| `category_rank`      | Integer | The product's ranking position in its main category. |
| `category_title`     | String  | The display name of the main category.               |
| `category_link`      | String  | The URL of the main category's Best Sellers list.    |
| `sub_category_rank`  | Integer | The product's ranking position in its sub-category.  |
| `sub_category_title` | String  | The display name of the sub-category.                |
| `sub_category_link`  | String  | The URL of the sub-category's Best Sellers list.     |

```json
"bestseller": {
    "category_link": "https://www.amazon.com/gp/bestsellers/kitchen",
    "category_rank": 886,
    "category_title": "Kitchen & Dining",
    "sub_category_link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
    "sub_category_rank": 1,
    "sub_category_title": "Household Stand Mixers"
}
```

#### D- Bestsellers (`result.product.bestsellers`)

An array listing every Best Sellers list the product is ranked in, including its main category and each of its sub-categories. Entries are not returned in a guaranteed order; use `type` to tell the main category apart from sub-categories.

| Field   | Type    | Description                                                                                         |
| ------- | ------- | --------------------------------------------------------------------------------------------------- |
| `rank`  | Integer | The product’s ranking position in this list.                                                        |
| `title` | String  | The display name of the category.                                                                   |
| `link`  | String  | The URL of the category’s Best Sellers list.                                                        |
| `type`  | String  | The level of the category: `"category"` for the main category, `"sub_category"` for a sub-category. |

{% code overflow="wrap" expandable="true" %}

```json
"bestsellers": [
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen",
        "rank": 886,
        "title": "Kitchen & Dining",
        "type": "category"
    },
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
        "rank": 1,
        "title": "Household Stand Mixers",
        "type": "sub_category"
    }
]
```

{% endcode %}

#### E- Main Image (`result.product.image`)

The product's main image in full resolution.`null` if no image is available.

| Field     | Type   | Description                                                       |
| --------- | ------ | ----------------------------------------------------------------- |
| `id`      | String | The Amazon image identifier.                                      |
| `link`    | String | The URL of the full-resolution image.                             |
| `variant` | String | The image variant (e.g., `"MAIN"` for the primary product image). |

```json
"image": {
    "id": "71d0Mecy7-L",
    "link": "https://m.media-amazon.com/images/I/71d0Mecy7-L.jpg",
    "variant": "MAIN"
}
```

#### Sample JSON Output

A complete Beta (`operation_version=2`) response for the example request.

{% code overflow="wrap" expandable="true" %}

```json
{
    "request_info": {
        "id": "437a2cea-cae7-40a7-b96c-30780beba220",
        "success": true,
        "status_code": 200,
        "error_details": [],
        "credits_used": 9752,
        "credit_used_this_request": 1,
        "credits_remaining": 990248,
        "credits_reset_at": "2028-12-09T08:46:47.000Z"
    },
    "request_parameters": {
        "asin": "B09NHWJRFM",
        "type": "BEST_SELLERS_RANK",
        "operation_version": 2
    },
    "request_metadata": {
        "created_at": "2026-09-29T11:40:48.332Z",
        "processed_at": "2026-09-29T11:40:51.648Z",
        "total_time_taken": 3.316
    },
    "result": {
        "country_code": "US",
        "product": {
            "asin": "B09NHWJRFM",
            "bestseller": {
                "category_link": "https://www.amazon.com/gp/bestsellers/kitchen",
                "category_rank": 374,
                "category_title": "Kitchen & Dining",
                "sub_category_link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
                "sub_category_rank": 1,
                "sub_category_title": "Household Stand Mixers"
            },
            "brand_name": "KitchenAid",
            "image": {
                "id": "71d0Mecy7-L",
                "link": "https://m.media-amazon.com/images/I/71d0Mecy7-L.jpg",
                "variant": "MAIN"
            },
            "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
            "manufacturer": "KitchenAid",
            "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange"
        },
        "bestsellers": [
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen",
        "rank": 886,
        "title": "Kitchen & Dining",
        "type": "category"
    },
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
        "rank": 1,
        "title": "Household Stand Mixers",
        "type": "sub_category"
    }
]
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 3 - Migrating from Live to Beta

If your integration relies on the Live response (`operation_version=1`), update it before November 1, 2026. Send `operation_version=2` to test the Beta structure now; the meta fields and `country_code`, `asin`, `brand_name`, and `link` are unchanged.

| Live Field (`1`)                     | Beta Field (`2`)                        | Change                                      |
| ------------------------------------ | --------------------------------------- | ------------------------------------------- |
| `product.bestseller.rank`            | `product.bestseller.category_rank`      | Renamed                                     |
| `product.bestseller.context_name`    | `product.bestseller.category_title`     | Renamed                                     |
| `product.bestseller.sub_category_id` | —                                       | Removed                                     |
| —                                    | `product.bestseller.category_link`      | Added                                       |
| —                                    | `product.bestseller.sub_category_rank`  | Added                                       |
| —                                    | `product.bestseller.sub_category_title` | Added                                       |
| —                                    | `product.bestseller.sub_category_link`  | Added                                       |
| —                                    | `product.bestsellers`                   | Added (all category and sub-category ranks) |
| `product.media.image_url`            | `product.image.link`                    | Replaced (full-resolution image)            |
| `product.media.thumb_url`            | —                                       | Removed                                     |
| —                                    | `product.image.id`                      | Added                                       |
| —                                    | `product.image.variant`                 | Added                                       |
| `product.title`                      | `product.title`                         | Now returns the short product title         |
| —                                    | `product.manufacturer`                  | Added                                       |
| `product.price`                      | —                                       | Removed                                     |
| `product.currency`                   | —                                       | Removed                                     |
| `product.reviews` (all fields)       | —                                       | Removed                                     |
| —                                    | `request_parameters.operation_version`  | Added (echoed in both Live and Beta)        |

{% hint style="info" %}
The Beta version no longer returns price or review data. If you need them, use the [Detail](/easyparser-documentation/real-time-integration/detail/response.md) operation.
{% endhint %}