Subscription

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-package-transaction-details-subscription-schema.json",
  "title": "Subscription",
  "description": "Subscription for the package transaction details 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-package-transaction-details-openapi.yml#/components/schemas/PackageTransactionDetailsSubscription",
  "allOf": [
    {
      "$ref": "#/$defs/Subscription"
    },
    {
      "required": [
        "filterProperties",
        "listenerURL",
        "secret"
      ],
      "type": "object",
      "properties": {
        "subscriptionType": {
          "type": "string",
          "description": "The subscription type defines the data domain for this subscription.",
          "readOnly": true,
          "enum": [
            "PACKAGE_TRANSACTION_DETAILS"
          ]
        },
        "filterProperties": {
          "$ref": "#/$defs/CRIDPackageTransactionDetailsFilter"
        }
      }
    }
  ],
  "$defs": {
    "CRIDPackageTransactionDetailsFilter": {
      "title": "Package Transaction Details Subscription",
      "type": "object",
      "properties": {
        "CRID": {
          "maxLength": 15,
          "minLength": 8,
          "type": "string",
          "description": "Customer Registration ID used to identify the business location associated to a shipment.",
          "pattern": "^[\\S\\s]{0,255}$"
        },
        "eventTypes": {
          "type": "array",
          "minItems": 1,
          "maxItems": 2,
          "description": "Specify what package transaction detail events should be include in the subscription: </p>\nNON_LABEL_FEE     - Package that does not have a label in manifest \n\nRETURN_LABEL - Package that has a return label",
          "items": {
            "type": "string",
            "enum": [
              "NON_LABEL_FEE",
              "RETURN_LABEL"
            ]
          },
          "default": [
            "NON_LABEL_FEE"
          ]
        }
      },
      "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."
    },
    "EmailNotification": {
      "type": "object",
      "description": "Email Address for Notifications",
      "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"
        }
      }
    },
    "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 Package Transaction Details API for the full latest status of events.",
          "format": "uri",
          "maxLength": 200
        },
        "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
        }
      },
      "additionalProperties": true,
      "description": "Subscription for the tracking event data the consumer is receiving."
    }
  }
}