> 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/bulk-integration/bulk-service-response.md).

# Bulk Service Response

### Overview

After you submit a valid Bulk Service request, the system returns a response that tells you which items in your batch were accepted, rejected, or failed (for example due to invalid data, insufficient credit, or rate limiting).

This response does **not** contain the parsed Amazon data. For each accepted item it returns a unique result `id`. You then use those IDs to retrieve the full structured data from the Data Service.

### Sample Response

{% code overflow="wrap" %}

```json
{
  "success": true,
  "meta_data": {
    "total_count": 3,
    "accepted_count": 3,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "B00004RFMB", "id": "qwe78933-7614-40b3-9a40-def192b74810", "credit": 1 },
          { "asin": "B00004RFMC", "id": "xyz5677e-c8a7-47e1-91a1-966bc448e0e8", "credit": 1 },
          { "asin": "B00004RFMJ", "id": "abc123b5-c346-4909-aa6b-f4194318dc3a", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [],
    "rate_limit_exceeded": []
  }
}
```

{% endcode %}

### Top-Level Fields

Every response contains these top-level keys. `success` and `message` report the outcome, while `meta_data` and `data` carry the batch summary and the per-item results.

| Field       | Type    | Description                                                                                                                                                                                                                             |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`   | boolean | Whether the request was processed without critical errors. A partially valid batch still returns `true`, with valid items in `data.accepted` and rejected items in the relevant arrays. Only a fully malformed request returns `false`. |
| `message`   | string  | Present only when the request fails. A short description of the error (e.g. `"Bad request."`).                                                                                                                                          |
| `meta_data` | object  | Summary counts for the batch (accepted, invalid, failed, and so on).                                                                                                                                                                    |
| `data`      | object  | Per-item results, grouped by outcome.                                                                                                                                                                                                   |

### `meta_data` Object

Summary counts for the whole batch. Each count corresponds to the number of items in the array of the same name inside `data` (for example, `invalid_count` equals the length of `data.invalid`).

| Field                       | Type    | Parent     | Description                                                           |
| --------------------------- | ------- | ---------- | --------------------------------------------------------------------- |
| `total_count`               | integer | meta\_data | Total number of individual items in your request payload.             |
| `accepted_count`            | integer | meta\_data | Items successfully accepted and queued for processing.                |
| `invalid_count`             | integer | meta\_data | Items rejected due to validation errors (e.g. missing fields).        |
| `insufficient_credit_count` | integer | meta\_data | Items not accepted due to lack of API credits.                        |
| `failed_count`              | integer | meta\_data | Items that failed due to internal errors.                             |
| `rate_limit_exceeded_count` | integer | meta\_data | Items not accepted because the per-minute request limit was exceeded. |

### `data` Object

Holds the per-item outcome of the batch, split into five arrays. Each item is placed in exactly one array based on its result. The `accepted` array is the one you act on next, since it carries the result IDs. Empty arrays may be omitted from the response.

| Field                 | Type             | Parent | Description                                                       |
| --------------------- | ---------------- | ------ | ----------------------------------------------------------------- |
| `accepted`            | array of objects | data   | Items accepted for processing. Contains the generated result IDs. |
| `invalid`             | array of objects | data   | Items rejected due to a validation error.                         |
| `failed`              | array of objects | data   | Items that hit a server-side failure during processing.           |
| `insufficient_credit` | array of objects | data   | Items dropped due to a credit shortage.                           |
| `rate_limit_exceeded` | array of objects | data   | Items dropped because the per-minute request limit was reached.   |

The objects inside these arrays differ by outcome. Items in `accepted` use the structure in **Accepted Items** below. Rejected items use a different structure depending on why they were rejected, described in the sections that follow.

Credits are charged only for items in `data.accepted`. A `credit` value shown on a dropped item (for example in `rate_limit_exceeded`) reflects its nominal cost, not an actual charge.

#### **Invalid Items**

Objects in `data.invalid` describe a validation error in the submitted request.

| Field          | Type   | Parent     | Description                                                                                                                                           |
| -------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`        | string | invalid\[] | The submitted value that caused the rejection (e.g. `"SELLER_FEDBACK"`).                                                                              |
| `message`      | string | invalid\[] | Why the item was rejected (e.g. `"must be equal to one of the allowed values"`).                                                                      |
| `path`         | string | invalid\[] | The general location of the error in the request (e.g. `"body"`).                                                                                     |
| `instancePath` | string | invalid\[] | Path to the invalid field, prefixed by the item's zero-based index in the batch (e.g. `/1/operation` means the `operation` field of the second item). |

