Parcel Perform Shipments API

openapi: 3.2.0
info:
  title: Parcel Perform 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.
  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:
    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.
    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
    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
    CollectionPoint:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        address:
          type: string
    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
    LineItem:
      type: object
      properties:
        sku:
          type: string
        name:
          type: string
        quantity:
          type: integer
        weight:
          type: number
    ShipmentUpdateInput:
      type: object
      properties:
        reference_number:
          type: string
        recipient:
          $ref: '#/components/schemas/Party'
        metadata:
          type: object
          additionalProperties: true
    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'
    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
    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
    Error:
      type: object
      properties:
        status:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
  responses:
    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'
    ValidationError:
      description: The request payload failed validation.
      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`.'