{
  "openapi": "3.0.1",
  "info": {
    "title": "Tracking APIs",
    "description": "The Tracking APIs provide operations to retrieve shipment tracking details and manage tracking subscriptions across supported carriers. These APIs enable access to shipment status and event history using a tracking number, supporting visibility into shipment progress and delivery.\n\nThey support both on-demand tracking retrieval and subscription-based tracking, allowing systems to monitor shipment progress and receive updates as tracking events occur.\n\n**Tracking Number**\n\nA unique identifier assigned to a shipment, used to retrieve tracking details.\n\n**Carrier**\n\nIdentifies the shipping carrier associated with the tracking number. Supported values include USPS, UPS, FEDEX, and DHLEXP.\n\n\n**Tracking Events**\n\nA collection of shipment status updates representing the lifecycle of a shipment (e.g., accepted, in transit, out for delivery, delivered).\n\n- Tracking details are retrieved using the `trackingNumber` and `carrier` parameter\n- The response includes a list of tracking events representing shipment progress\n- Subscription API allows enabling or disabling tracking updates using the subscribe parameter:\n  - true: Subscribes to tracking updates\n  - false: Unsubscribes from tracking updates\n- Subscribed tracking provides updated tracking event information in the response\n- Each request includes a unique `X-PB-TransactionId` for tracking and auditing\n",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://api-sandbox.sendpro360.pitneybowes.com/shippingtracking",
      "description": "Sandbox Server"
    },
    {
      "url": "https://api.sendpro360.pitneybowes.com/shippingtracking",
      "description": "Production Server (uses live data)"
    },
    {
      "url": "https://api-ppd.shipping360.pitneybowes.com/ca/shippingtracking",
      "description": "Sandbox Server for Canada"
    },
    {
      "url": "https://api.shipping360.pitneybowes.com/ca/shippingtracking",
      "description": "Production Server for Canada"
    }
  ],
  "tags": [
    {
      "name": "Tracking",
      "description": "APIs for retrieving shipment tracking details and managing tracking subscriptions."
    }
  ],
  "paths": {
    "/api/v1/tracking/{trackingNumber}": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "summary": "Get Shipment Tracking Details",
        "description": "Get Shipment Tracking Details",
        "operationId": "getShipmentTrackingDetails",
        "parameters": [
          {
            "name": "X-PB-Developer-Partner-ID",
            "in": "header",
            "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "This indicates the parcel tracking number of created shipment",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "carrier",
            "in": "query",
            "description": "This indicates carrier ID",
            "schema": {
              "type": "string",
              "enum": [
                "USPS",
                "UPS",
                "FEDEX",
                "DHLEXP"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get Shipment Tracking Details",
            "headers": {
              "X-Pb-Transactionid": {
                "schema": {
                  "type": "string",
                  "example": "zR1x43AjL1pBevQ"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingEvents"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/v1/track/{trackingNumber}/subscribe": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "summary": "Subscribe Tracking Details",
        "description": "Subscribe To Shipment Tracking Details",
        "operationId": "subscribeShipmentTrackingDetails",
        "parameters": [
          {
            "name": "X-PB-Developer-Partner-ID",
            "in": "header",
            "description": "This is the Developer Partner ID. When the developer is the only partner, this field is not required.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "This indicates the parcel tracking number of created shipment",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "carrier",
            "in": "query",
            "description": "This indicates carrier ID",
            "schema": {
              "type": "string",
              "enum": [
                "USPS",
                "UPS",
                "FEDEX",
                "DHLEXP"
              ]
            }
          },
          {
            "name": "subscribe",
            "in": "query",
            "description": "This indicates subscribe to shipment tracking when set to true and unsubscribe to shipment tracking when set to false",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get Shipment Subscribed Tracking Details",
            "headers": {
              "X-PB-TransactionId": {
                "schema": {
                  "type": "string",
                  "example": "zR1x43AjL1pBevQ"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "it shows the tracking message",
                      "example": "Tracking number subscribed successfully"
                    },
                    "trackingEvents": {
                      "description": "it shows the tracking events",
                      "$ref": "#/components/schemas/TrackingEvents"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Unauthorized",
            "description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource."
          }
        },
        "required": [
          "message"
        ]
      },
      "Errors": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "errorCode": {
                  "type": "string",
                  "description": "Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g. validation-error.",
                  "example": "validation_error"
                },
                "errorDescription": {
                  "type": "string",
                  "description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).",
                  "example": "Error while getting rates for carrier with carrierAccount eRMnRx4mzPP."
                },
                "additionalCode": {
                  "type": "string",
                  "description": "A unique identifier for the error, for example 1101055, 0100008, or 1021126."
                },
                "additionalInfo": {
                  "type": "string",
                  "description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
                },
                "additionalParameters": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "The field(s) that might be incorrect in the request."
                  }
                }
              }
            }
          }
        }
      },
      "NotFoundErrors": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "errorCode": {
                  "type": "string",
                  "description": "Error code(s) that appear due to HTTP 404 Page or File not found",
                  "example": "not_found"
                },
                "errorDescription": {
                  "type": "string",
                  "description": "The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.",
                  "example": "resource not found."
                },
                "additionalCode": {
                  "type": "string",
                  "description": "A unique identifier for the error, for example 1101055, 0100008, or 1021126."
                },
                "additionalInfo": {
                  "type": "string",
                  "description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
                },
                "additionalParameters": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "The field(s) that might be incorrect in the request."
                  }
                }
              }
            }
          }
        }
      },
      "TrackingEvents": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": "string",
            "description": "it shows the carrier used for the shipment",
            "example": "FEDEX"
          },
          "currentLocation": {
            "type": "object",
            "description": "it shows the current location of the shipment",
            "properties": {
              "city": {
                "type": "string",
                "description": "it shows the current city location of the shipment",
                "example": "Miami"
              },
              "country": {
                "type": "string",
                "description": "it shows the current location country of the shipment",
                "example": "US"
              },
              "description": {
                "type": "string",
                "description": "it shows the current description details of the shipment",
                "example": "Delivered"
              },
              "postalCode": {
                "type": "string",
                "description": "it shows the current location postal code of the shipment",
                "example": "33122"
              },
              "stateOrProvince": {
                "type": "string",
                "description": "it shows the current state or province of the shipment",
                "example": "FL"
              }
            }
          },
          "currentStatus": {
            "type": "object",
            "properties": {
              "carrierEventCode": {
                "type": "string",
                "description": "It is the carrier returned carrier event code",
                "example": "DL"
              },
              "carrierEventDescription": {
                "type": "string",
                "description": "It is the carrier returned carrier event description",
                "example": "Delivered"
              },
              "eventCode": {
                "type": "string",
                "description": "It is the Pitney bowes returned event code",
                "enum": [
                  "AWP- Awaiting Pickup",
                  "CUC-Customs Cleared",
                  "DAT-Delivery Attempt",
                  "DLD-Delivered",
                  "DYU-Delay -Undeliverable",
                  "INF-Information Event",
                  "MSC-Miscellaneous Event",
                  "OFD-Out for Delivery",
                  "PSR-Tracking details uploaded",
                  "RTS-Return - Shipped to Retailer",
                  "SPH-Shipped from Shipping Center to International Destination",
                  "TRD-In Transit",
                  "UDL-Unable to deliver"
                ]
              },
              "eventDate": {
                "type": "string",
                "description": "it displays the event date",
                "example": "2026-06-19T02:10:00-05:00"
              },
              "eventDescription": {
                "type": "string",
                "description": "it displays the event description",
                "example": "Delivered"
              },
              "eventLocation": {
                "type": "object",
                "description": "it displays the event location",
                "properties": {
                  "city": {
                    "type": "string",
                    "description": "it displays the current event location city",
                    "example": "Miami"
                  },
                  "country": {
                    "type": "string",
                    "description": "it displays the current event location country",
                    "example": "US"
                  },
                  "description": {
                    "type": "string",
                    "description": "it displays the current event description",
                    "example": ""
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "it displays the current event location postal code",
                    "example": "33122"
                  },
                  "stateOrProvince": {
                    "type": "string",
                    "description": "it displays the current event location state or province",
                    "example": "FL"
                  }
                }
              },
              "status": {
                "type": "string",
                "description": "it displays the current event status",
                "example": "Delivered"
              }
            }
          },
          "deliveryDate": {
            "type": "string",
            "description": "It displays the delivery date",
            "example": "2023-06-28T16:55:00.000Z"
          },
          "deliveryProofUrl": {
            "type": "string",
            "description": "The URL to access either a picture of the delivered package or a picture of the signature confirmation.",
            "example": ""
          },
          "estimatedDeliveryDate": {
            "type": "string",
            "description": "The estimated date at the destination that the package will be delivered, specified in the YYYY-MM-DD format.",
            "example": "1901-01-01T00:00:00.000Z"
          },
          "serviceCode": {
            "type": "string",
            "description": "The carrier’s code for the service.",
            "example": ""
          },
          "serviceName": {
            "type": "string",
            "description": "The carrier’s name for the service.",
            "example": "FedEx Ground"
          },
          "shipDate": {
            "type": "string",
            "description": "The date at the origin when the package was shipped, specified in the YYYY-MM-DD format.",
            "example": "1901-01-01T00:00:00.000Z"
          },
          "trackingHistory": {
            "type": "array",
            "description": "it displays the tracking history",
            "items": {
              "type": "object",
              "properties": {
                "carrierEventCode": {
                  "type": "string",
                  "description": "it displays the carrier returned event code",
                  "example": "DL"
                },
                "carrierEventDescription": {
                  "type": "string",
                  "description": "it displays the carrier returned event description",
                  "example": "Delivered"
                },
                "eventCode": {
                  "type": "string",
                  "description": "it displays the Pitney Bowes returned event code",
                  "example": "DLD"
                },
                "eventDate": {
                  "type": "string",
                  "description": "it displays the event date",
                  "example": "2026-06-19T02:10:00-05:00"
                },
                "eventTimeOffset": {
                  "type": "string",
                  "example": "-07:00",
                  "description": "it displays the event time offset. The time offset is the difference in time between the local time at the event location and Coordinated Universal Time (UTC). It is represented in the format ±[hh]:[mm], where ± indicates whether the local time is ahead of (positive) or behind (negative) UTC, hh is the number of hours, and mm is the number of minutes. For example, a time offset of -07:00 indicates that the local time is 7 hours behind UTC."
                },
                "eventDescription": {
                  "type": "string",
                  "description": "it displays the event description",
                  "example": "Delivered"
                },
                "eventLocation": {
                  "type": "object",
                  "description": "it displays the event location details",
                  "properties": {
                    "city": {
                      "type": "string",
                      "description": "it displays the event location city",
                      "example": "Miami"
                    },
                    "country": {
                      "type": "string",
                      "description": "it displays the event location country",
                      "example": "US"
                    },
                    "description": {
                      "type": "string",
                      "description": "it displays the event description details",
                      "example": ""
                    },
                    "postalCode": {
                      "type": "string",
                      "description": "it displays the event location postal code",
                      "example": "33122"
                    },
                    "stateOrProvince": {
                      "type": "string",
                      "description": "it displays the event location state or province",
                      "example": "FL"
                    }
                  }
                },
                "status": {
                  "type": "string",
                  "description": "it displays the event status",
                  "example": "Delivered"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "The request could not be authorized.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "The request could not be completed due to an internal error.",
        "content": {}
      },
      "BadRequestError": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Errors"
            }
          }
        }
      },
      "NotFoundError": {
        "description": "The requested resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/NotFoundErrors"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}