<details>

<summary>Sample Response – invalid item (wrong operation name)</summary>

{% code overflow="wrap" %}

```json
{
  "success": false,
  "message": "Bad request.",
  "meta_data": {
    "total_count": 1,
    "accepted_count": 0,
    "invalid_count": 1,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [],
    "invalid": [
      {
        "value": "SELLER_FEEDBAK",
        "message": "must be equal to one of the allowed values",
        "path": "body",
        "instancePath": "/0/operation"
      }
    ],
    "failed": [],
    "insufficient_credit": []
  }
}
```

{% endcode %}

</details>

#### **Failed Items**

Objects in `data.failed` are items that were valid but hit a server-side failure during processing. The original request fields are echoed back so you can identify and retry them.

| Field          | Type   | Parent    | Description                                            |
| -------------- | ------ | --------- | ------------------------------------------------------ |
| `id`           | string | failed\[] | Identifier assigned to the failed item.                |
| `platform`     | string | failed\[] | The platform of the failed request (e.g. `AMZ`).       |
| `operation`    | string | failed\[] | The operation of the failed request (e.g. `DETAIL`).   |
| `payload`      | object | failed\[] | The original input payload (e.g. `{ "asin": "..." }`). |
| `domain`       | string | failed\[] | The marketplace domain of the failed request.          |
| `callback_url` | string | failed\[] | The callback URL submitted with the request.           |

<details>

<summary>Sample Response – failed items</summary>

{% code overflow="wrap" %}

```json
{
  "success": true,
  "meta_data": {
    "total_count": 8,
    "accepted_count": 4,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 4,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "0002158639", "id": "019ef8e0-5403-72f3-86dc-110ad7fed88c", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [
      {
        "id": "019ef8e0-5402-7e64-9a7f-f6e8b20be5fe",
        "platform": "AMZ",
        "operation": "DETAIL",
        "payload": { "asin": "0000306037" },
        "domain": ".com",
        "callback_url": "https://example.com/webhook"
      }
    ],
    "insufficient_credit": [],
    "rate_limit_exceeded": []
  }
}
```

{% endcode %}

</details>

#### **Rate-Limited Items**

Objects in `data.rate_limit_exceeded` contain the original request that was dropped because the per-minute request limit was reached. The rest of the batch is still processed.

