openapi: 3.0.3
info:
  title: Pitney Bowes Shipping API
  description: >-
    The Pitney Bowes Shipping API enables businesses to integrate shipping,
    rating, tracking, address validation, manifesting, and pickup operations
    directly into their applications. Authentication uses OAuth 2.0 client
    credentials.
  version: '1.0'
  contact:
    name: Pitney Bowes Shipping API
    url: https://docs.shippingapi.pitneybowes.com/
servers:
  - url: https://shipping-api.pitneybowes.com
    description: Production
  - url: https://shipping-api-sandbox.pitneybowes.com
    description: Sandbox
security:
  - oauth2: []
paths:
  /oauth/token:
    post:
      summary: Get OAuth access token
      description: >-
        Generate an OAuth access token using client credentials. Send the
        Base64-encoded API credentials in the Authorization header using
        Basic auth and grant_type=client_credentials in the body.
      operationId: getOAuthToken
      security:
        - basicAuth: []
      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: Access token returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  tokenType:
                    type: string
                  expiresIn:
                    type: integer
  /shippingservices/v1/rates:
    post:
      summary: Rate a parcel
      description: Returns shipping rates for a parcel based on origin, destination, weight, and service.
      operationId: rateParcel
      tags: [Rating]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Rates returned.
  /shippingservices/v1/shipments:
    post:
      summary: Create a shipment
      description: Creates a shipment and returns shipping label details.
      operationId: createShipment
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Shipment created.
  /shippingservices/v1/shipments/{shipmentId}:
    get:
      summary: Reprint a shipment label
      operationId: reprintShipment
      tags: [Shipments]
      parameters:
        - in: path
          name: shipmentId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Shipment label returned.
    delete:
      summary: Void a shipment
      operationId: voidShipment
      tags: [Shipments]
      parameters:
        - in: path
          name: shipmentId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Shipment voided.
  /shippingservices/v1/manifests:
    post:
      summary: Create a manifest
      operationId: createManifest
      tags: [Manifests]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Manifest created.
  /shippingservices/v1/tracking/{trackingNumber}:
    get:
      summary: Track a parcel
      operationId: trackParcel
      tags: [Tracking]
      parameters:
        - in: path
          name: trackingNumber
          required: true
          schema: { type: string }
        - in: query
          name: carrier
          schema: { type: string }
      responses:
        '200':
          description: Tracking events returned.
  /shippingservices/v1/addresses/verify:
    post:
      summary: Validate and suggest addresses
      operationId: verifyAddress
      tags: [Address]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Verified address returned.
  /shippingservices/v1/pickups:
    post:
      summary: Schedule a pickup
      operationId: schedulePickup
      tags: [Pickups]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Pickup scheduled.
  /shippingservices/v1/pickups/{pickupId}:
    delete:
      summary: Cancel a pickup
      operationId: cancelPickup
      tags: [Pickups]
      parameters:
        - in: path
          name: pickupId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Pickup cancelled.
  /shippingservices/v1/ledger/transactions/reports:
    get:
      summary: Retrieve transaction report
      operationId: getTransactionReport
      tags: [Reports]
      responses:
        '200':
          description: Transaction report returned.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Used only on /oauth/token to obtain an access token.
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://shipping-api.pitneybowes.com/oauth/token
          scopes: {}