Bulk Service Response

When you submit a Bulk Service Request, the response tells you which input values were accepted and which were rejected, and why. It does not contain the parsed Amazon data: each accepted value gets a result id that you use to fetch the data from the Data Service.

Response structure

success
message                      only when the whole request fails
meta_data
  bulk_request_id
  total_count
  accepted_count
  invalid_count
  insufficient_credit_count
  failed_count
  rate_limit_exceeded_count
data
  accepted[]                 one object per accepted group
    platform, operation, domain, callback_url, group_id
    ship_to
      zipCode[]
    results[]                one entry per input value
      id, credit, asin | keyword | seller_id | url | link | identifier | ...
  invalid[]
  failed[]
  insufficient_credit[]
  rate_limit_exceeded[]

Response fields

Top-level fields

Field	Type	Description
success	boolean	true when the request was processed, even if only some items were accepted. false only when the whole request is malformed.
message	string	Short error description, present only when the request fails. Example: Bad request.
meta_data	object	Counts for the whole request.
data	object	Items grouped by outcome.

meta_data

Each count equals the number of items in the array of the same name in data (for example, invalid_count is the number of items in data.invalid).

Field	Type	Description
bulk_request_id	string	ID of this whole submission. Use it to find the request on the Bulk Requests page of the web app.
total_count	integer	Number of input values in the request.
accepted_count	integer	Values accepted and queued for processing.
invalid_count	integer	Values rejected by validation.
insufficient_credit_count	integer	Values not accepted because your credits ran out.
failed_count	integer	Values that hit a server-side failure.
rate_limit_exceeded_count	integer	Values not accepted because the per-minute limit was reached.

data

Each item appears in exactly one array. Empty arrays may be left out of the response.

Field	Type	Description
accepted	array	Accepted groups with their result IDs.
invalid	array	Items rejected by validation.
failed	array	Items that hit a server-side failure.
insufficient_credit	array	Items dropped because your credits ran out.
rate_limit_exceeded	array	Items dropped because the per-minute limit was reached.

Every item carries a group_id that identifies the request object it came from, whichever array it ends up in.

data.accepted[]

Each object echoes one accepted group from your request and lists its queries under results.

Field	Type	Description
platform	string	Platform of the group, for example AMZ.
operation	string	Operation of the group, for example DETAIL.
domain	string	Marketplace of the group, for example .com.
callback_url	string	URL that receives the webhook for each finished query. The webhook does not carry the parsed data.
ship_to	object	Delivery location used for the group. Without address_id, the marketplace default is used.
ship_to.zipCode	array	Zip code or codes used to localize the requests.
group_id	string	ID of this group. Each object in your request array becomes one group.
results	array	One entry per input value, each with its own result id.

results[]

Each entry is one query. id and credit are always present; the other fields depend on the operation and the input key you sent.

Field	Type	Description
id	string	Result ID. Use it to fetch the result from the Data Service.
credit	integer	Credits charged for this query, using the same rules as the Real-Time API. Example: 6 for SIMILAR_PRODUCTS with similar_limit 50.
asin	string	Submitted ASIN. For ASIN input (DETAIL, OFFER, SIMILAR_PRODUCTS and other ASIN operations).
keyword	string	Submitted search term. For SEARCH with keywords.
seller_id	string	Submitted seller ID. For SELLER_PROFILE, SELLER_PRODUCTS, SELLER_FEEDBACK with seller_ids.
url	string	Submitted full URL. For URL input. Seller URLs use the /sp?seller= form (SELLER_PROFILE, SELLER_FEEDBACK) or the /s?me= form (SELLER_PRODUCTS).
link	string	Relative path of the submitted URL. For URL input, except SELLER_FEEDBACK, which returns only url.
identifier	string	Submitted product code. For PRODUCT_LOOKUP.
identifier_type	string	Code type used for the lookup, for example UPC. For PRODUCT_LOOKUP.
min_rating	integer	Echo of the minimum rating filter. For SELLER_FEEDBACK. When you do not send a filter, none is applied and the echoed value may be 0.
max_rating	integer	Echo of the maximum rating filter. For SELLER_FEEDBACK. When you do not send a filter, none is applied and the echoed value may be 0.
similar_limit	integer	Echo of similar_limit. For SIMILAR_PRODUCTS.

Note

Three IDs trace a bulk request: meta_data.bulk_request_id identifies the whole submission, group_id identifies one object from your request array, and results[].id identifies one query. Only results[].id works with the Data Service.

data.invalid[]

Each object describes a validation error in the request.

