Get Batch

This method is used to retrieve details of a shipment batch including its items and validation results.

Endpoint

Method URI Headers
GET /batches/{batch_id} default

Request

Field Required Type Description
batch_id Yes String The batch hash ID. (URL parameter)
status No String Filter items by status. Options: valid, invalid, completed, failed.

Response

Field Type Description
id String The batch hash ID.
status String Current batch status: validating, invalid, ready, processing, or completed.
default_service String The service code set for this batch.
default_shipper_id String The shipper hash ID for this batch.
results {} Object Batch statistics.
+total_count Integer Total number of items in the batch.
+completion_percentage String Percentage of completed items.
+valid_count Integer Number of valid items.
+invalid_count Integer Number of invalid items.
+completed_count Integer Number of successfully shipped items.
+failed_count Integer Number of items that failed during shipping.
items {} Object Paginated list of batch items.
+current_page Integer Current page number.
+data [] Array Array of batch item objects.
++id String The item hash ID.
++status String Item status: valid, invalid, completed, or failed.
++errors Object/Null Object of validation error messages (if status is invalid), null otherwise.
++shipment_order Object/Null The shipment order object if item is completed, null otherwise.
+++main_tracking_number String The main tracking number for the shipment.
+first_page_url String URL to the first page.
+from Integer Starting item number on current page.
+next_page_url String/Null URL to the next page, null if on last page.
+path String Base URL path.
+per_page Integer Number of items per page.
+prev_page_url String/Null URL to the previous page, null if on first page.
+to Integer Ending item number on current page.
labels [] Array Array of merged label PDF URLs (only present when batch is completed).

Response Examples

Successful (Ready Status)

{
    "success": true,
    "data": {
        "id": "12345678",
        "status": "ready",
        "default_service": "USPS-3",
        "default_shipper_id": "99999999",
        "results": {
            "total_count": 10,
            "valid_count": 10,
            "invalid_count": 0,
            "completed_count": 0,
            "failed_count": 0,
            "completion_percentage": "0%"
        },
        "items": {
            "current_page": 1,
            "data": [
                {
                    "id": "d34b4588-8e98-4e26-8ae8-5145f6a61c47",
                    "status": "valid",
                    "errors": null,
                    "shipment_order": null
                },
                {
                    "id": "a12c5678-9f01-4b23-cdef-6789abcd0123",
                    "status": "valid",
                    "errors": null,
                    "shipment_order": null
                }
            ],
            "first_page_url": "https://api.deftship.com/api/batches/12345678?page=1",
            "from": 1,
            "next_page_url": null,
            "path": "https://api.deftship.com/api/batches/12345678",
            "per_page": 100,
            "prev_page_url": null,
            "to": 2
        }
    }
}

Successful (Processing Status)

{
    "success": true,
    "data": {
        "id": "12345678",
        "status": "processing",
        "default_service": "USPS-3",
        "default_shipper_id": "99999999",
        "results": {
            "total_count": 10,
            "valid_count": 10,
            "invalid_count": 0,
            "completed_count": 2,
            "failed_count": 1,
            "completion_percentage": "30%"
        },
        "labels": [
            "https://storage.example.com/labels/batch-12345678-1.pdf"
        ],
        "items": {
            "current_page": 1,
            "data": [
                {
                    "id": "d34b4588-8e98-4e26-8ae8-5145f6a61c47",
                    "status": "completed",
                    "errors": null,
                    "shipment_order": {
                        "main_tracking_number": "9400111899223456789012"
                    }
                },
                {
                    "id": "a12c5678-9f01-4b23-cdef-6789abcd0123",
                    "status": "completed",
                    "errors": null,
                    "shipment_order": {
                        "main_tracking_number": "9400111899223456789013"
                    }
                }
            ],
            "first_page_url": "https://api.deftship.com/api/batches/12345678?page=1",
            "from": 1,
            "next_page_url": null,
            "path": "https://api.deftship.com/api/batches/12345678",
            "per_page": 100,
            "prev_page_url": null,
            "to": 2
        }
    }
}

Failed

{
    "success": false,
    "message": "Batch not found."
}