# Get Shipment Transaction Report

This Operation returns the report of shipments transactions within the specified date range.

Endpoint: GET /api/v1/shipments
Version: 1.0.0
Security: bearerAuth

## Query parameters:

  - `startDate` (string)
    Start date for the transaction report, in UTC format (e.g., `2025-08-01T00:00:00Z`). default start date is today.

  - `endDate` (string)
    End date for the transaction report, in UTC format (e.g., `2025-08-15T23:59:59Z`). Default end date is today.

  - `size` (number)
    Number of transaction reports per page. Used for pagination.

  - `page` (string)
    Page number to fetch in paginated results.

  - `carrier` (string)
    Filter shipments transaction report by carrier code (e.g., `UPS`, `FEDEX`, `USPS`).

  - `insurance` (boolean)
    Filter shipments by insurance status. Set to `true` for insured shipments, `false` otherwise.

  - `returnLabel` (boolean)
    Filter shipments that include return labels. Set to `true` to return only shipments with return labels, `false` otherwise.

  - `isInternational` (boolean)
    Filter shipments by type. Set `true` for international shipments, `false` for domestic shipments.

  - `refundEligible` (boolean)
    Filter shipments eligible for refund.

  - `merchant` (boolean)
    Filter merchant shipments transaction report.
- **true** → Returns shipment transaction reports for all merchants associated with the developer.   
- To view the transaction report for a **specific merchant**, include the header `X-PB-Developer-Partner-ID` with the value set to that merchant's `subscriptionId`.

  - `shipmentType` (string)
    Filter by shipment type. Accepted values:
- `multipiece`: multi-piece shipments
- `apv`: Adjusted Posted Value (APV) shipments
If omitted, all shipment types are returned.

## Header parameters:

  - `X-PB-Developer-Partner-ID` (string)
    This is the Developer Partner ID.