Field	Type	Description
value	string	Submitted value that caused the rejection.
message	string	Reason for the rejection, including the value and its index. Example: Invalid seller_id format at index 0: "AAK72K4OIWDXL827362".
path	string	General location of the error, for example body.
instancePath	string	Path to the invalid field in the request, for example /0/payload/seller_ids/0.
platform	string	Platform of the rejected group.
operation	string	Operation of the rejected group.
domain	string	Marketplace of the rejected group.
payload_count	integer	Number of input values in the rejected group's payload.
group_id	string	ID of the group the item belongs to.

data.failed[]

Each object is an item that passed validation but hit a server-side failure. The original request fields are echoed so you can identify and resend the item.

Field	Type	Description
id	string	ID assigned to the failed item.
platform	string	Platform of the item.
operation	string	Operation of the item.
domain	string	Marketplace of the item.
payload	object	The single input value, for example { "asin": "0000306037" }.
callback_url	string	Callback URL sent with the request.
group_id	string	ID of the group the item belongs to.

data.rate_limit_exceeded[]

Each object is an item dropped because your plan's Bulk API per-minute limit was reached. The rest of the request is still processed.

Field	Type	Description
message	string	Error message: [!] Minute request limit exceeded.
payload	object	The dropped item, with its assigned id and credit.
payload.platform	string	Platform of the item.
payload.operation	string	Operation of the item.
payload.domain	string	Marketplace of the item.
payload.payload	object	The single input value, for example { "asin": "B000PXYADK" }.
payload.callback_url	string	Callback URL sent with the request.
payload.id	string	ID assigned to the dropped item.
payload.credit	integer	Nominal credit cost of the item. Not charged.
group_id	string	ID of the group the item belongs to.

data.insufficient_credit[]

Items are accepted in order until your credits run out. Each remaining item is returned here with the same structure as data.rate_limit_exceeded[].

Field	Type	Description
message	string	Error message: [!] You do not have enough credit to perform this action.
payload	object	The dropped item, with platform, operation, domain, payload, callback_url, id and credit as in data.rate_limit_exceeded[].
group_id	string	ID of the group the item belongs to.

Status values

Each input value is evaluated on its own, so one request can have several outcomes. success stays true in that case, and the meta_data counts show the split. Check the arrays rather than success alone.

Outcome	Array	Charged	What to do
Accepted	data.accepted	Yes, the credit of each result	Store each results[].id and fetch the result from the Data Service.
Invalid	data.invalid	No	Fix the value at instancePath and send it again.
Failed	data.failed	No	Send the item again in a new request.
Insufficient credit	data.insufficient_credit	No	Add credits or wait for your credits to reset, then send the items again.
Rate limit exceeded	data.rate_limit_exceeded	No	Send the items again after the current minute.

Note

Credits are charged only for items in data.accepted. A credit value on a dropped item shows its nominal cost, not a charge.

An accepted query is processed in the background and ends with status success or failure. Easyparser then sends a webhook to the group's callback_url. See Data Service Response for the query record and its statuses. Results are kept for at most 24 hours.

Sample responses

Sample response: all items accepted (DETAIL, .com)

{
  "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": []
  }
}

Sample response: invalid item (wrong seller_id)

{
  "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": []
  }
}

Sample response: failed items

{
  "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": []
  }
}

Sample response: rate-limited items (105 sent, 100 accepted, 5 rate-limited)

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

Sample response: insufficient credit (80 sent, 74 accepted, 6 dropped)

{
  "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": []
  }
}

Sample results[] entries by input type

// 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 }

// SIMILAR_PRODUCTS
{ "asin": "B0G2V8898X", "similar_limit": 50, "id": "01a1399a-cb8d-7361-90b0-2f370ece0155", "credit": 6 }

Errors

Problems with single items do not fail the request; they appear in the outcome arrays above. The request as a whole fails only when it cannot be processed.

Case	What you receive
Malformed request body	success is false and message describes the error, for example Bad request.
Missing api-key header	Error MSG0035: Request header does not have api-key.
Invalid API key	Error MSG0023: Invalid API Key. Please verify your API key is valid.
Value fails validation	Item in data.invalid, for example Invalid seller_id format at index 0.
Credits run out	Remaining items in data.insufficient_credit: [!] You do not have enough credit to perform this action.
Per-minute limit reached	Items above the limit in data.rate_limit_exceeded: [!] Minute request limit exceeded.

Related

• Bulk Service Request
• Data Service Request
• Data Service Response
• Bulk API overview
• Credit Consumption