Bulk Service Response

🧩 What is the Bulk Response?

After you submit a valid Bulk Create request, the system returns a response indicating whether each item in your batch was successfully accepted, rejected, or failed due to specific reasons (e.g., invalid data, insufficient credit, rate limiting).

This response contains two main sections:

1. meta_data – Summary of the overall batch result

2. data – Detailed result per request

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

🔍 Understanding the Response

success

• Indicates whether the bulk request itself was processed without critical errors.

• Note: Even if success is true, some individual items may still be invalid or rejected.

📊 meta_data Object

Field	Description
total_count	Total number of individual items in your request payload
accepted_count	Items that were successfully accepted and queued for processing
invalid_count	Items that failed due to validation errors (e.g., missing required fields)
insufficient_credit_count	Items not accepted due to lack of API credits
failed_count	Items that failed due to internal errors (rare)
rate_limit_exceeded_count	Items not accepted because you exceeded request rate limits

📦 data Object

This object contains categorized arrays:

• accepted: Each item accepted for processing. Includes the generated ids used in the next step.

• invalid: Malformed or missing data.

• failed: Server-side failure (e.g. upstream service down).

• insufficient_credit: Requests dropped due to credit shortage.

• rate_limit_exceeded: Requests dropped due to rate-limiting constraints.

📌 What Does Each Accepted Item Contain?

Each accepted item returns the IDs of the individual sub-queries and related information within the results field. These IDs will later be used to retrieve the data via the Data Service.

Field	Type	Description
platform	string	The platform the operation is targeting (e.g., AMZ)
operation	string	Type of operation requested (e.g., SEARCH, DETAIL)
domain	string	Domain of the target marketplace (e.g., .com, .ca)
callback_url	string	Webhook address where results will be sent when ready
ship_to	object	(Optional) Includes destination details like zipCode
results	array of objects	List of individual query results with IDs and additional info

🔹 results[] – Breakdown

Field	Type	Description
id	string	Unique identifier assigned to this particular query. Use it in Data Service.
credit	number	Number of credits consumed by this query (usually 1)
link	string	(Only for DETAIL/SEARCH) The relative product/search link submitted
asin	string	(Only for DETAIL/OFFER) The ASIN of the product being queried
keyword	string	(If used) The keyword provided in the payload for a keyword-based search

Once the results[].id values are returned for each query: Use these IDs to request results via the Data Service Request endpoint.