# Get Shipment by Id

The operation retrieves shipment details using shipmentId.

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

## Path parameters:

  - `shipmentId` (string, required)
    The shipmentId, a unique identifier for an individual Shipment.

## 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 isn't required.

## Response 200 fields (application/json):

  - `correlationId` (string)
    Unique identifier assigned by the shipping system to the transaction.
    Example: 49ce304a251447539c84b204d968d7c4

  - `subId` (string)
    Subscription identifier associated with the shipment.
    Example: sac735d

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

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

  - `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

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

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

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

  - `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

  - `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

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

  - `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

  - `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

  - `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

  - `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

  - `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

  - `altReturnAddress` (object)
    Alternate return address for the shipment, if provided.

  - `altReturnAddress.name` (string)
    Example: Paul Wright

  - `altReturnAddress.addressLine1` (string)
    Example: 24182 Kathy Ave

  - `altReturnAddress.cityTown` (string)
    Example: Lake Forest

  - `altReturnAddress.stateProvince` (string)
    Example: CA

  - `altReturnAddress.postalCode` (string)
    Example: 92630-1827

  - `altReturnAddress.countryCode` (string)
    Example: US

  - `altReturnAddress.phone` (string)
    Example: 203-555-1213

  - `altReturnAddress.residential` (boolean)
    Example: false

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

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

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

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

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

  - `rates.currencyCode` (string)
    Currency code for the rate amounts.
    Example: USD

  - `rates.parcelType` (string)
    Parcel/package type.
    Example: PKG

  - `rates.rateTypeId` (string)
    Rate type identifier.
    Example: COMMERCIAL

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

  - `rates.specialServices` (array)
    Special services applied to the shipment.

  - `rates.specialServices.specialServiceId` (string)
    Special service identifier.
    Example: ADULT_SIG

  - `rates.specialServices.fee` (number)
    Fee for the special service.
    Example: 9.35

  - `rates.specialServices.inputParameters` (array)
    Input parameters for the special service (if applicable).

  - `rates.specialServices.inputParameters.name` (string)
    Example: INPUT_VALUE

  - `rates.specialServices.inputParameters.value` (string)
    Example: 200.00

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

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

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

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

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

  - `shipmentId` (string)
    Unique identifier of the shipment.
    Example: UPS2202625646462636

  - `shipmentOptions` (object)
    Additional shipment options.

  - `shipmentOptions.billingWeight` (string)
    Billable weight used for rating.
    Example: 16.00

  - `customs` (object)
    Customs information required for international shipments and optional for domestic shipments.
- Required only for RMG carrier in domestic shipment requests.
- Must include customsItems and customsInfo objects.

  - `customs.customsInfo` (object, required)
    This is additional customs information required along with item details.

  - `customs.customsInfo.reasonForExport` (string, required)
    Reason for exporting the items.
    Enum: "GIFT", "COMMERCIAL_SAMPLE", "MERCHANDISE", "DOCUMENTS", "RETURNED_GOODS", "OTHER"

  - `customs.customsInfo.comments` (string)
    Free-form comments regarding the exported shipment.
    Example: Test comment

  - `customs.customsInfo.invoiceNumber` (string)
    The commercial invoice number assigned by the exporter.
    Example: 001189223

  - `customs.customsInfo.importerCustomsReference` (string)
    A reference number used by the importer, such as a VAT number, PO number, or insured number.
    Example: 987654

  - `customs.customsInfo.sdrValue` (number)
    When an international parcel is insured, the insured value must be expressed in Special Drawing Rights values.
    Example: 23.32

  - `customs.customsInfo.EELPFC` (string)
    A number provided by the Automated Export System (AES).  Required if the item is more than $2,500 USD, per Schedule B export codes.  Required if EELPFC  is AES ITN.