## Response 200 fields (application/json):

  - `data` (array)
    List of shipment transactions.

  - `data.correlationId` (string)
    Unique identifier assigned by the shipping system to the transaction.
    Example: 2e95966e870e4a40bba8c76bac0f667e

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

  - `data.fromAddress.name` (string)
    The name of the Sender to which this address points.
    Example: Sender Name

  - `data.fromAddress.addressLine1` (string)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Sender.  `Max length = 35`.
    Example: 1600 Amphitheatre Parkway

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

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

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

  - `data.fromAddress.email` (string)
    This must be senders's valid email. Email is required if the customer is using GoFor Carrier.  `Max length = 30`
    Example: testuser@gmail.com

  - `data.fromAddress.phone` (string)
    This is sender's phone number. Enter the digits with or without spaces or hyphens. The maximum limit of characters for Phone number are 10 digits.
    Example: 6502530000

  - `data.fromAddress.cityTown` (string)
    The name of the city or town the Sender's address belongs to.  `Max length = 30`.
    Example: Mountain View

  - `data.fromAddress.stateProvince` (string)
    "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: CA

  - `data.fromAddress.postalCode` (string)
    The Postal Code or ZIP Code of the address.  For CA addresses, use a `six-character` alphanumeric string Postal Code in this format: 'A1A 1A1'.  While for US addresses, use either the `5-digit` or `9-digit` ZIP Code in one of the following formats: '12345' or '12345-6789'.  `Max length = 10`
    Example: 94043

  - `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.
    Example: 06905

  - `data.fromAddress.countryCode` (string)
    "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.  `Max length = 2`"
    Example: US

  - `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.toAddress` (object)
    The complete address of the Recipient.

  - `data.toAddress.name` (string)
    The name of the Recipient.
    Example: Recipient Name

  - `data.toAddress.addressLine1` (string)
    The addressLine1 contains the Flat number, Building or Apartment Name/number (if any) or company name (if not residential) of the Recipient.  `Max length = 35`.
    Example: 350 Fifth Avenue

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

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

  - `data.toAddress.cityTown` (string)
    The name of the city or town the Recipient belongs to.  `Max length = 30`.
    Example: New York

  - `data.toAddress.stateProvince` (string)
    "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: NY

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

  - `data.toAddress.countryCode` (string)
    "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. "
    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.
    Example: 332 555-1212

  - `data.toAddress.email` (string)
    This must be recipient's valid email. Email is required if the customer is using GoFor Carrier.
    Example: recipient@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.toAddress.isPOBox` (boolean)
    Checks if the specified address has the PO Box. In case if Yes, the boolean value will be 'true', else it will take 'false'.
    Example: true

  - `data.parcelTrackingNumber` (string)
    Tracking number assigned to the parcel by the carrier.
    Example: 400000665101

  - `data.service` (string)
    The unique identifier given to the carrier specific service.
    Example: NDA_AM

  - `data.rates` (array)
    Rate details applied to the shipment.

  - `data.rates.baseCharge` (number)
    Base service charge applied by the carrier.
    Example: 113.92

  - `data.rates.carrier` (string)
    Name of the carrier providing the rate.
    Example: Purolator

  - `data.rates.serviceId` (string)
    Identifier of the carrier's service.
    Example: NDA_AM

  - `data.rates.serviceName` (string)
    Full name of the carrier's service.
    Example: Purolator Express® 9AM

  - `data.rates.surcharges` (array)
    List of surcharges applied to the rate.

  - `data.rates.surcharges.fee` (number)
    Amount of the surcharge.
    Example: 28.41

  - `data.rates.surcharges.name` (string)
    Type of surcharge.
    Example: Fuel

  - `data.rates.totalCarrierCharge` (number)
    Total amount payable to the carrier, including surcharges.
    Example: 154.12

  - `data.rates.totalTaxAmount` (number)
    Total tax applied on the charges.
    Example: 7.34

  - `data.rates.isHazmat` (boolean)
    Indicates if the shipment contains hazardous materials.
    Example: false

  - `data.shipmentId` (string)
    Unique identifier of the shipment.

  - `data.shipmentOptions` (object)
    Additional shipment options.

  - `data.status` (string)
    Current status of the shipment.
    Example: Label Printed

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

  - `data.metadata.name` (string)
    Example: costAccountName

  - `data.metadata.value` (string)
    Example: cost account 123

  - `data.parcel` (object)
    Details of the parcel being rated.

  - `data.parcel.length` (number)
    Example: 2

  - `data.parcel.height` (number)
    Example: 1

  - `data.parcel.width` (number)
    Example: 1

  - `data.parcel.dimUnit` (string)
    Example: IN

  - `data.parcel.weightUnit` (string)
    Example: OZ

  - `data.parcel.weight` (number)
    Example: 2

  - `data.parcel.packageValue` (number)
    Example: 2

  - `data.dispenseClient` (string)
    Client/system used to create the shipment.
    Example: api

  - `data.refundStatus` (string)
    Refund status of the shipment.

  - `data.isInternational` (boolean)
    Indicates whether the shipment is international.

  - `data.insured` (boolean)
    Indicates if the shipment is insured.

  - `data.carrierCode` (string)
    Code of the carrier handling the shipment.

  - `data.transactionCreateDate` (string)
    Date and time when the shipment transaction was created.

  - `data.locationId` (string)
    Identifier of the location where the shipment originated.

  - `pageInfo` (object)

  - `pageInfo.total` (integer)
    The total number of records available.
    Example: 1

  - `pageInfo.pages` (integer)
    The total number of pages calculated based on pageSize.
    Example: 2

  - `pageInfo.page` (integer)
    The current page number being returned.
    Example: 1

  - `pageInfo.pageSize` (integer)
    The number of records per page.
    Example: 1

## 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 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: Rategrop cannot created.

  - `additionalCode` (string)
    A unique identifier for the error, for example 01000806.

  - `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 fields (application/json):

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