# Get Batch Shipment Details

"This API operation provides the shipment details for those shipments which are SUCCESS or FAILED during batch processing at the following levels:
- addressValidation
- rating
- labelGeneration, and
- voidLabel

Based on fields/data mentioned in Query Parameter, user can check shipment details for particular status at any levels. 
If no values are provided in the fields mentioned in Query Parameter, the default for each will be:
- Page: 1
- Size: 20
- Status: SUCCESS/FAILED.

Endpoint: GET /api/v1/shipments/batch/{batchId}/shipments
Version: 1.0.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Path parameters:

  - `batchId` (string, required)
    This is a system-generated unique identifier assigned to the Batch while it is processed

## Query parameters:

  - `page` (integer)
    It returns detailed information for shipments status and it can cover in one or more pages. The default value for page number is 1.

  - `size` (integer)
    Indicates the number of records per page. The default value for records is 20.

  - `status` (string)
    The status of the shipment. Values can be Failed or Success.

  - `step` (string)
    Indicates various stages of the batch processing.

## Header parameters:

  - `X-PB-Developer-Partner-ID` (string)
    The Developer-Partner- ID is assigned by PB to uniquely identify a Developer's strategic business partners. If the developer is the sole business partner, this field is not required.

## Response 200:

  - `200` (unknown)
    Detailed status of processed shipments for the batch.

