Get Batch

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

• Endpoint
• Request
• Response
• Response Example

Endpoint

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."
}