Subscription List

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-subscriptions-schema.json",
  "title": "Subscription List",
  "description": "List of subscriptions",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-subscriptions-adjustments-openapi.yml#/components/schemas/Subscriptions",
  "type": "array",
  "items": {
    "$ref": "#/$defs/AdjustmentSubscription"
  },
  "$defs": {
    "AdjustmentSubscription": {
      "title": "Subscription",
      "description": "Subscription for the adjustment event data the consumer is receiving.",
      "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": [
                "ADJUSTMENT"
              ]
            },
            "filterProperties": {
              "$ref": "#/$defs/CRIDAdjustmentFilter"
            }
          }
        }
      ]
    },
    "CRIDAdjustmentFilter": {
      "title": "Adjustment Subscription",
      "type": "object",
      "properties": {
        "CRID": {
          "type": "string",
          "description": "Specify the Customer Registration 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."
        },
        "eventTypes": {
          "type": "array",
          "description": "Specify what adjustment events should be include in the subscription: </p>\nALL                        - All Below Updates </p>\nCENSUS                     - Adjustments where package characteristics are captured during network processing that do \n                             not align with the manifested characteristics and lead to differences in manifested vs expected payments.\nDUPLICATES                 - Adjustments where multiple packages are shipped with the same barcode without corresponding \n                             payment records for secondary packages.\nUNMANIFESTED               - Adjustments where packages are accepted and delivered without corresponding \n                             payment records for the packages.",
          "items": {
            "type": "string",
            "enum": [
              "ALL",
              "CENSUS",
              "DUPLICATES",
              "UNMANIFESTED"
            ]
          },
          "default": [
            "ALL"
          ]
        }
      },
      "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",
      "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 Adjustments 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."
    }
  }
}