## Response 200 fields (application/json):

  - `data` (array)
    It displays all the shipment details based on the paramter selected in the request body.

  - `data.batchId` (string)
    This is a system-generated unique identifier assigned to the Batch while it is processed.
    Example: RgYgaV7mKax

  - `data.carrierAccountId` (string)
    A unique identifier associated with the Carrier account used by client users during shipment process.
    Example: GpoVzzeQ37l

  - `data.externalId` (string)
    This is a user-defined value provided by users just for their reference. This is for mapping purpose against each shipment.
    Example: 1

  - `data.fromAddress` (object)
    The complete address of the Sender.

  - `data.fromAddress.name` (string, required)
    The name of the Sender to which this address points. `Max length = 40`
    Example: Anupama

  - `data.fromAddress.addressLine1` (string, required)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Sender.  `Max length = 40`
    Example: 27 Watervw Dr

  - `data.fromAddress.addressLine2` (string)
    The addressLine2 contains the Area or Street Name. This is an optional field.  `Max length = 40`
    Example: Street-257

  - `data.fromAddress.addressLine3` (string)
    The addressLine3 contains other details for easy reach, e.g. Landmark. This is an optional field.  `Max length = 40`
    Example: Near XZ Tower

  - `data.fromAddress.cityTown` (string, required)
    The name of the city or town the Sender's address belongs to.
    Example: Stamford

  - `data.fromAddress.stateProvince` (string, required)
    The name of the State or Province the Sender belongs to. It is the `2-letter` State or Province Code for US or Canadian address(es).  Below is the hyperlink for CA country that will navigate to its Province/State Codes page. Similarly, respective country users can check for their country- State/Province codes.  Please switch to the `Search` tab, select `Country codes` radio button, enter the required country name or country code, and then click `SEARCH` button.
    Example: CT

  - `data.fromAddress.postalCode` (string, required)
    The Postal Code or ZIP Code of the address.  For US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'.  While for CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'.   *NOTE: USPS supports only US location.*
    Example: 6905

  - `data.fromAddress.inductionPostalCode` (string)
    The postal code where the shipment is tendered to the carrier. If an induction postal code is specified in the "fromAddress", it will be used for rate calculations and determining manifest eligibility instead of the standard postal code. If not specified, the postal code from the "fromAddress" will be used. Supported for Create Bulk Shipment API.
    Example: 06905

  - `data.fromAddress.countryCode` (string, required)
    The country in which the sender's address is located. The value will be the two-character ISO Code of the country from the ISO country list.  Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.  Below is the hyperlink, please select `Country codes` and then click `SEARCH` button.  *NOTE: USPS supports only US location.*
    Example: US

  - `data.fromAddress.company` (string)
    The name of the company, in case if the sender address is not residential.
    Example: PB

  - `data.fromAddress.phone` (string)
    This is sender's phone number. Enter the digits with or without spaces or hyphens.  `Max length = 15`.
    Example: 203-555-1213

  - `data.fromAddress.email` (string)
    This must be sender's valid email.  `Max length = 50`
    Example: anupama.k@gmail.com

  - `data.fromAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `data.labelLayout` (object)
    Label layout details

  - `data.labelLayout.fileFormat` (string)
    Defines the format of the document file the print takes.
    Example: PDF

  - `data.labelLayout.printReceipt` (boolean)
    This option asks if the receipt is to be printed.
    Example: true

  - `data.labelLayout.size` (string)
    Defines the label size of the Shipment, that is, the Shipping Label is available in different Doc Size.
    Enum: "DOC_8X11", "DOC_4X6"

  - `data.labelLayout.type` (string)
    This indicates the type of the label
    Example: SHIPPING_LABEL

  - `data.metadata` (array)
    Additional metadata that needs to be stored for this shipment can be added here. For now, `costAccountName` is supported.

  - `data.metadata.name` (string)
    The key of metadata is CostAccount. User needs to enter the name of the CostAccount.
    Enum: "costAccountName"

  - `data.metadata.value` (string)
    User needs to enter the Cost Account Code.
    Example: CostAccount-00PBPUN

  - `data.parcel` (object)
    The details of the Parcel.

  - `data.parcel.length` (number)
    Length is always the greatest of the three dimensions. The other two dimensions are used in the calculation of the girth.
    Example: 2

  - `data.parcel.width` (number)
    There is no strict rule as to which element is the width or the height, but the width is the second greatest dimension of a parcel by convention.
    Example: 1

  - `data.parcel.height` (number)
    By convention the height is the smallest dimension of the parcel.
    Example: 1

  - `data.parcel.dimUnit` (string)
    DimUnit is a standard for measuring the physical quantities of specified dimension parameters. The valid values are: Inch and Centimeter.
    Enum: "IN", "CM"

  - `data.parcel.weightUnit` (string, required)
    WeightUnit is a standard for measuring the physical quantities of specified weight. The valid values are: Ounces and Grams. For USPS shipments, set this to OZ.
    Enum: "OZ", "GM"

  - `data.parcel.weight` (number)
    Weight measures the heaviness of an object (how heavy an object is) .
    Example: 2

  - `data.parcelType` (string)
    Parcel Type is required for creating a shipment while rating a parcel. And it varies as per carrier selection and corresponding services.
    Example: LP

  - `data.serviceId` (string)
    A unique identifier given to the carrier-specific service. User can override this value by defining it at Shipment level.
    Example: LIB

  - `data.shipmentId` (string)
    Shipment ID is a unique identifier for an individual shipment
    Example: USPS2200589023653912

  - `data.parcelTrackingNumber` (string)
    The `parcelTrackingNumber` is a unique identifier assigned to a shipment for tracking.
    Example: 9407809105156003660859

  - `data.shipmentIdentifier` (string)
    Unique identifier generated for each shipment, it can be either success or failed.
    Example: USPS2200589023653912

  - `data.shipmentOptions` (object)

  - `data.shipmentOptions.addToManifest` (boolean)
    This option asks if the shipment is to be added for Manifest, so that the shipment can be reflected in the Manifest Form while compilation. The value can be 'true' or 'false'. Applicable for USPS.
    Example: true

  - `data.shipmentOptions.printCustomMessage` (string)
    This prints a custom message on shipping label.
    Example: Print Message 1

  - `data.shipmentOptions.receiptOption` (string)
    It provides options to print receipt with shipping label. Only applicable for USPS, can take values- RECEIPT_ONLY or RECEIPT_WITH_INSTRUCTIONS or NO_OPTIONS.
    Enum: "RECEIPT_ONLY", "RECEIPT_WITH_INSTRUCTIONS", "NO_OPTIONS"

  - `data.shipmentOptions.printDepartment` (string)
    This prints Department name on the shipping label. This is applicable for FedEx.
    Example: department

  - `data.shipmentOptions.printInvoiceNumber` (string)
    This prints Invoice Number on the shipping label. This is applicable for FedEx.
    Example: invoicenumber

  - `data.shipmentOptions.printPONumber` (string)
    This prints PO number on the shipping label. This is applicable for FedEx.
    Example: ponumber

  - `data.shipmentOptions.minimalAddressValidation` (boolean)
    Allows performing minimal address validation during shipment creation. the addressLine1 field is not validated if set to true.
Minimal address validation is supported only for these APIs:
- Create Shipment
- Create Bulk Shipments
- Create Multipiece Shipment
    Enum: "true", "false"

  - `data.shipmentOptions.billingWeight` (string)
    The weight used by the carrier to calculate the shipping cost. This value is determined as the greater of the actual weight and the dimensional weight.
    Example: 128.0

  - `data.shipmentOptions.bookingConfirmationNumber` (string)
    This is an advanced booking number required for FedEx Express Freight shipments. It must be obtained through the appropriate channel in the shipment's origin country. Without a valid booking confirmation number, pickup and space allocation for the shipment are not guaranteed. The booking number must be between 5 and 12 digits.
    Example: XXXX56789812

  - `data.specialServices` (array)
    Special services used to create shipment
    Example: [{"fee":0,"specialServiceId":"DelCon"}]

  - `data.specialServices.fee` (number)
    The amount of the surcharge.
    Example: 0

  - `data.specialServices.specialServiceId` (string)
    A unique identifier associated with the Special Service, will be mentioned in this column. If user selects additional service will be entered here.
    Example: DelCon

  - `data.stepStatus` (object)
    It displays different status of shipments at each level- addressValidation, rating, labelGeneration, and voidLabel.

  - `data.stepStatus.import` (string)
    This is only visible for batch submitted during Import via .CSV.
    Example: SUCCESS

  - `data.stepStatus.addressValidation` (string)
    It indicates the status of shipments at addressValidation stage.
    Example: SUCCESS

  - `data.stepStatus.rating` (string)
    It indicates status of shipments at rating level.
    Example: SUCCESS

  - `data.stepStatus.labelGeneration` (string)
    It indicates status of shipments at labelGeneration step.
    Example: SUCCESS

  - `data.stepStatus.voidLabel` (string)
    It will only be visible when batch labels are cancelled.
    Example: SUCCESS

  - `data.toAddress` (object)
    The complete address of the Recipient or Department (in case if the address is not pointed to any individual recipient).

  - `data.toAddress.name` (string, required)
    The name of the Recipient.  `Max length = 40`
    Example: John Smith

  - `data.toAddress.addressLine1` (string, required)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Recipient.  `Max length = 40`
    Example: 98 Watervw Dr

  - `data.toAddress.addressLine2` (string)
    The addressLine2 contains the Area or Street Name. This is an optional field.  `Max length = 40`
    Example: Street-975

  - `data.toAddress.addressLine3` (string)
    The addressLine3 contains other details for easy reach, e.g. Landmark. This is an optional field.  `Max length = 40`
    Example: Near ABC Tower

  - `data.toAddress.cityTown` (string, required)
    The name of the city or town the Recipient belongs to.
    Example: Shelton

  - `data.toAddress.stateProvince` (string, required)
    The name of the State or Province the Sender belongs to. It is the `2-letter` State or Province Code for US or Canadian address(es).  Below is the hyperlink for CA country that will navigate to its Province/State Codes page. Similarly, respective country users can check for their country- State/Province codes.  Please switch to the `Search` tab, select `Country codes` radio button, enter the required country name or country code, and then click `SEARCH` button .  `Max length = 2`
    Example: CT

  - `data.toAddress.postalCode` (string, required)
    The Postal Code or ZIP Code of the address. For US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'.  While for CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'. ERR supports only US addresses. *NOTE: USPS supports only US location.*
    Example: 6905

  - `data.toAddress.countryCode` (string, required)
    The country in which the recipient's address is located. The value will be the two-character ISO Code of the country from the ISO country list.  Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.  Below is the hyperlink, please select `Country codes` and then click `SEARCH` button.   *NOTE: USPS supports only US location.*
    Example: US

  - `data.toAddress.company` (string)
    The name of the company, in case if the Recipient address is not residential.
    Example: PB

  - `data.toAddress.phone` (string)
    This is recipient's phone number. Enter the digits with or without spaces or hyphens.  `Max length = 15`.
    Example: 203-555-1213

  - `data.toAddress.email` (string)
    This must be recipients's valid email.  `Max length = 50`
    Example: anupama.kr@gmail.com

  - `data.toAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `data.additionalAddresses` (array)
    A list of additional addresses associated with the shipment.
