> ## 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 (v5.2) > Returns everything [Retrieve Shipment Details](#tag/Shipments) v5.0 returns, **plus**: `shipment_type` (`"return"` or `null`), a `returns` object for Return Shipments, `line_items`, `collection_point`, `rating`, `parcel_recipient_information`, and `pod_url` (carrier proof of delivery; the URL expires after 7 days and is regenerated per response). Each event's `location` is enriched from a single `place` string to a full address object with coordinates and timezone. ## OpenAPI ````yaml /specs/public-api-v5.yaml get /v5-2-0/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-2-0/shipment/details/: get: tags: - Shipments summary: Retrieve Shipment Details (v5.2) description: |- Returns everything [Retrieve Shipment Details](#tag/Shipments) v5.0 returns, **plus**: `shipment_type` (`"return"` or `null`), a `returns` object for Return Shipments, `line_items`, `collection_point`, `rating`, `parcel_recipient_information`, and `pod_url` (carrier proof of delivery; the URL expires after 7 days and is regenerated per response). Each event's `location` is enriched from a single `place` string to a full address object with coordinates and timezone. operationId: get-v5-2-0-shipment-details parameters: - $ref: '#/components/parameters/ShipmentUuidQuery' - $ref: '#/components/parameters/ShipmentIdQuery' responses: '200': description: The Shipment's full details (v5.2 shape). content: application/json: schema: type: object properties: api_response: type: string data: $ref: '#/components/schemas/ShipmentDetailV52' '400': description: Identifier missing or invalid. content: application/json: schema: $ref: '#/components/schemas/FieldValidationError' '403': $ref: '#/components/responses/Unauthorized' '404': description: No Shipment matched the provided identifier. content: application/json: schema: $ref: '#/components/schemas/RequestError' '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: ShipmentDetailV52: allOf: - $ref: '#/components/schemas/ShipmentDetailV5' - type: object properties: shipment_type: type: - string - 'null' description: '`return` for Return Shipments, otherwise `null`.' returns: anyOf: - $ref: '#/components/schemas/ReturnsInfo' - type: 'null' line_items: type: array items: $ref: '#/components/schemas/LineItemOutput' collection_point: anyOf: - $ref: '#/components/schemas/CollectionPoint' - type: 'null' rating: anyOf: - $ref: '#/components/schemas/RatingInfo' - type: 'null' parcel_recipient_information: type: - string - 'null' pod_url: type: - string - 'null' description: >- Carrier proof of delivery. Expires after 7 days; regenerated per response. all_events: type: array items: allOf: - $ref: '#/components/schemas/EventOutput' - type: object properties: location: anyOf: - $ref: '#/components/schemas/EventLocationV52' - type: 'null' 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 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 ReturnsInfo: type: object description: Present only when `shipment_type` is `return`; otherwise `null`. properties: order_id: type: - string - 'null' id: type: string description: Perform.AI-generated return ID. return_id: type: - string - 'null' description: Merchant-created return ID (usable for RMA). return_status: type: string enum: - pending approval - rejected - approved - carrier booking pending - shipping - completed - cancelled - inactive - archived total_refund_amount: type: - string - 'null' refund_is_calculated: type: boolean description: '`false` if the merchant provided the amount.' comment: type: - string - 'null' return_proofs: type: array items: $ref: '#/components/schemas/ReturnProof' requested_date: type: string updated_at: type: string reject_reason: type: - string - 'null' refund_method: type: - string - 'null' description: original payment, store credit, or exchange. return_method: type: - string - 'null' description: drop off, pick-up, send by consumer, or return to store. cost_of_return: type: - string - 'null' cost_is_calculated: type: boolean additional_cost: type: - string - 'null' internal_notes: type: - string - 'null' approver_email: type: - string - 'null' booking_id: type: - string - 'null' description: Carrier booking service ID for return labels or QR codes. shipment_pk: type: - integer - 'null' description: >- Internal identifier of the Return Shipment. Do not build on it — use `shipment_uuid` to reference the Shipment. LineItemOutput: allOf: - $ref: '#/components/schemas/LineItemInput' description: >- Line item as returned in Shipment details; `return_reason` is `null` when the line item is not being returned. CollectionPoint: type: object description: The latest available collection point for the Shipment. properties: uuid: type: string collection_point_identifier: type: string address: type: object description: >- Like the address object, without company, tax_id, first_name, last_name, salutation, or email. status: type: string description: '`active` or `expired`.' lat: type: number lng: type: number operating_hours_calc: type: array items: type: object properties: service_name: type: string operating_day: type: string time_zone: type: string first_open_hours: type: - string - 'null' second_open_hours: type: - string - 'null' first_cutoff: type: - string - 'null' second_cutoff: type: - string - 'null' additional_info: type: object updated_date: type: string RatingInfo: type: object properties: id: type: string value: type: - number - 'null' description: Latest star rating submitted by the consumer. categories: type: array items: type: string comment: type: - string - 'null' 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 EventLocationV52: type: object description: Enriched event location (v5.2 and later). properties: place: type: string full: type: - string - 'null' formatted_address: type: - string - 'null' location_type: type: - string - 'null' line1: type: - string - 'null' line2: type: - string - 'null' line3: type: - string - 'null' postal_code: type: - string - 'null' city: type: - string - 'null' state_or_province: type: - string - 'null' region: type: - string - 'null' country: type: - string - 'null' country_code: type: - string - 'null' longitude: type: - string - 'null' latitude: type: - string - 'null' timezone: type: - string - 'null' 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`. 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 ReturnProof: type: object properties: url: type: string format: uri description: Public URL of the consumer-uploaded proof image. file_name: type: string LineItemInput: type: object description: One product line in the Shipment. properties: product_name: type: string maxLength: 500 product_id: type: string maxLength: 50 product_reference: type: string maxLength: 50 description: Another reference for the line item, e.g. an SKU. product_category: type: string maxLength: 500 product_description: type: string maxLength: 500 product_origin_country_code: type: string minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country of origin. hs_code: type: string maxLength: 20 description: Harmonized System code, mainly for customs. customs_description: type: string maxLength: 500 quantity: type: integer minimum: 1 maximum: 1000000 default: 1 product_image_url: type: string format: uri maxLength: 1024 description: JPG/PNG/GIF up to 5 MB; stored at up to 1 MB and 1024×1024. product_url: type: string format: uri maxLength: 1024 product_weight: type: number minimum: 0 description: Weight of a single unit. product_weight_unit: type: string maxLength: 5 line_item_weight: type: number minimum: 0 line_item_weight_unit: type: string maxLength: 5 currency_code: type: string description: >- ISO 4217 currency for the cost fields. Must match across all line items in a Shipment. product_cost: type: number minimum: 0 subtotal_cost: type: number minimum: 0 description: Before discount and tax. discount_amount: type: number minimum: 0 tax_amount: type: number minimum: 0 misc_cost: type: number minimum: 0 total_price: type: number minimum: 0 description: After discount and tax. return_id: type: string maxLength: 50 description: Return this line item belongs to, if any. return_reason: type: string maxLength: 512 additional_info: type: object description: Custom fields. Keys max 50 chars, values max 150. 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}`. ````