> 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": {
"bulk_request_id": "01a0341d-c6a8-722b-9189-2f2ee09608ef",
"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"] },
"group_id": "01a0341d-c6be-7ccb-b916-49e17627b560",
"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. |
| `bulk_request_id` | string | meta\_data | Unique identifier of this bulk request (the entire batch). Use it to track the request in the [Bulk Requests page of the Web App.](https://app.easyparser.com/bulk-requests) |
### `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.
Every item carries a `group_id` identifying the request object it came from, regardless of which array it ends up in.
#### **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. |
| `message` | string | invalid\[] | Why the item was rejected, including the offending value and index. |
| `path` | string | invalid\[] | The general location of the error in the request (e.g. `"body"`). |
| `instancePath` | string | invalid\[] | Path to the invalid field within the request (e.g. `/0/payload/seller_ids/0`). |
| `platform` | string | invalid\[] | The platform of the rejected request (e.g. `AMZ`). |
| `operation` | string | invalid\[] | The operation of the rejected request (e.g. `SELLER_PROFILE`). |
| `domain` | string | invalid\[] | The marketplace domain of the rejected request. |
| `payload_count` | number | invalid\[] | Number of input values in the rejected item's payload. |
| `group_id` | string | invalid\[] | Identifier of the group this item forms, matching the request object. |
Sample Response – invalid item (wrong seller_id)
{% code overflow="wrap" %}
```json
{
"success": true,
"meta_data": {
"bulk_request_id": "01a038b0-742b-73c3-a3f1-7666d2c4aeb6",
"total_count": 2,
"accepted_count": 1,
"invalid_count": 1,
"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"] },
"group_id": "01a038b0-7517-7e9c-b5eb-c56cd50ad8bf",
"results": [
{ "asin": "B00063NUW6", "id": "01a038b0-7516-7fb0-8cb5-b1d98e49a982", "credit": 1 }
]
}
],
"invalid": [
{
"value": "AAK72K4OIWDXL827362",
"message": "Invalid seller_id format at index 0: \"AAK72K4OIWDXL827362\"",
"path": "body",
"instancePath": "/0/payload/seller_ids/0",
"platform": "AMZ",
"operation": "SELLER_PROFILE",
"domain": ".com",
"payload_count": 1,
"group_id": "01a038b0-7517-7e9c-b5eb-c56dc887a371"
}
],
"failed": [],
"insufficient_credit": [],
"rate_limit_exceeded": []
}
}
```
{% endcode %}
#### **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. |
Sample Response – failed items
{% code overflow="wrap" %}
```json
{
"success": true,
"meta_data": {
"bulk_request_id": "01a03e32-cbf1-7406-a423-462adab9ed87",
"total_count": 8,
"accepted_count": 4,
"invalid_count": 0,
"insufficient_credit_count": 0,
"failed_count": 4,
"rate_limit_exceeded_count": 0
},
"data": {
"accepted": [
{
"group_id": "01a03e32-cbf9-71e4-af94-c8d2abdfe02b",
"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": [
{
"group_id": "01a03e32-cbf9-71e4-af94-c8d1fda44b9b",
"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 %}
#### **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. |
Sample Response – rate-limited batch (105 sent, 100 accepted, 5 rate-limited)
{% code overflow="wrap" %}
```json
{
"success": true,
"meta_data": {
"bulk_request_id": "01a03e32-cbf1-7406-a423-462adab9ed65",
"total_count": 105,
"accepted_count": 100,
"invalid_count": 0,
"insufficient_credit_count": 0,
"failed_count": 0,
"rate_limit_exceeded_count": 5
},
"data": {
"accepted": [
{
"group_id": "01a03e32-cbf9-71e4-af94-c8d1fda44a3c",
"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": [
{
"group_id": "01a03e32-cbf9-71e4-af43-c8d1fda54b1e",
"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 %}
#### **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. |
Sample Response – insufficient credit (80 sent, 74 accepted, 6 dropped)
{% code overflow="wrap" %}
```json
{
"success": true,
"meta_data": {
"bulk_request_id": "01a03e32-cbf1-7406-a423-462bcab6ar23",
"total_count": 80,
"accepted_count": 74,
"invalid_count": 0,
"insufficient_credit_count": 6,
"failed_count": 0,
"rate_limit_exceeded_count": 0
},
"data": {
"accepted": [
{
"group_id": "01a03e32-cbf9-71e4-af54-c7d1fda44a3k",
"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": [
{
"group_id": "01a03e32-cbf9-71e4-af94-c8d4alo98b4s",
"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 %}
### 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`. |
| `group_id` | string | data.accepted\[] | Identifier of the group this item forms. Each object in your request array becomes one group. |
#### **`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`. |
{% hint style="info" %}
Each bulk request is traceable through three identifiers: `meta_data.bulk_request_id` identifies the whole batch, each item's `group_id` identifies one object from your request array, and each `results[].id` identifies a single query within that group.
{% endhint %}
Sample results[] by input type
{% 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 %}
### 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.