- AES ITN is a unique transaction number generated by the Automated Export System (AES) when export data is filed for international shipments from the U.S.
- The ITN format is AES XYYYYMMDDNNNNNN, where X indicates the type, YYYYMMDD is the filing date, and NNNNNN is a 6-digit number. Example: `AES X20250327123456`
- If the ITN is not available, an exemption format may be used: AESDOWN [Filer ID] [mm/dd/yyyy]. Example: `AESDOWN 12345678912 03/27/2025`
    Example: NOEEI 30.2D2

  - `customs.customsInfo.currencyCode` (string, required)
    The currency used for declared value. Use three uppercase letters, per ISO 4217.
    Example: USD

  - `customs.customsInfo.fromCustomsReference` (string)
    Free-form reference information provided by the requestor of the shipment. Depending on the carrier this information may or may not be rendered on the customs documents.
    Example: EFEFE4554545

  - `customs.customsInfo.licenseNumber` (string)
    The export license number associated with the commodity.
    Example: 456ABC123

  - `customs.customsInfo.certificateNumber` (string)
    The certificate number associated with the commodity.
    Example: 987

  - `customs.customsInfo.customsDeclaredValue` (number, required)
    Item value in mentioned currencyCode.
    Example: 6000

  - `customs.customsInfo.termsOfSale` (string)
    Defines the delivery and payment terms between the shipper and recipient. Currenty supported by carriers - UPS, FedEx and DHL. - Common values include:
- CIP: Carriage and Insurance Paid to
- CPT: Carriage Paid To
- DAP: Delivered at Place
- DAT: Delivered at Terminal
- DDP: Delivered Duty Paid
- EXW: Ex Works
- FCA: Free Carrier
    Enum: "CIP", "CPT", "DAP", "DAT", "DDP", "EXW", "FCA"

  - `customs.customsItems` (array, required)
    Items included in the customs declaration.

  - `customs.customsItems.description` (string)
    A detailed description of the commodity, up to 255 characters. The description will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each. Each description will appear on the form.
    Example: Books

  - `customs.customsItems.itemId` (string)
    Unique identifier for the commodity.
    Example: item1

  - `customs.customsItems.orderNumber` (string)
    The unique identifier for the order.
    Example: ORD1

  - `customs.customsItems.quantity` (number)
    Enter the total number of items of this type of commodity.
    Example: 1

  - `customs.customsItems.unitPrice` (number)
    The price of one item of this type of commodity.
    Example: 3000

  - `customs.customsItems.weightUnit` (string)
    The unit of measurement. This field is required by the unitWeight object.
    Example: OZ

  - `customs.customsItems.weight` (number)
    Weight of the item.
    Example: 0.1

  - `customs.customsItems.hSTariffCode` (string)
    The destination country's tariff-classification number (HS code) for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and then add digits for more detail. The maximum length for an HS code is 14 characters. The HS code will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each. HS Code is required for RMG b2b shipment.
    Example: AST559

  - `customs.customsItems.originCountryCode` (string)
    The two-character ISO country code of the shipment's origin country. Use ISO 3166-1 Alpha-2 standard values.
    Example: US

  - `customs.customsDocuments` (array)
    Use this field to attach Electronic Trade Documents (ETDs) to your DHL international shipment.
Each item should represent a document uploaded previously using the [Upload ETD API](/openapi/shipping/electronic-trade-document/uploadetd).
- For DHL, if you pass this field, ensure the selected service type is PAPERLESS.
- The `s3FileId` value must be taken from the [Upload ETD API response](/openapi/shipping/electronic-trade-document/uploadetd).

> Electronic trade document must upload before shipment label creation.

  - `customs.customsDocuments.fileName` (string, required)
    The name of the uploaded trade document file.
    Example: invoice.pdf

  - `customs.customsDocuments.s3FileId` (string, required)
    The relative file path where the document is stored in the S3 bucket.
    Example: uploads/shipping/intl_docs/sa58a03/0oa2bxnhu03i48mh50h8/NJ3ww7gv73kwDJK/DRNgGjEraOvV8ZB_invoice.pdf

  - `customs.customsDocuments.documentType` (string, required)
    Type of the uploaded document. This value is referenced when generating customs declarations.
