openapi: 3.0.3
info:
  title: Parcel Perform Analytics Tracking Events 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: Tracking Events
  description: Normalized carrier tracking event timeline. CONFIRMED operations; MODELED paths/schemas.
paths:
  /shipment/{tracking_id}/event:
    parameters:
    - name: tracking_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: createShipmentEvents
      tags:
      - Tracking Events
      summary: Create events for an existing shipment (MODELED path; operation name CONFIRMED)
      description: Manually creates one or more tracking events on an existing outbound or return shipment, for cases such as in-house last-mile legs not covered by a carrier feed. Confirmed via the "Create Events for an Existing Shipment" and "Create Events (v5.0)" documentation page titles; exact path and payload are modeled on the documented event object (status, location, timestamp).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/EventInput'
      responses:
        '201':
          description: The created events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    Error:
      type: object
      properties:
        status:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                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
    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.
  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`.'