> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Shipment Details > Returns the full record of one Shipment — identifiers, carrier, status and phase, all address objects, costs, dimensions, linked Shipments, documents, and the complete event history in `all_events`. Identify the Shipment with **either** `shipment_uuid` **or** `shipment_id` as a query parameter. ## OpenAPI ````yaml /specs/public-api-v5.yaml get /v5/shipment/details/ openapi: 3.1.0 info: title: Perform.AI Public API (v5) version: 5.0.0 description: |- The Perform.AI Public API lets you create and manage shipments, returns, bookings, tracking events, and documents, and retrieve reference data such as PUDO locations and carrier configurations. All endpoints accept HTTPS connections only and are secured with OAuth 2.0. Generate a Bearer access token with your API credentials (Client ID and Client Secret, from **Integrations > API** in your account), then send it in the `Authorization` header of every request. This specification covers the following endpoints: - `POST /auth/oauth/token/` - `POST /v5/shipment/` - `POST /v5/shipment/update/` - `POST /v5-2-0/shipment/update/` - `GET /v5/shipment/list/` - `GET /v5/shipment/details/` - `GET /v5-2-0/shipment/details/` - `POST /v5/events/create/` - `POST /v5/return/` - `POST /v5/return/update/` - `GET /v5/shipments/documents/` - `GET /v5/shipments/documents/{document_uuid}/` - `GET /v5/shipments/documents/labels/` - `POST /v5/booking/` - `GET /v5/pudo-locations/` - `GET /v5/carrier-configs/` servers: - url: https://api.perform.ai security: - BearerAuth: [] tags: - name: Authentication description: Generate the Bearer access token used by every other endpoint. - name: Shipments description: Create, update, search, and retrieve Shipments. - name: Events description: Add manual tracking events to Shipments. - name: Returns description: Create and update Returns and their Return Shipments. - name: Documents description: Retrieve documents attached to Shipments. - name: Booking description: Book Open Shipments with carriers and provision shipping labels. - name: PUDO locations description: Search pick-up/drop-off locations across your configured carriers. - name: Carrier configurations description: Discover the carriers configured in your account. - name: Webhooks description: Shipment update payloads Perform.AI pushes to your endpoint. paths: /v5/shipment/details/: get: tags: - Shipments summary: Retrieve Shipment Details description: |- Returns the full record of one Shipment — identifiers, carrier, status and phase, all address objects, costs, dimensions, linked Shipments, documents, and the complete event history in `all_events`. Identify the Shipment with **either** `shipment_uuid` **or** `shipment_id` as a query parameter. operationId: get-v5-shipment-details parameters: - $ref: '#/components/parameters/ShipmentUuidQuery' - $ref: '#/components/parameters/ShipmentIdQuery' responses: '200': description: The Shipment's full details. content: application/json: schema: type: object properties: api_response: type: string data: $ref: '#/components/schemas/ShipmentDetailV5' '400': description: >- Neither `shipment_uuid` nor `shipment_id` was provided, or the value is in an invalid format. content: application/json: schema: $ref: '#/components/schemas/FieldValidationError' example: api_response: '4030' message: validation_error errors: shipment_uuid: - Either shipment_uuid or shipment_id is required. '403': $ref: '#/components/responses/Unauthorized' '404': description: No Shipment matched the provided identifier. content: application/json: schema: $ref: '#/components/schemas/RequestError' example: api_response: '4041' message: No results found with the provided search parameters '429': $ref: '#/components/responses/Throttled' '500': $ref: '#/components/responses/SystemError' components: parameters: ShipmentUuidQuery: name: shipment_uuid in: query schema: type: string format: uuid description: >- Perform.AI identifier of the Shipment. Provide either `shipment_uuid` or `shipment_id`. ShipmentIdQuery: name: shipment_id in: query schema: type: string maxLength: 50 description: >- Your identifier of the Shipment. Provide either `shipment_uuid` or `shipment_id`. schemas: ShipmentDetailV5: type: object description: The `data` object of Retrieve Shipment Details v5.0. properties: shipment_uuid: type: string format: uuid shipment_id: type: - string - 'null' shipment_reference: type: - string - 'null' additional_reference: type: - string - 'null' tracking_number: type: - string - 'null' carrier_reference: type: - string - 'null' carrier: anyOf: - $ref: '#/components/schemas/CarrierInfo' - type: 'null' created_date: type: string updated_date: type: string source: type: string description: Input source of the Shipment, e.g. api, File Upload, SFTP. status: type: string description: pending, expired, active, inactive, delivered, or return. current_phase: $ref: '#/components/schemas/PhaseInfo' tags: type: array items: type: string notification_email: type: array items: type: string notification_phone: type: array items: type: string tracking_page_reference: type: - string - 'null' order: anyOf: - $ref: '#/components/schemas/OrderInfo' - type: 'null' recipient_address: anyOf: - $ref: '#/components/schemas/AddressOutput' - type: 'null' sender_address: anyOf: - $ref: '#/components/schemas/AddressOutput' - type: 'null' to_address: anyOf: - $ref: '#/components/schemas/AddressOutput' - type: 'null' from_address: anyOf: - $ref: '#/components/schemas/AddressOutput' - type: 'null' return_address: anyOf: - $ref: '#/components/schemas/AddressOutput' - type: 'null' shipment_value: $ref: '#/components/schemas/MoneyOutput' total_shipping_cost: $ref: '#/components/schemas/MoneyOutput' shipping_costs: type: array items: $ref: '#/components/schemas/ShippingCostOutput' cod_value: $ref: '#/components/schemas/MoneyOutput' dimensions: $ref: '#/components/schemas/DimensionsOutput' weight: $ref: '#/components/schemas/WeightOutput' linked_shipments: type: array items: $ref: '#/components/schemas/LinkedShipmentOutput' expected_delivery: $ref: '#/components/schemas/ExpectedDelivery' payment_type: type: - string - 'null' item_count: type: - integer - 'null' packaging_type: type: - string - 'null' note: type: - string - 'null' shipping_service: type: - string - 'null' description_of_goods: type: - string - 'null' handling_instructions: type: - string - 'null' sales_channel: type: - string - 'null' documents: type: array items: $ref: '#/components/schemas/DocumentOutput' all_events: type: array items: $ref: '#/components/schemas/EventOutput' description: The Shipment's complete event history, newest first. additional_info: type: object FieldValidationError: type: object description: >- HTTP 400 — one or more fields failed validation; nothing was persisted. For fields inside arrays, errors are keyed by the item's position as a string ("0", "1", …), then the field name. required: - api_response - message - errors properties: api_response: type: string description: Always `"4030"`. message: type: string description: Always `validation_error`. errors: type: object description: >- Affected field → array of error messages (or a nested object for array items). RequestError: type: object description: >- A request-level error such as `4000` (invalid request format), `4041` (no results found), or a `5XX` system error. required: - api_response - message properties: api_response: type: string description: Error code as a string, e.g. `"4000"`, `"4041"`, `"500"`. message: type: string CarrierInfo: type: object properties: id: type: string description: Perform.AI's 6-character carrier identifier. name: type: string country_iso: type: array items: type: string description: Operating countries, ISO 3166-1 alpha-2. language: type: - array - 'null' items: type: string supported_languages: type: array items: type: string contact: type: - string - 'null' site_link: type: - string - 'null' PhaseInfo: type: object properties: name: type: - string - 'null' description: Name of the delivery phase. key: type: - string - 'null' description: Standard phase key. OrderInfo: type: object properties: order_uuid: type: - string - 'null' order_id: type: - string - 'null' order_reference: type: - string - 'null' source_type: type: - string - 'null' source_name: type: - string - 'null' created_date: type: string updated_date: type: string AddressOutput: allOf: - $ref: '#/components/schemas/AddressInput' - type: object properties: full: type: string description: All address fields combined into a single string. MoneyOutput: type: object description: A monetary value in responses. properties: amount: type: number currency: type: string description: ISO 4217. ShippingCostOutput: type: object properties: name: type: string reference: type: string unit_quantity: type: - number - 'null' unit_cost: $ref: '#/components/schemas/MoneyOutput' total_cost: $ref: '#/components/schemas/MoneyOutput' DimensionsOutput: type: object properties: length: type: number width: type: number height: type: number unit: type: string description: Always centimeters (`cm`). WeightOutput: type: object properties: amount: type: number unit: type: string description: Always grams (`g`). LinkedShipmentOutput: type: object properties: tracking_number: type: string carrier_reference: type: string carrier: $ref: '#/components/schemas/CarrierInfo' ExpectedDelivery: type: object properties: from: type: string description: >- Start of the expected delivery window. Format varies with known precision — see the timestamps guide. to: type: string description: End of the expected delivery window. DocumentOutput: type: object description: A document reference within Shipment details. properties: document_uuid: type: string format: uuid document_id: type: string name: type: string type: type: string file_format: type: string created_date: type: string additional_info: type: object EventOutput: type: object description: One entry of `all_events`. properties: event: type: string description: >- Standard English description or the original carrier description, depending on how the event was processed. event_key: type: string description: Standard event key, when the event is mapped. phase: type: string phase_key: type: string time: type: string description: Format varies with known precision — see the timestamps guide. timezone: type: - string - 'null' description: IANA timezone of the event, when known. carrier_name: type: string location: type: - object - 'null' properties: place: type: string additional_info: type: object GatewayError: type: object description: >- An error generated at the API gateway — authorization (`403`) or throttling (`429`). Note `api_response` is a number here, unlike application-level responses where it is a string. required: - api_response - message properties: api_response: type: integer description: '`403` or `429`.' message: type: string description: E.g. `Key not authorized`, `Quota exceeded`, `Throttled`. AddressInput: type: object description: >- One of the Shipment's five address roles (recipient, sender, to, from, return). Provide either `country` or `country_code`. The `email` and `phone` here are contact data — they are never subscribed to tracking notifications. properties: address_name: type: string maxLength: 50 description: Name or description of the address. location_type: type: string maxLength: 50 entity_reference: type: string maxLength: 50 description: Reference for the entity behind the address. salutation: type: string maxLength: 50 first_name: type: string maxLength: 150 description: First or full name. last_name: type: string maxLength: 150 line1: type: string maxLength: 150 line2: type: string maxLength: 150 line3: type: string maxLength: 150 street_name: type: string maxLength: 500 description: Street name, when kept separate from the address lines. house_number: type: string maxLength: 50 city: type: string maxLength: 75 postal_code: type: string maxLength: 25 state_or_province: type: string maxLength: 75 region: type: string maxLength: 75 country: type: string maxLength: 75 description: >- Country name; resolved through a country identifier and stored as the identified name. Provide this or `country_code`. country_code: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2. Provide this or `country`. email: type: string format: email maxLength: 100 description: Contact email. Not subscribed to notifications. phone: type: string maxLength: 30 description: >- Contact phone, `+` then country calling code and number. Not subscribed to notifications. fax: type: string maxLength: 16 description: '`+` followed by up to 15 digits.' company: type: string maxLength: 150 tax_id: type: string maxLength: 100 responses: Unauthorized: description: >- The Bearer token is expired, invalid, or missing — or the account lacks access. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 403 message: Key not authorized Throttled: description: Rate limit exceeded (40 requests per second per account). content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: api_response: 429 message: Throttled SystemError: description: Internal system error. content: application/json: schema: $ref: '#/components/schemas/RequestError' example: api_response: '500' message: System error securitySchemes: BearerAuth: type: http scheme: bearer description: >- Used by every functional endpoint. Generate the token with `POST /auth/oauth/token/` and send it as `Authorization: Bearer {token}`. ````