openapi: 3.0.3
info:
  title: Parcel Perform 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: Authentication
    description: OAuth2 client-credentials token issuance. CONFIRMED path.
  - name: Shipments
    description: Create, retrieve, list, and update shipments. CONFIRMED operations; MODELED paths/schemas.
  - name: Tracking Events
    description: Normalized carrier tracking event timeline. CONFIRMED operations; MODELED paths/schemas.
  - name: Returns
    description: Create returns and return shipments. CONFIRMED operations; MODELED paths/schemas.
  - name: Webhooks
    description: Outgoing webhook subscriptions for tracking updates. CONFIRMED operations; MODELED paths/schemas.
  - name: Couriers
    description: Carrier/courier reference data. Entirely MODELED - no public reference page found.
  - name: Analytics
    description: Delivery-experience performance metrics behind the Analyze product. Entirely MODELED - no public reference page found.
paths:
  /auth/oauth/token/:
    post:
      operationId: createAccessToken
      tags:
        - Authentication
      summary: Generate a Bearer access token (CONFIRMED path)
      description: >-
        Exchanges API credentials for a short-lived OAuth2 Bearer access
        token using the client-credentials grant. Send `Authorization: Basic
        base64(client_id:client_secret)` and `grant_type=client_credentials`
        in a form-encoded body. Confirmed via Parcel Perform's public
        "Generate Bearer Access Token" documentation page and indexed
        third-party integration guides; the returned token is reported valid
        for 3600 seconds (60 minutes).
      security: []
      parameters:
        - name: Authorization
          in: header
          required: true
          description: 'Basic base64(client_id:client_secret).'
          schema:
            type: string
            example: Basic base64Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials]
      responses:
        '200':
          description: Bearer token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /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'
  /return:
    post:
      operationId: createReturn
      tags:
        - Returns
      summary: Create a return (MODELED path; operation name CONFIRMED)
      description: >-
        Creates a return in the Parcel Perform account against an existing
        outbound shipment. Only one return may be created per request.
        Confirmed via the "Create a Return" / "Create Return" documentation
        page titles; exact path and payload are modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnInput'
      responses:
        '201':
          description: The created return.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /return/shipment:
    post:
      operationId: createReturnWithShipment
      tags:
        - Returns
      summary: Create a return with its return shipment (MODELED path; operation name CONFIRMED)
      description: >-
        Creates a Return and its associated Return Shipment together in a
        single request. Confirmed via the "Create a Return" documentation
        page title (which pairs Create Return with Create Shipment); exact
        path and payload are modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ReturnInput'
                - type: object
                  properties:
                    shipment:
                      $ref: '#/components/schemas/ShipmentInput'
      responses:
        '201':
          description: The created return and return shipment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  return:
                    $ref: '#/components/schemas/Return'
                  shipment:
                    $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /webhook:
    get:
      operationId: listWebhookSubscriptions
      tags:
        - Webhooks
      summary: List outgoing webhook subscriptions (MODELED)
      description: >-
        Lists the callback URLs registered to receive outgoing Shipment
        Tracking Update webhooks. The existence of outgoing webhooks in
        v5.0.0 and v5.2.0 payload formats is confirmed via documentation page
        titles; a management endpoint for subscriptions is modeled, since
        webhook target URLs are commonly configured in the Parcel Perform
        console rather than (or in addition to) via API.
      responses:
        '200':
          description: Registered webhook subscriptions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhookSubscription
      tags:
        - Webhooks
      summary: Create an outgoing webhook subscription (MODELED)
      description: >-
        Registers a callback URL and payload format version
        (`5.0.0` or `5.2.0`) to receive outgoing Shipment Tracking Update
        events. Modeled endpoint - see summary on the GET operation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '201':
          description: The created webhook subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /courier:
    get:
      operationId: listCouriers
      tags:
        - Couriers
      summary: List supported couriers/carriers (MODELED - not found in public reference)
      description: >-
        Illustrative list of the courier/carrier network Parcel Perform
        tracks against (reported between roughly 900 and 1,000+ carriers
        worldwide per Parcel Perform's marketing pages). No standalone
        `/courier` endpoint is documented in the public API Guides &
        Reference as of this review; carrier codes otherwise only appear as
        a field on Shipment resources. Entirely modeled.
      responses:
        '200':
          description: Supported couriers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Courier'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /courier/{courier_code}:
    parameters:
      - name: courier_code
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getCourier
      tags:
        - Couriers
      summary: Retrieve a courier/carrier (MODELED - not found in public reference)
      description: Entirely modeled - see summary on the list operation.
      responses:
        '200':
          description: The requested courier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Courier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /analytics/performance:
    get:
      operationId: getPerformanceAnalytics
      tags:
        - Analytics
      summary: Retrieve delivery-experience performance metrics (MODELED - not found in public reference)
      description: >-
        Illustrative reporting endpoint modeled on the metrics described for
        Parcel Perform's "Analyze" product - carrier on-time/SLA performance,
        exception rates, and estimated-delivery-date accuracy aggregated over
        a date range. No standalone analytics endpoint is documented in the
        public API Guides & Reference as of this review; Analyze is presented
        as an in-app dashboard/AI-insights product. Entirely modeled.
      parameters:
        - name: date_from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: courier
          in: query
          schema:
            type: string
        - name: group_by
          in: query
          schema:
            type: string
            enum: [courier, country, service_level]
      responses:
        '200':
          description: Aggregated performance metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PerformanceReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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`.
  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'
  schemas:
    Error:
      type: object
      properties:
        status:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Token lifetime in seconds. Reported as 3600 (60 minutes).
          example: 3600
    PageMeta:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    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
    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
    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
    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
    LineItem:
      type: object
      properties:
        sku:
          type: string
        name:
          type: string
        quantity:
          type: integer
        weight:
          type: number
    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
    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.
    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
    WebhookSubscriptionInput:
      type: object
      required:
        - target_url
        - format_version
      properties:
        target_url:
          type: string
          format: uri
        format_version:
          type: string
          enum: ['5.0.0', '5.2.0']
        secret:
          type: string
          description: Shared secret used to sign the webhook payload.
    WebhookSubscription:
      allOf:
        - $ref: '#/components/schemas/WebhookSubscriptionInput'
        - type: object
          properties:
            id:
              type: string
            created_at:
              type: string
              format: date-time
    Courier:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        country:
          type: string
        service_types:
          type: array
          items:
            type: string
    PerformanceReport:
      type: object
      properties:
        date_from:
          type: string
          format: date
        date_to:
          type: string
          format: date
        groups:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              shipment_count:
                type: integer
              on_time_rate:
                type: number
              exception_rate:
                type: number
              average_transit_days:
                type: number