Handle Asynchronous Requests

Many operations in the Version API, such as duplicating a version, activating a version, or uploading a large product catalog, are resource-intensive. To prevent timeouts and ensure system stability, DealHub processes these requests asynchronously.

This guide explains how to track these background processes to determine when they are complete and if they were successful.

How it Works

When you initiate an asynchronous operation (like Activate a Version), the API does not wait for the task to finish. Instead, it immediately returns a 200 OK response containing a unique tracking identifier called a request_id.

{
  "request_id": "4D114DAD97"
}

You must use this ID to monitor the progress of the task.

Step 1: Check Request Status

To check the current state of a job, use the Get Asynchronous Request Status endpoint. Send a GET /api/v1/request/{request_id}/status request using the request_id you received:

curl --location 'https://api.dealhub.io/api/v1/request/4D114DAD97/status' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

The system returns the current status of the job.

{
  "request_id": "4D114DAD97",
  "status": "in-progress",
  "error_description": "",
  "error_code": null
}

The status field will contain one of the following values:

📘

Polling Strategy

We recommend implementing a "backoff" strategy for polling. Check the status every 5–10 seconds initially. If the job runs longer, increase the interval to reduce API traffic. Alternatively, you can listen for Webhook events to be notified immediately upon completion.

⚠️

Large payloads may cause requests to remain in queued status

Requests that include a large number of SKUs, typically above 500, may get stuck in queued and fail to advance to in-progress . This is a known issue currently under investigation.

To reduce the risk of this happening:

• Keep the number of SKUs per request below 500.
• If you need to push a large catalog, split it into smaller batches and submit each batch as a separate request.
• Monitor each requestId individually when batching.

Step 2: Retrieve Execution Summary

For complex operations like Product Catalog Upload, a simple "done" status might not be enough. You may need to know how many products were created successfully versus how many were skipped due to warnings.

Once the request status is done, you can retrieve a detailed report using the Get Asynchronous Request Execution Summary endpoint . Send a GET /api/v1/request/{request_id}/summary request:

curl --location 'https://api.dealhub.io/api/v1/request/4D114DAD97/summary' \
--header 'Authorization: Bearer <YOUR_TOKEN>'

The response provides a breakdown of the operation's results .

{
  "status": "Completed",
  "summary": {
    "success_count": 150,
    "errors_count": 0,
    "warnings": [
      "Missing currency in price item for SKU KY014X, using default currency: USD"
    ],
    "errors": []
  }
}

The following table describes the information from the API response:

Next Steps

• Updating the Product Catalog: Learn how to initiate the large upload jobs that require this monitoring.

📘

Related API Reference

The following API Reference pages document the endpoints used in this guide:

• Get Asynchronous Request Status
• Get Asynchronous Request Execution Summary