| Field            | Type   | Parent                           | Description                                                                                                                                                                       |
| ---------------- | ------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`        | string | rate\_limit\_exceeded\[]         | The rate-limit error message (e.g. `"[!] Minute request limit exceeded."`).                                                                                                       |
| `payload`        | object | rate\_limit\_exceeded\[]         | The original request item that was dropped, plus its assigned `id` and `credit`.                                                                                                  |
| ↳ `platform`     | string | rate\_limit\_exceeded\[].payload | The platform of the dropped request (e.g. `AMZ`).                                                                                                                                 |
| ↳ `operation`    | string | rate\_limit\_exceeded\[].payload | The operation of the dropped request (e.g. `DETAIL`).                                                                                                                             |
| ↳ `domain`       | string | rate\_limit\_exceeded\[].payload | The marketplace domain of the dropped request.                                                                                                                                    |
| ↳ `payload`      | object | rate\_limit\_exceeded\[].payload | The original input payload (e.g. `{ "asin": "..." }`).                                                                                                                            |
| ↳ `callback_url` | string | rate\_limit\_exceeded\[].payload | The callback URL submitted with the request.                                                                                                                                      |
| ↳ `id`           | string | rate\_limit\_exceeded\[].payload | Identifier assigned to the dropped request.                                                                                                                                       |
| ↳ `credit`       | number | rate\_limit\_exceeded\[].payload | The nominal credit cost of the request. This value is shown for reference only; credits are charged solely for items in `data.accepted`, so dropped items do not consume credits. |

<details>

<summary>Sample Response – rate-limited batch (105 sent, 100 accepted, 5 rate-limited)</summary>

{% code overflow="wrap" %}

```json
{
  "success": true,
  "meta_data": {
    "total_count": 105,
    "accepted_count": 100,
    "invalid_count": 0,
    "insufficient_credit_count": 0,
    "failed_count": 0,
    "rate_limit_exceeded_count": 5
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "B000PW6WYQ", "id": "019ef4d9-e721-7b23-8ad4-d54c51b3cba2", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [],
    "rate_limit_exceeded": [
      {
        "message": "[!] Minute request limit exceeded.",
        "payload": {
          "platform": "AMZ",
          "operation": "DETAIL",
          "domain": ".com",
          "payload": { "asin": "B000PXYADK" },
          "callback_url": "https://example.com/webhook",
          "id": "019ef4d9-e722-7a30-a866-dee242c5c0f1",
          "credit": 1
        }
      }
    ]
  }
}
```

{% endcode %}

</details>

**Insufficient-Credit Items**

Objects in `data.insufficient_credit` contain the original request that was dropped because your account did not have enough credits to process it. Items are accepted in order until your credit runs out; the remainder are placed here while the rest of the batch is still processed.

| Field            | Type   | Parent                          | Description                                                                                             |
| ---------------- | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `message`        | string | insufficient\_credit\[]         | The error message (e.g. `"[!] You do not have enough credit to perform this action."`).                 |
| `payload`        | object | insufficient\_credit\[]         | The original request item that was dropped, plus its assigned `id` and `credit`.                        |
| ↳ `platform`     | string | insufficient\_credit\[].payload | The platform of the dropped request (e.g. `AMZ`).                                                       |
| ↳ `operation`    | string | insufficient\_credit\[].payload | The operation of the dropped request (e.g. `DETAIL`).                                                   |
| ↳ `domain`       | string | insufficient\_credit\[].payload | The marketplace domain of the dropped request.                                                          |
| ↳ `payload`      | object | insufficient\_credit\[].payload | The original input payload (e.g. `{ "asin": "..." }`).                                                  |
| ↳ `callback_url` | string | insufficient\_credit\[].payload | The callback URL submitted with the request.                                                            |
| ↳ `id`           | string | insufficient\_credit\[].payload | Identifier assigned to the dropped request.                                                             |
| ↳ `credit`       | number | insufficient\_credit\[].payload | The nominal credit cost of the request. Shown for reference only; dropped items do not consume credits. |

<details>

<summary>Sample Response – insufficient credit (80 sent, 74 accepted, 6 dropped)</summary>

{% code overflow="wrap" %}

```json
{
  "success": true,
  "meta_data": {
    "total_count": 80,
    "accepted_count": 74,
    "invalid_count": 0,
    "insufficient_credit_count": 6,
    "failed_count": 0,
    "rate_limit_exceeded_count": 0
  },
  "data": {
    "accepted": [
      {
        "platform": "AMZ",
        "operation": "DETAIL",
        "domain": ".com",
        "callback_url": "https://example.com/webhook",
        "ship_to": { "zipCode": ["19805"] },
        "results": [
          { "asin": "B000PWTITM", "id": "019ef975-16bd-7242-9fd5-c6e031409f70", "credit": 1 }
        ]
      }
    ],
    "invalid": [],
    "failed": [],
    "insufficient_credit": [
      {
        "message": "[!] You do not have enough credit to perform this action.",
        "payload": {
          "platform": "AMZ",
          "operation": "DETAIL",
          "domain": ".com",
          "payload": { "asin": "B000PWU23I" },
          "callback_url": "https://example.com/webhook",
          "id": "019ef975-16bd-7242-9fd5-c6e4f1d939f7",
          "credit": 1
        }
      }
    ],
    "rate_limit_exceeded": []
  }
}
```

{% endcode %}

</details>

### Partial Success

A single batch can contain items with different outcomes. Each item is evaluated independently:

* Valid items are accepted and appear in `data.accepted` with their result IDs.
* Invalid items are rejected and appear in `data.invalid` with the reason.
* Items that fail during processing appear in `data.failed`.
* Items that exceed the per-minute request limit appear in `data.rate_limit_exceeded` while the rest of the batch is still accepted.

In these cases `success` remains `true`, and the `meta_data` counts reflect the split. Always check the individual arrays rather than relying on `success` alone.

### Accepted Items

Each object in `data.accepted` echoes back the request that was accepted and lists the generated queries under `results`. Each input value in your payload (each ASIN, keyword, URL, Seller ID, or identifier) generates its own result `id`.

| Field          | Type             | Parent           | Description                                                                                                             |
| -------------- | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `platform`     | string           | data.accepted\[] | The platform the operation targets (e.g. `AMZ`).                                                                        |
| `operation`    | string           | data.accepted\[] | The operation requested (e.g. `SEARCH`, `DETAIL`, `SELLER_FEEDBACK`).                                                   |
| `domain`       | string           | data.accepted\[] | Domain of the target marketplace (e.g. `.com`, `.ca`).                                                                  |
| `callback_url` | string           | data.accepted\[] | Webhook address notified when the results are ready. It receives a readiness notification, not the parsed data.         |
| `ship_to`      | object           | data.accepted\[] | Resolved shipping destination. When no `address_id` is sent, it defaults to a location based on the marketplace domain. |
| ↳ `zipCode`    | array of strings | ship\_to         | Zip code(s) used to localize the request.                                                                               |
| `results`      | array of objects | data.accepted\[] | The individual queries generated from this item, each with its own result `id`.                                         |

#### **`results[]` Fields**

Each entry represents one query and carries the `id` you use to retrieve its data from the Data Service. The identifier fields present depend on the operation and the input type you submitted.

| Field             | Type    | Parent  | Description                                                                                                                                                  |
| ----------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | string  | results | Unique identifier for this query. Use it to retrieve the result from the Data Service.                                                                       |
| `credit`          | integer | results | Credits consumed by this accepted query (typically `1`)                                                                                                      |
| `asin`            | string  | results | The queried ASIN. Present for ASIN-based input (e.g. DETAIL, OFFER).                                                                                         |
| `keyword`         | string  | results | The submitted search term. Present for SEARCH with keyword input.                                                                                            |
| `seller_id`       | string  | results | The submitted Seller ID. Present for SELLER\_PROFILE, SELLER\_PRODUCTS, SELLER\_FEEDBACK.                                                                    |
| `url`             | string  | results | The full storefront URL you submitted. SELLER\_PROFILE and SELLER\_FEEDBACK use the `/sp?...seller=` form; SELLER\_PRODUCTS uses the `/s?me=` form.          |
| `link`            | string  | results | The relative path of the submitted URL. Present for URL-based input, except SELLER\_FEEDBACK (which returns only `url`).                                     |
| `identifier`      | string  | results | The submitted product code. Present for PRODUCT\_LOOKUP.                                                                                                     |
| `identifier_type` | string  | results | The code type used for the lookup (e.g. `UPC`). Present for PRODUCT\_LOOKUP.                                                                                 |
| `min_rating`      | integer | results | Echoed minimum rating filter (SELLER\_FEEDBACK). When not sent, no filter is applied and all ratings from 1 to 5 are returned; the echoed value is then `0`. |
| `max_rating`      | integer | results | Echoed maximum rating filter (SELLER\_FEEDBACK). When not sent, no filter is applied and all ratings from 1 to 5 are returned; the echoed value is then `0`. |

<details>

<summary>Sample <code>results[]</code> by input type</summary>

{% code overflow="wrap" %}

```json
// ASIN input (DETAIL, OFFER)
{ "asin": "B00004RFMB", "id": "qwe78933-7614-40b3-9a40-def192b74810", "credit": 1 }

