openapi: 3.0.3
info:
  title: Parcel Perform Analytics Shipments API
  description: 'Parcel Perform aggregates real-time tracking data across hundreds of carriers into one standardized event model, then layers shipment management, returns, outgoing webhooks, and delivery-experience analytics on top. All requests are authenticated with an OAuth2 client-credentials Bearer access token obtained from the auth endpoint below.


    Endpoint groups marked CONFIRMED were verified against Parcel Perform''s public developer portal (developer.parcelperform.com, hosted on Stoplight at developers.parcelperform.com) via documentation page titles and indexed search snippets - the base domain `api.parcelperform.com`, the literal auth path `/auth/oauth/token/`, and the literal shipment-details path fragment `/v5/shipment/details/` were confirmed verbatim. The Stoplight portal renders its reference pages client-side, which blocked programmatic extraction of the remaining literal path strings and full request/response schemas, so most operation paths and all schemas below are MODELED - built from the confirmed operation names/versions (Create/Retrieve/List/Update Shipment, Create Events, Create Return, Outgoing Webhooks v5.0.0/v5.2.0, Response Structure & Errors) and standard Parcel Perform v5 REST conventions. The Couriers and Analytics groups are entirely modeled - Parcel Perform''s public API reference does not document a standalone endpoint set for either, so those paths are illustrative based on the company''s marketing/product pages.'
  version: 5.2.0
  contact:
    name: Parcel Perform
    url: https://www.parcelperform.com
  termsOfService: https://www.parcelperform.com/terms-of-service
servers:
- url: https://api.parcelperform.com/v5
  description: Parcel Perform production API (v5)
security:
- bearerAuth: []
tags:
- name: Shipments
  description: Create, retrieve, list, and update shipments. CONFIRMED operations; MODELED paths/schemas.
paths:
  /shipment:
    post:
      operationId: createShipment
      tags:
      - Shipments
      summary: Create a shipment (MODELED path; operation name CONFIRMED)
      description: Creates a shipment in the Parcel Perform account so it can be tracked across the carrier network. Confirmed via the "Create a Shipment" documentation page title; exact path and payload fields are modeled on Parcel Perform's documented v5 shipment object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentInput'
      responses:
        '201':
          description: The created shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /shipment/list:
    get:
      operationId: listShipments
      tags:
      - Shipments
      summary: List shipments (MODELED path; operation name CONFIRMED)
      description: Retrieves a list of shipments and their key details using search criteria such as tracking number, courier code, or creation date range. Confirmed via the "List Shipments (v5.0)" documentation page title; exact path, query parameters, and pagination are modeled.
      parameters:
      - name: tracking_number
        in: query
        schema:
          type: string
      - name: courier
        in: query
        description: Carrier/courier code.
        schema:
          type: string
      - name: created_from
        in: query
        schema:
          type: string
          format: date-time
      - name: created_to
        in: query
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: A page of shipments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shipment'
                  meta:
                    $ref: '#/components/schemas/PageMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /shipment/details/{tracking_id}:
    parameters:
    - name: tracking_id
      in: path
      required: true
      description: Parcel Perform tracking ID or tracking number for the shipment.
      schema:
        type: string
    get:
      operationId: getShipmentDetails
      tags:
      - Shipments
      summary: Retrieve shipment details (CONFIRMED path fragment)
      description: Retrieves the user-input details plus the normalized tracking events for a single shipment. The `/v5/shipment/details/` path fragment is confirmed verbatim from indexed documentation; the trailing path parameter name is modeled. The v5.2.0 response additionally includes `returns`, `rating`, `line_items`, `collection_point`, and `event.location` objects versus v5.0.0, per the documented version diff.
      responses:
        '200':
          description: The requested shipment, including its tracking events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateShipment
      tags:
      - Shipments
      summary: Update shipment (MODELED path; operation name CONFIRMED)
      description: Updates certain fields, or adds additional elements, for an existing outbound or return shipment. Confirmed via the "Update Shipment (v5.0)" and "Update Details for an Existing Shipment" documentation page titles; exact path/verb and payload are modeled (Parcel Perform's docs list both PUT and POST variants by title, so PUT is used here as the primary verb).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentUpdateInput'
      responses:
        '200':
          description: The updated shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ShipmentInput:
      type: object
      required:
      - tracking_number
      - courier
      properties:
        tracking_number:
          type: string
        courier:
          type: string
          description: Carrier/courier code (e.g. dhl, ups, fedex, ninjavan).
        reference_number:
          type: string
          description: Merchant order/reference number.
        sender:
          $ref: '#/components/schemas/Party'
        recipient:
          $ref: '#/components/schemas/Party'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        collection_point:
          $ref: '#/components/schemas/CollectionPoint'
        metadata:
          type: object
          additionalProperties: true
    ShipmentUpdateInput:
      type: object
      properties:
        reference_number:
          type: string
        recipient:
          $ref: '#/components/schemas/Party'
        metadata:
          type: object
          additionalProperties: true
    LineItem:
      type: object
      properties:
        sku:
          type: string
        name:
          type: string
        quantity:
          type: integer
        weight:
          type: number
    Shipment:
      allOf:
      - $ref: '#/components/schemas/ShipmentInput'
      - type: object
        properties:
          id:
            type: string
          status:
            type: string
            description: Normalized shipment status/milestone.
            enum:
            - info_received
            - in_transit
            - out_for_delivery
            - delivered
            - exception
            - returned
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
    ReturnInput:
      type: object
      required:
      - shipment_tracking_number
      properties:
        shipment_tracking_number:
          type: string
          description: Tracking number of the outbound shipment being returned.
        reason:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
    Error:
      type: object
      properties:
        status:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
    CollectionPoint:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        address:
          type: string
    EventInput:
      type: object
      required:
      - status
      - occurred_at
      properties:
        status:
          type: string
        description:
          type: string
        occurred_at:
          type: string
          format: date-time
        location:
          type: object
          properties:
            city:
              type: string
            state:
              type: string
            country:
              type: string
    ShipmentDetails:
      allOf:
      - $ref: '#/components/schemas/Shipment'
      - type: object
        properties:
          events:
            type: array
            items:
              $ref: '#/components/schemas/Event'
          returns:
            type: array
            description: Present in v5.2.0 responses.
            items:
              $ref: '#/components/schemas/Return'
          rating:
            type: object
            description: Present in v5.2.0 responses.
            additionalProperties: true
    Event:
      allOf:
      - $ref: '#/components/schemas/EventInput'
      - type: object
        properties:
          id:
            type: string
          courier_raw_status:
            type: string
            description: The original, non-normalized status text reported by the carrier.
    Return:
      allOf:
      - $ref: '#/components/schemas/ReturnInput'
      - type: object
        properties:
          id:
            type: string
          status:
            type: string
            enum:
            - requested
            - approved
            - in_transit
            - received
            - refunded
            - rejected
          created_at:
            type: string
            format: date-time
    PageMeta:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    Party:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer access token obtained from POST /auth/oauth/token/, valid for 3600 seconds (60 minutes) per indexed integration guides. Passed as `Authorization: Bearer YOUR_ACCESS_TOKEN`.'