Must match the type used during document upload.
    Enum: "INVOICE", "COMMERCIAL_INVOICE", "PROFORMA_INVOICE", "CERTIFICATE_OF_ORIGIN", "NAFTA_CERTIFICATE_OF_ORIGIN", "CUSTOMS_DECLARATION_FORM", "AIR_WAYBILL_AND_WAYBILL"

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

  - `carrier` (string)
    Carrier code/name used for the shipment.
    Example: ups

  - `carrierAccountId` (string)
    Carrier account Id used for the shipment.
    Example: EQ7Ar2dmXXX

  - `metadata` (array)
    Additional metadata that needs to be stored for this shipment can be added here. Supported values are [Cost Account Name, Cost Account Id, Cost Account Code](/openapi/costaccount/cost-account-management/addcostaccount), [Account Code](/openapi/billingcodes/account-code/createaccountcode) and [Company Code](/openapi/billingcodes/company-code/createcompanycode).If Cost Account metadata is provided, all three Cost Account fields are required.

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

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

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

  - `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

  - `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

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

  - `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"

  - `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"

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

  - `parcel.packageValue` (number)
    Indicates value of the package.
    Example: 2

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

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

  - `isInternational` (boolean)
    Indicates whether the shipment is international.
    Example: true

  - `isReturnLblRequested` (boolean)
    Indicates whether a return label was requested.
    Example: false

  - `insured` (boolean)
    Indicates if the shipment is insured.
    Example: true

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

  - `transactionCreateDate` (string)
    Date and time when the shipment transaction was created.
    Example: 2026-02-09T07:22:05.457Z

  - `locationId` (string)
    Identifier of the location where the shipment originated.
    Example: zLwdWnZ7LyVWknO

  - `references` (object)
    References are tags or information that is printed on Shipping Label based on the customer's requirement.  Reference Fields can have values/indication like department name, invoice no., package description, purchase order no., carrier note, cost account no., transportation no., or PO no., print custom message etc. Each of the reference field can have only one indication/value.

  - `references.reference1` (string)
    Reference 1 can have one of the above-indicated values/information, which is printed on Label. For FedEx, it is a Reference number in the invoice. For USPS, it is a print custom message that will be printed vertically at the top of the label.  `Max length = 30`.
    Example: custome message

  - `references.reference2` (string)
    Reference 2 can have other details as indicated in the example values above. This is also printed on Label. For FedEx, this is the department. For USPS, it is a print custom message that will be printed horizontally at the bottom of the label.  `Max length = 30`.
    Example: SendTech

  - `references.reference3` (string)
    Reference 3 can have the information which were not fulfilled in Ref1 and Ref2. For FedEx, this is the invoice number.  `Max length = 30`.
    Example: 98437

  - `references.reference4` (string)
    Reference 4 can have more information which were not provided in Ref1, Ref2, or Ref3. For FedEx, this is the PO number.  `Max length = 30`.
    Example: Overnight Shipping

  - `references.poNumber` (string)
    The Purchase Order Number. For FedEx, the PO number is passed in the `reference4` field.  `Max length = 30`.
    Example: R2W 2H2

  - `references.department` (string)
    The department of the Recipient.For FedEx, the Department is passed in `reference2` field.  `Max length = 30`.
    Example: Name department

  - `references.additionalReference1` (string)
    Additional Reference is hardly used, but sender can mention anything as per requirement, just for Recipient's information.  `Max length = 30`.
    Example: 612987641

  - `references.additionalReference2` (string)
    Any tags or information that to be shown to Recipient, can be mentioned by Sender, which is not indicated on AdditionalReference1 field, e.g., PO No, Order No. etc. `Max length = 30`.
    Example: 989

  - `references.shippingNotes` (string)
    Shipping notes are the instructions or messages that the sender wants to communicate to the carrier or the recipient regarding the handling, delivery, or any special requirements for the shipment. These notes can include specific delivery instructions, handling precautions, or any other relevant information that can assist in ensuring the safe and accurate delivery of the package.  `Max length = 30`.
    Example: Handle with care.

  - `references.ShipperReference` (string)
    Shipper Reference is a unique identifier or code assigned by the shipper to a specific shipment or package.  `Max length = 30`.
    Example: REF123456789

  - `references.transportationReference` (string)
    Transportation Reference is a unique identifier or code used to track and manage the transportation of a shipment or package throughout the shipping process.  `Max length = 30`.
    Example: TRANSREF987654321

  - `ecommerceProvider` (object)
    E-commerce platform details associated with the shipment. This object will only be return in case of using Order Management APIs.

  - `ecommerceProvider.customer` (object)
    Customer details received from the e-commerce system.

  - `ecommerceProvider.customer.id` (string)
    Unique identifier of the customer.
    Example: CUST12345

  - `ecommerceProvider.customer.email` (string)
    Customer email address.
    Example: john.doe@example.com

  - `ecommerceProvider.customer.first_name` (string)
    Customer first name.
    Example: John

  - `ecommerceProvider.customer.last_name` (string)
    Customer last name.
    Example: Doe

  - `ecommerceProvider.orderNumber` (string)
    Order number from the e-commerce system.
    Example: 3865

  - `customerLocationId` (string)
    This is a customer-defined location identifier in addition to the system-generated LocationId created during developer onboarding. If a `customerLocationId` is not defined, the system assigns a default `locationID`. In responses, both identifiers are returned, if a customer-defined value is not set, both fields return the same system-generated LocationID
    Example: loc_auto_sa5501a

  - `dateOfShipment` (string)
    The actual date the freight shipment is scheduled to be shipped (YYYY-MM-DD).
    Example: 2026-07-15

  - `ltlRates` (array)
    LTL freight rate details, including per-handling-unit parcel information such as freight class, sequence, and billable weight.

  - `ltlRates.carrier` (string)
    LTL carrier providing the rate.
    Example: XG38WGBJLOL4

  - `ltlRates.serviceId` (string)
    Identifier of the carrier's service.
    Example: SVC_xDzkRdJL24KG

  - `ltlRates.serviceName` (string)
    Human-readable name of the carrier's service.
    Example: GRD

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

  - `ltlRates.parcels` (array)
    Details of each handling unit (e.g., pallet) included in the LTL shipment.

  - `ltlRates.parcels.parcelType` (string)
    Type of handling unit used for the freight shipment (e.g., `PALLET`).
    Example: PKG_xO6M1DKBaaXM

  - `ltlRates.parcels.parcel` (object)
    Physical dimensions and weight of the handling unit.

  - `ltlRates.parcels.parcel.length` (number)
    Example: 11

  - `ltlRates.parcels.parcel.height` (number)
    Example: 11

  - `ltlRates.parcels.parcel.width` (number)
    Example: 11

  - `ltlRates.parcels.parcel.dimUnit` (string)
    Example: IN

  - `ltlRates.parcels.parcel.weightUnit` (string)
    Example: OZ

  - `ltlRates.parcels.parcel.weight` (number)
    Example: 1500

  - `ltlRates.parcels.sequenceNumber` (string)
    Sequence number of this handling unit within the LTL shipment.
    Example: 1

  - `ltlRates.parcels.pieceCount` (string)
    Number of pieces contained within this handling unit.
    Example: 1

  - `ltlRates.parcels.parcelBrandedName` (string)
    Branded/display name of the handling unit type.
    Example: Pallet

  - `ltlRates.parcels.freightClass` (string)
    NMFC freight class assigned to the handling unit (e.g., `CLASS200`).
    Example: CLASS200

  - `ltlRates.parcels.billableWeight` (object)
    Billable weight of the handling unit used for rating.

  - `ltlRates.parcels.billableWeight.weightUnit` (string)
    Example: OZ

  - `ltlRates.parcels.billableWeight.weight` (number)
    Example: 1500

  - `ltlRates.handlingUnitCount` (integer)
    Total number of handling units included in the LTL shipment.
    Example: 0

  - `ltlRates.carrierBrandedName` (string)
    Branded/display name of the LTL carrier.
    Example: customLTL1

## 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: string

  - `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 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 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 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.