// Keyword input (SEARCH)
{ "keyword": "car", "id": "019eef7c-ee5c-7cde-945c-ecb0eeb4ead3", "credit": 1 }

// Seller ID input (SELLER_PROFILE, SELLER_PRODUCTS, SELLER_FEEDBACK)
{ "seller_id": "A29DXXRE3BKYH7", "id": "019ef42e-8f2d-7ca5-997a-bc87609f5085", "credit": 1 }

// URL input (SELLER_PROFILE) — storefront /sp?...seller=
{ "url": "https://www.amazon.com/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "link": "/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "id": "019ef42a-dd1f-7fb4-a07f-af59318f979f", "credit": 1 }

// URL input (SELLER_PRODUCTS) — storefront /s?me=
{ "url": "https://www.amazon.com/s?me=A29DXXRE3BKYH7", "link": "/s?me=A29DXXRE3BKYH7", "id": "019ef441-7ee2-722d-ad36-96fdf5296136", "credit": 1 }

// URL input (SELLER_FEEDBACK) — storefront /sp?...seller=, returns url only, no link
{ "url": "https://www.amazon.com/sp?ie=UTF8&seller=A29DXXRE3BKYH7", "min_rating": 0, "max_rating": 0, "id": "019ef42d-060a-71d4-b3e1-82e65cf37579", "credit": 1 }

// PRODUCT_LOOKUP
{ "identifier": "724382975021", "identifier_type": "UPC", "id": "019ef43f-14f2-7a8c-b737-466f0ce0b54a", "credit": 1 }
```

{% endcode %}

</details>

### Next Step: Retrieving Your Data

Each result `id` represents one unit of processed work. Once you have the IDs from `data.accepted[].results[]`, use them to fetch the parsed data from the Data Service.