Tracking Information Fields

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-tracking-details-schema.json",
  "title": "Tracking Information Fields",
  "description": "Detailed tracking information for the requested tracking number.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-tracking-openapi.yml#/components/schemas/TrackingDetails",
  "type": "object",
  "properties": {
    "trackingNumber": {
      "type": "string",
      "description": "The human-readble representation of package barcode data, commonly known as its tracking number"
    },
    "additionalInfo": {
      "type": "string",
      "description": "Additional package information."
    },
    "ADPScripting": {
      "type": "string",
      "description": "Additional ADP scripting specific to the ADP Type code."
    },
    "archiveRestoreInfo": {
      "type": "string",
      "description": "Information regarding availability of Restore service function."
    },
    "associatedLabel": {
      "type": "string",
      "description": "Additional Label on the mail piece, example is: EA123456785US. This is not currently populated."
    },
    "carrierRelease": {
      "type": "boolean",
      "description": "Indicating the item qualifies for the customer to electronically authorize shipment release."
    },
    "mailClass": {
      "type": "string",
      "description": "Mail Class of the mail piece (human readable). This will also include the service standard message if it exists.\n\nNote: Global Express Guaranteed Service is suspended as of September 29, 2024.\n",
      "enum": [
        "BOUND_PRINTED_MATTER",
        "LIBRARY_MAIL",
        "USPS_RETAIL_GROUND",
        "MEDIA_MAIL",
        "CRITICAL_MAIL",
        "PRIORITY_MAIL_INTERNATIONAL_PARCELS",
        "DOMESTIC_MATTER_FOR_THE_BLIND",
        "PRIORITY_MAIL_EXPRESS",
        "FIRST-CLASS_MAIL",
        "PRIORITY_MAIL_EXPRESS_INTERNATIONAL",
        "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE",
        "PARCEL_SELECT_LIGHTWEIGHT",
        "PRIORITY_MAIL_GUARANTEED",
        "GLOBAL_EXPRESS_GUARANTEED",
        "PRIORITY_MAIL",
        "PARCEL_SELECT",
        "USPS_MARKETING_MAIL",
        "PRIORITY_MAIL_SAME_DAY"
      ]
    },
    "destinationCity": {
      "type": "string",
      "description": "The destination city."
    },
    "destinationCountryCode": {
      "type": "string",
      "description": "The destination country code."
    },
    "destinationState": {
      "maxLength": 2,
      "minLength": 2,
      "pattern": "^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$",
      "type": "string"
    },
    "destinationZIP": {
      "type": "string",
      "description": "The destination ZIP Code™."
    },
    "editedLabelId": {
      "type": "string",
      "description": "The edited label identifier or Full Label identifier, example: EA123456795US."
    },
    "emailEnabled": {
      "type": "string",
      "description": "Signifies if USPS® Tracking by Email service is enabled."
    },
    "endOfDay": {
      "type": "string",
      "description": "Populated with the end of day time provided by TRP when TRP API indicates the window is \"End of Day\" or when the piece is eligible for the PTR default end of day."
    },
    "eSOFEligible": {
      "type": "boolean",
      "description": "Indicates if the mail piece is signature on file eligible."
    },
    "expectedDeliveryTimeStamp": {
      "type": "string",
      "description": "The expected delivery date.",
      "format": "date-time"
    },
    "expectedDeliveryType": {
      "type": "string",
      "description": "Populates Expected Delivery byif there is an expected delivery date."
    },
    "guaranteedDeliveryTimeStamp": {
      "type": "string",
      "description": "Guaranteed Delivery Date Global Express Mail only: certain countries provide a guarantee delivery.",
      "format": "date-time"
    },
    "guaranteedDetails": {
      "type": "string",
      "description": "Special messaging related to the guarantee."
    },
    "itemShape": {
      "type": "string",
      "description": "Indicates the shape of the item.",
      "enum": [
        "LETTER",
        "FLAT",
        "PARCEL",
        "UNKNOWN"
      ]
    },
    "kahalaIndicator": {
      "type": "string",
      "description": "Kahala Posts Group (KPG) member indicator"
    },
    "mailType": {
      "type": "string",
      "description": "Type of Mail: if kahalaIndicator is true mailTypeCode is IM (International mail) ",
      "enum": [
        "INTERNATIONAL_INBOUND",
        "INTERNATIONAL_OUTBOUND",
        "DOMESTIC_MAIL",
        "UNKNOWN"
      ]
    },
    "approximateIntakeDate": {
      "type": "string",
      "description": "Unique mail piece ID (mp-date) value, unique to each TrackID",
      "deprecated": true
    },
    "mailPieceIntakeDate": {
      "type": "string",
      "description": "Unique mail piece ID (mp-date) value, unique to each TrackID",
      "format": "date-time"
    },
    "uniqueTrackingId": {
      "type": "string",
      "description": "Unique mail piece ID (mp-suffix) value, unique to each TrackID",
      "deprecated": true
    },
    "uniqueMailPieceId": {
      "type": "string",
      "description": "Unique mail piece ID (mp-suffix) value, unique to each TrackID"
    },
    "onTime": {
      "type": "boolean",
      "description": "Indicating if the item will be delivered on time as specified in the Expected or Guaranteed delivery date."
    },
    "originCity": {
      "type": "string",
      "description": "The mail item origin city."
    },
    "originCountry": {
      "maxLength": 2,
      "type": "string",
      "description": "The mail item origin country."
    },
    "originState": {
      "maxLength": 3,
      "type": "string",
      "description": "The mail item origin state or province."
    },
    "originZIP": {
      "maxLength": 5,
      "type": "string",
      "description": "The mail item origin ZIP Code™."
    },
    "proofOfDeliveryEnabled": {
      "type": "string",
      "description": "Signifies if Proof of Delivery service is enabled."
    },
    "predictedDeliveryTimeStamp": {
      "type": "string",
      "description": "The predicted delivery date.",
      "format": "date-time",
      "deprecated": true
    },
    "predictedDeliveryDate": {
      "type": "string",
      "description": "The predicted delivery date.",
      "format": "date"
    },
    "predictedDeliveryWindowStartTime": {
      "type": "string",
      "description": "The predicted delivery window start time."
    },
    "predictedDeliveryWindowEndTime": {
      "type": "string",
      "description": "The predicted delivery window end time."
    },
    "relatedReturnReceiptID": {
      "type": "string",
      "description": "The related label ID between a tracking barcode, the core product, and a PS3811, Green Card Return Reciept. This field can contain either the core product label ID or the Green Card label ID. There is only a one to one relationship."
    },
    "redeliveryEnabled": {
      "type": "boolean",
      "description": "Field indicating if the item qualifies for redelivery."
    },
    "enabledNotificationRequests": {
      "$ref": "#/$defs/EnabledNotificationRequests"
    },
    "restoreEnabled": {
      "type": "string",
      "description": "Signifies if Restore tracking information service is enabled."
    },
    "returnDateNotice": {
      "type": "string",
      "description": "Field indicating the date the item will be Returned to Sender.",
      "format": "date"
    },
    "RRAMenabled": {
      "type": "string",
      "description": "Signifies if Return Receipt After Mailing service is enabled"
    },
    "RREEnabled": {
      "type": "string",
      "description": "Signifies if Return Receipt Electronic service is enabled"
    },
    "services": {
      "type": "array",
      "description": "Additional services purchased. Refer to the lookup table for all the possible values. \n USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix J-Table 7 Extra Service Codes ",
      "items": {
        "maxItems": 99,
        "type": "string"
      }
    },
    "serviceTypeCode": {
      "type": "string",
      "description": "The service Type Code of the mail piece.  Refer to the lookup table for all the possible values.  USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix I: Intelligent Mail Package Barcode Service Type Codes"
    },
    "status": {
      "type": "string",
      "description": "The item status.  Refer to the lookup table for all the possible values.  USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix G-4: USPS Domestic Tracking Scan Events and Appendix G-5: Scan Event Codes - International Mail"
    },
    "statusCategory": {
      "type": "string",
      "description": "The item status category.  Refer to the lookup table for all the possible values.  USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix G-4: USPS Domestic Tracking Scan Events and Appendix G-5: Scan Event Codes - International Mail"
    },
    "statusSummary": {
      "type": "string",
      "description": "The status summary."
    },
    "tableCode": {
      "type": "string",
      "description": "USPS internal description of mail piece."
    },
    "trackingProofOfDeliveryEnabled": {
      "type": "boolean",
      "description": "Signifies if Tracking Proof of Delivery service is enabled."
    },
    "valueofArticle": {
      "type": "string",
      "description": "The value of article"
    },
    "accessControl": {
      "$ref": "#/$defs/AccessControl"
    },
    "extendRetentionPurchasedCode": {
      "type": "string",
      "description": "Populates the Extended Retention extra service charge purchased on the mail piece."
    },
    "extendRetentionExtraServiceCodeOptions": {
      "type": "array",
      "description": "Contain a list of available extended retention ESCs eligible for a mail piece.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "description": "Populates an extended retention extra service charge eligible for the mail piece."
      }
    },
    "trackingEvents": {
      "maxItems": 99,
      "minItems": 0,
      "type": "array",
      "description": "The detailed tracking event information for the requested tracking number in reverse chronological order",
      "items": {
        "$ref": "#/$defs/TrackingEvent"
      }
    }
  },
  "additionalProperties": true,
  "$defs": {
    "AccessControl": {
      "title": "Access Control",
      "type": "string",
      "description": "Details on if the Tracking request was free or charged based on MID access through an IP Agreement.\n\n- `FREE` - The Tracking request was free.\n- `IP_AGREEMENT` - The tracking request was charged based on MID access through an IP Agreement.\n",
      "enum": [
        "FREE",
        "IP_AGREEMENT"
      ]
    },
    "AvailableNotificationOptions": {
      "title": "Available Notification Options",
      "type": "object",
      "properties": {
        "futureDelivery": {
          "type": "boolean",
          "description": "Mail piece eligibility for Future Delivery  Expected Delivery Date / Time Updates requests. Future activity only on the package."
        },
        "alertDelivery": {
          "type": "boolean",
          "description": "Mail piece eligibility for Alert - Delivery Expection requests. All past and future activity on the package."
        },
        "todayDelivery": {
          "type": "boolean",
          "description": "Mail piece eligibility for Today Delivery  Day of Delivery Update requests."
        },
        "UP": {
          "type": "boolean",
          "description": "Mail piece eligibility for UP / Mail Pickup Available for Pickup requests."
        },
        "DND": {
          "type": "boolean",
          "description": "Mail piece eligibility for DND  Delivery Activity requests. Notification of each delivery or delivery attempt."
        }
      },
      "additionalProperties": false,
      "description": "Noticication options that are available for the tracking number"
    },
    "EnabledNotificationRequests": {
      "title": "Enabled Notification Requests",
      "type": "object",
      "properties": {
        "SMS": {
          "$ref": "#/$defs/AvailableNotificationOptions"
        },
        "EMail": {
          "description": "E-mail notification.",
          "allOf": [
            {
              "$ref": "#/$defs/AvailableNotificationOptions"
            },
            {
              "type": "object",
              "properties": {
                "firstDisplayable": {
                  "type": "boolean",
                  "description": "Mail piece eligibility for FS  First displayable event for Informed Delivery / MyUSPS only requests."
                },
                "otherActivity": {
                  "type": "boolean",
                  "description": "Mail piece eligibility for OA  In-Transit / Other Activity requests."
                }
              },
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false,
      "description": "USPS® Text Tracking is a mechanism by which customers can be notified of the status of their package."
    },
    "TrackingEvent": {
      "title": "Tracking Event",
      "type": "object",
      "properties": {
        "eventType": {
          "type": "string",
          "description": "The type of event"
        },
        "eventTimestamp": {
          "type": "string",
          "description": "The date of the event.",
          "format": "date-time"
        },
        "GMTTimestamp": {
          "type": "string",
          "description": "The date-time of the event in Greenwich Mean Time (GMT).",
          "format": "date-time"
        },
        "GMTOffset": {
          "type": "string",
          "description": "The offset of the local time of the event from Greenwich Mean Time (GMT)."
        },
        "eventCountry": {
          "type": "string",
          "description": "The country where the event occurred."
        },
        "eventCity": {
          "type": "string",
          "description": "The city where the event occurred."
        },
        "eventState": {
          "type": "string",
          "description": "The state where the event occurred."
        },
        "eventZIP": {
          "type": "string",
          "description": "The ZIP Code™ of the event."
        },
        "firm": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "The company name if delivered to a company."
        },
        "name": {
          "type": "string",
          "description": "The name of the persons signing for delivery (if available)."
        },
        "authorizedAgent": {
          "type": "string",
          "description": "Indicating whether the person signing is an Authorized Agent."
        },
        "eventCode": {
          "type": "string",
          "description": "Refer to the lookup table for all the possible values.  USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix G-4:USPS® Domestic Tracking Scan Events "
        },
        "veriPoint": {
          "type": "boolean",
          "description": "Delivery scan location certified, if applicable.  Refer to GeoCertified"
        },
        "actionCode": {
          "type": "string",
          "description": "Refer to  Pub 199 page 256 for list of Action Codes"
        },
        "reasonCode": {
          "type": "string",
          "description": "Refer to the lookup table for all the possible values.  USPS® [Pub 199](http://postalpro.usps.com/pub199) Appendix G-4: USPS® Domestic Tracking Scan Events"
        }
      },
      "additionalProperties": true,
      "description": "To be done."
    }
  }
}