Subscription

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-tracking-subscription-schema.json",
  "title": "Subscription",
  "description": "Subscription for the tracking event data the consumer is receiving.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-subscriptions-tracking-openapi.yml#/components/schemas/TrackingSubscription",
  "allOf": [
    {
      "$ref": "#/$defs/Subscription"
    },
    {
      "required": [
        "filterProperties",
        "listenerURL",
        "secret"
      ],
      "type": "object",
      "properties": {
        "filterProperties": {
          "description": "The filters that should be applied to the subscription. The structure of this property will change dependent on the type of subscription a client is signing up for.",
          "oneOf": [
            {
              "$ref": "#/$defs/MIDTrackingFilter"
            },
            {
              "$ref": "#/$defs/TrackingNumberFilter"
            }
          ]
        }
      },
      "additionalProperties": true
    }
  ],
  "$defs": {
    "EmailNotification": {
      "type": "object",
      "properties": {
        "email": {
          "maxLength": 100,
          "type": "string",
          "description": "E-mail address of recipient. Valid e-mail addresses must be used used for notifications via email. ",
          "format": "email"
        }
      }
    },
    "MIDTrackingFilter": {
      "title": "Tracking subscription based on a MID",
      "required": [
        "MID"
      ],
      "type": "object",
      "properties": {
        "MID": {
          "pattern": "^(\\d{6}|\\d{9})$",
          "type": "string",
          "description": "Specify the Mailer ID that should be included in the subscription. Once a subscription is created this field cannot be changed through a future edit, instead the subscription should be deleted and a new subscription should be created."
        },
        "trackingEventTypes": {
          "type": "array",
          "description": "Specify what tracking events should be include in the subscription: </p>\nALL                        - All Below Updates </p>\nPACKAGE_DELIVERED          - Receive a message when package has been delivered to the recipient's \n                             address or when it's been delivered to a delivery partner (if applicable). </p>\nAVAILABLE_FOR_PICKUP       - Receive a message when your package is ready to be picked up at your \n                             local Post Office location. </p>\nDELIVERY_EXCEPTION_UPDATES - Receive a message when there are other delivery updates, alerts\n                             about potential delays (including weather-related delays), or\n                             actions needed (e.g., Schedule Redelivery) related to your package. (Exceptions?)</p>\nPACKAGE_IN_TRANSIT_UPDATES - Receive a message when your package is in-transit with the current \n                             expected delivery date, if available. (InTransit?)</p>\nPACKAGE_DELAYED            - Package has been delayed</p> \nDEFAULT                        - Includes PACKAGE_DELIVERED, AVAILABLE_FOR_PICKUP, DELIVERY_EXCEPTION_UPDATES, and PACKAGE_IN_TRANSIT_UPDATES",
          "items": {
            "type": "string",
            "enum": [
              "ALL",
              "PACKAGE_DELIVERED",
              "AVAILABLE_FOR_PICKUP",
              "DELIVERY_EXCEPTION_UPDATES",
              "PACKAGE_IN_TRANSIT_UPDATES",
              "PACKAGE_DELAYED",
              "DEFAULT"
            ]
          },
          "default": [
            "ALL"
          ]
        }
      },
      "additionalProperties": true,
      "description": "Filter by MID"
    },
    "Subscription": {
      "title": "Subscription",
      "required": [
        "adminNotification",
        "filterProperties",
        "listenerURL",
        "secret"
      ],
      "type": "object",
      "properties": {
        "subscriptionId": {
          "type": "string",
          "description": "Unique Identifier created for this Subscription.",
          "readOnly": true
        },
        "listenerURL": {
          "type": "string",
          "description": "Customer URL in which subscription data will be sent. You can parse the data received on the server URL, and you can call back to the Tracking API for the full detailed set of events.",
          "maxLength": 200,
          "format": "uri"
        },
        "secret": {
          "maxLength": 32,
          "minLength": 32,
          "type": "string",
          "description": "Customer supplied secret USPS will use to create a hash value.  The hash will be provided in the Notification payload. USPS will use the SHA-256 algorithm to create the hash value."
        },
        "status": {
          "type": "string",
          "description": "Current status of the subscription.  USPS will post notifications to the supplied listenerURL.  If the listenerURL cannot be reached or is invalid, USPS will change the status of the subscription to SUSPENDED.  The customer has the option of changing the status to DISABLED.  It is recommended the customer change the status to DISABLED if they know their endpoint will not be active, i.e operational maintenance.",
          "enum": [
            "DISABLED",
            "ENABLED",
            "SUSPENDED"
          ]
        },
        "statusReason": {
          "type": "string",
          "description": "When status is suspended the Status Reason will return why it was suspended.",
          "readOnly": true
        },
        "adminNotification": {
          "maxItems": 3,
          "minItems": 1,
          "type": "array",
          "description": "Customer can supply an email address to receive important updates on the status and events related to the subscription.",
          "items": {
            "$ref": "#/$defs/EmailNotification"
          }
        },
        "creationTimestamp": {
          "type": "string",
          "description": "When the subscription was originally created.",
          "format": "date-time",
          "readOnly": true
        },
        "statusChangeTimestamp": {
          "type": "string",
          "description": "Time when the status was last changed.",
          "format": "date-time",
          "readOnly": true
        },
        "expirationTimestamp": {
          "type": "string",
          "description": "When the subscription expires.",
          "format": "date-time",
          "readOnly": true
        },
        "accessControl": {
          "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"
          ],
          "readOnly": true
        }
      },
      "additionalProperties": true,
      "description": "Subscription for the tracking event data the consumer is receiving."
    },
    "TrackingNumberFilter": {
      "title": "Tracking subscription based on a specific tracking number",
      "required": [
        "trackingNumber"
      ],
      "type": "object",
      "properties": {
        "trackingNumber": {
          "type": "string",
          "description": "Specify the Mailer ID that should be included in the subscription. Once a subscription is created this field cannot be changed through a future edit, instead the subscription should be deleted and a new subscription should be created."
        },
        "trackingEventTypes": {
          "type": "array",
          "description": "Specify what tracking events should be include in the subscription: </p>\nALL                        - All Below Updates </p>\nPACKAGE_DELIVERED          - Receive a message when package has been delivered to the recipient's \n                             address or when it's been delivered to a delivery partner (if applicable). </p>\nAVAILABLE_FOR_PICKUP       - Receive a message when your package is ready to be picked up at your \n                             local Post Office location. </p>\nDELIVERY_EXCEPTION_UPDATES - Receive a message when there are other delivery updates, alerts\n                             about potential delays (including weather-related delays), or\n                             actions needed (e.g., Schedule Redelivery) related to your package. (Exceptions?)</p>\nPACKAGE_IN_TRANSIT_UPDATES - Receive a message when your package is in-transit with the current \n                             expected delivery date, if available. (InTransit?)</p>\nPACKAGE_DELAYED            - Package has been delayed\nDEFAULT                        - Includes PACKAGE_DELIVERED, AVAILABLE_FOR_PICKUP, DELIVERY_EXCEPTION_UPDATES, and PACKAGE_IN_TRANSIT_UPDATES",
          "items": {
            "type": "string",
            "enum": [
              "ALL",
              "PACKAGE_DELIVERED",
              "AVAILABLE_FOR_PICKUP",
              "DELIVERY_EXCEPTION_UPDATES",
              "PACKAGE_IN_TRANSIT_UPDATES",
              "PACKAGE_DELAYED",
              "DEFAULT"
            ]
          },
          "default": [
            "ALL"
          ]
        }
      },
      "additionalProperties": true,
      "description": "Filter by tracking number"
    }
  }
}