- Each object includes an address and its designated type, such as BROKER or other parties involved in customs or shipping processes.
- Additional address could be domestic or International both.

  - `data.additionalAddresses.address` (object)
    The additional address details.

  - `data.additionalAddresses.address.residential` (boolean)
    If the address is residential.
    Example: false

  - `data.additionalAddresses.address.phone` (string)
    Contact phone number for the address.
    Example: 732-443-1007

  - `data.additionalAddresses.address.countryCode` (string)
    The ISO 2-letter country code.
    Example: US

  - `data.additionalAddresses.address.postalCode` (string)
    ZIP or postal code.
    Example: 08810-1411

  - `data.additionalAddresses.address.cityTown` (string)
    Name of the city or town.
    Example: DAYTON

  - `data.additionalAddresses.address.name` (string)
    Name of the contact person.
    Example: Warehouse Manager

  - `data.additionalAddresses.address.stateProvince` (string)
    State or province code.
    Example: NJ

  - `data.additionalAddresses.address.addressLine1` (string)
    Primary street address line.
    Example: 2270 US HIGHWAY 130

  - `data.additionalAddresses.addressType` (string)
    Type of the additional address (e.g., BROKER). This is required if passing `additionalAddresses`.  **Note** The addressType `SHIPPER` is returned only in USPS responses.
    Enum: "HOLD", "BROKER", "THIRD_PARTY", "PICKUP", "EXPORTER", "ALT_DELIVERY", "SHIPPER"

  - `data.altReturnAddress` (object)
    This is an optional field. if a package shipped from Location_A to Location_B needs to return to Location_C. The alternate address will be printed on the label. Use this object to specify a return address different from the fromAddress. Supported by FedEx, UPS, and Purolator.

  - `data.altReturnAddress.addressLine1` (string)
    The first line of the alternate return address, such as a street address or PO Box.
    Example: 27 Waterview Dr

  - `data.altReturnAddress.addressLine2` (string)
    The addressLine2 contains Street address or Landmark (if any).
    Example: near abc street

  - `data.altReturnAddress.addressLine3` (string)
    The addressLine3 contains P.O. Box (if any) near the address.
    Example: near xyz street

  - `data.altReturnAddress.company` (string)
    The name of the company for the alternate return address, in case if the recipient's address is not residential.  `Max length = 30`.
    Example: PB

  - `data.altReturnAddress.email` (string)
    The email address of the recipient. It can be person's email address or company email address (for non-residential).
    Example: user@email.com

  - `data.altReturnAddress.residential` (boolean)
    The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `data.altReturnAddress.cityTown` (string)
    The city or town for the alternate return address.
    Example: Shelton

  - `data.altReturnAddress.countryCode` (string)
    The two-character ISO Code of the source country from this ISO country list.  The country in which the address is located. Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.
    Example: US

  - `data.altReturnAddress.name` (string)
    The name of the recipient or organization for the alternate return address.
    Example: User Name

  - `data.altReturnAddress.phone` (string)
    The phone number associated with the alternate return address.
    Example: 203-555-1213

  - `data.altReturnAddress.postalCode` (string)
    The postal or ZIP code for the alternate return address.
    Example: 06484

  - `data.altReturnAddress.stateProvince` (string)
    The 2-letter state or province code for the alternate return address.
    Example: CT

  - `pageInfo` (object)
    It displays the pagination details.

  - `pageInfo.page` (number)
    It displays current page number.
    Example: 1

  - `pageInfo.pages` (number)
    It displays total number of pages.
    Example: 1

  - `pageInfo.total` (number)
    It displays total records which are filtered.
    Example: 2

## Response 400:

  - `400` (unknown)
    Invalid request.

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g. validation-error.
    Example: validation_error

  - `errorDescription` (string)
    The HTTP 400 Bad/Invalid Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
    Example: Error while getting rates for carrier with carrierAccount eRMnRx4mzPP.

  - `additionalCode` (string)
    A unique identifier for the error, for example 1101055, 0100008, or 1021126.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing.

  - `additionalParameters` (array)

## Response 401:

  - `401` (unknown)
    The request could not be authorized.

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

## Response 404:

  - `404` (unknown)
    The requested resource was not found.

## Response 404 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due HTTP 404 Page or File not found.
    Example: not_found

  - `errorDescription` (string)
    The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.
    Example: resource not found

  - `additionalCode` (string)
    A unique identifier for the error, for example 0100025, 1110017, or 1090001.

  - `additionalInfo` (string)
    Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`.

  - `additionalParameters` (array)

## Response 500:

  - `500` (unknown)
    The request could not be completed due to an internal server error.

## Response 500 fields (application/json):

  - `message` (string, required)
    This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.