United States Postal Service · Schema
Subscription Event
Subscription Event
GovernmentPostal ServiceShippingLogisticsAddress ValidationPackage Tracking
Properties
| Name | Type | Description |
|---|---|---|
| subscriptionId | string | Unique identifier created for this Subscription |
| subscriptionType | string | The name of the topic related to this event. |
| timestamp | string | Timestamp message was generated, in ISO-8601 format. |
| links | object | |
| payload | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/usps/json-schema/usps-dispute-notification-schema.json",
"title": "Subscription Event",
"description": "Subscription Event",
"x-generated": "2026-11-11",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/usps-subscriptions-disputes-openapi.yml#/components/schemas/DisputeNotification",
"additionalProperties": false,
"allOf": [
{
"$ref": "#/$defs/Notification"
},
{
"type": "object",
"properties": {
"payload": {
"oneOf": [
{
"$ref": "#/$defs/DisputeDetails"
},
{
"$ref": "#/$defs/JointReviewDetails"
},
{
"$ref": "#/$defs/UnusedLabelDetails"
},
{
"$ref": "#/$defs/LettersAndFlatsDetails"
}
]
}
}
}
],
"$defs": {
"DisputeDetails": {
"type": "object",
"properties": {
"requestType": {
"type": "string",
"enum": [
"DISPUTE"
]
},
"requestStatus": {
"type": "string",
"enum": [
"CREATED",
"ACCEPTED",
"APPROVED",
"REJECTED"
],
"description": "Current status of the Request."
},
"CRID": {
"type": "string",
"description": "Customer Registration Identifier"
},
"manifestPackageID": {
"type": "string",
"description": "The manifest package Id."
},
"EPSAccountNumber": {
"type": "string",
"description": "EPS account Number."
},
"mailClass": {
"type": "string",
"description": "Mail Class."
},
"mailerID": {
"type": "string",
"description": "Mailer ID."
},
"originalDisputeAmount": {
"type": "number",
"description": "Original dispute amount",
"format": "double"
},
"transactionAmount": {
"type": "number",
"description": "Transaction amount",
"format": "double"
},
"disputeID": {
"type": "string",
"description": "Dispute Id"
},
"disputeCloseoutID": {
"type": "string",
"description": "Dispute closeout Id"
},
"disputeReason": {
"type": "string",
"description": "Dispute Reason"
},
"resolutionStatus": {
"type": "string",
"description": "Resolution Status"
},
"resolutionDate": {
"type": "string",
"description": "resolution date time.",
"format": "date-time"
}
}
},
"JointReviewDetails": {
"type": "object",
"properties": {
"requestType": {
"type": "string",
"enum": [
"JOINT_REVIEW"
]
},
"requestStatus": {
"type": "string",
"enum": [
"CREATED",
"ACCEPTED",
"REJECTED"
],
"description": "Current status of the Request."
},
"CRID": {
"type": "string",
"description": "crid."
},
"manifestPackageID": {
"type": "string",
"description": "The manifest package Id."
},
"EPSAccountNumber": {
"type": "string",
"description": "EPS account Number."
},
"mailClass": {
"type": "string",
"description": "Mail Class."
},
"mailerID": {
"type": "string",
"description": "Mailer id."
},
"originalDisputeAmount": {
"type": "number",
"description": "Original dispute amount",
"format": "double"
},
"transactionAmount": {
"type": "number",
"description": "Transaction amount",
"format": "double"
},
"disputeID": {
"type": "string",
"description": "Dispute Id"
},
"disputeCloseoutID": {
"type": "string",
"description": "Dispute closeout Id"
},
"disputeReason": {
"type": "string",
"description": "Dispute Reason"
},
"resolutionStatus": {
"type": "string",
"description": "Resolution Status"
},
"resolutionDate": {
"type": "string",
"description": "resolution date time.",
"format": "date-time"
}
}
},
"LettersAndFlatsDetails": {
"type": "object",
"properties": {
"id": {
"type": "object",
"properties": {
"subscriptionId": {
"type": "string",
"description": "Webhooks Subscription ID"
},
"subscrType": {
"type": "string",
"description": "The Subscription Disputes",
"enum": [
"DISPUTES"
]
},
"subscrSubType": {
"type": "string",
"description": "The Subscription Disputes",
"enum": [
"ALL"
]
},
"status": {
"type": "string",
"enum": [
"ACCEPTED",
"REJECTED"
],
"description": "Current status of the Request."
},
"APIRequestId": {
"maxLength": 36,
"type": "string",
"description": "UUIDv4 unique ID per request"
}
}
},
"indiciaEMASId": {
"type": "string",
"description": "The indiciaEmasId is the unique identifier for the indicia EMAS request that triggered this notification event. This can be used for troubleshooting and debugging purposes."
},
"CRIDOfMailOwner": {
"maxLength": 15,
"minLength": 8,
"type": "string",
"description": "Customer Registration ID used to identify the business location associated to a shipment."
},
"label": {
"maxLength": 31,
"minLength": 25,
"type": "string",
"description": "IMb label (barcode) for Letters/Flats, must be present for non netstamp unused label requests"
},
"disputeId": {
"maxLength": 12,
"type": "string",
"description": "Unique Id that correlates submission date and mail owner CRID"
},
"submissionDate": {
"type": "string",
"description": "When the request was submitted",
"format": "date-time"
},
"rejectionReason": {
"maxLength": 2,
"type": "string",
"enum": [
"IR",
"NM",
"SE",
"RE"
],
"description": "Reason for rejection Eg. NM (No Manifest/not paid) , SE (Scan exists), DR (Duplicate request), RE (Refunded), IR (Invalid Request)"
},
"unusedLabelFeeAmt": {
"type": "number",
"description": "000v00 format amount for unused label fee",
"format": "double"
},
"unusedLabelFeeType": {
"maxLength": 15,
"type": "string",
"enum": [
"CUSTOM",
"DEFAULT"
],
"description": "CUSTOM or DEFAULT"
},
"refundAmount": {
"type": "number",
"description": "000v00 format amount for refund",
"format": "double"
},
"paymentLabel": {
"maxLength": 31,
"minLength": 25,
"type": "string",
"description": "Extra Service Code – 2nd Service."
},
"paymentFound": {
"maxLength": 1,
"minLength": 1,
"type": "string",
"enum": [
"N",
"Y"
],
"description": "Y/N if payment was found for requested label and CRID"
},
"refundFound": {
"maxLength": 1,
"minLength": 1,
"type": "string",
"enum": [
"N",
"Y"
],
"description": "Y/N if refund was found for requested label and CRID"
},
"statusCode": {
"minLength": 0,
"maxLength": 3,
"type": "string",
"description": "Enterprise Payment System (EPS) Transaction ID."
},
"statusMessage": {
"minLength": 2,
"type": "string",
"description": "Status message corresponding to the status code."
},
"paymentEPSTranId": {
"maxLength": 28,
"type": "string",
"description": "EPS Transaction ID for successful LFPayment transactions."
},
"paymentTransactionTime": {
"type": "string",
"description": "EPS Transaction Date, Time for successful LFPayment transactions.",
"format": "date-time"
},
"paymentTotalPostage": {
"type": "number",
"description": "The amount of the transaction.",
"format": "double"
},
"compositeVersion": {
"maxLength": 15,
"type": "string",
"description": "Composite version is the combination of the API version and the version of the internal processing system that handled the request."
},
"indiciaAccountNumber": {
"type": "string",
"description": "Indicia Account Number."
},
"indiciaAccountZIPCode": {
"type": "string",
"description": "Indicia Account Zipcode."
},
"indiciaAIC": {
"type": "string",
"description": "Indicia AIC."
},
"indiciaGLA": {
"type": "string",
"description": "Indicia GLA."
},
"indiciaProcessingCategory": {
"type": "string",
"description": "Indicia Processing Category."
},
"indiciaMailingDate": {
"type": "string",
"description": "Indicia Mailing Date.",
"format": "date-time"
},
"indiciaIMB": {
"type": "string",
"description": "Indicia IMB."
},
"indiciaWeight": {
"type": "number",
"description": "Indicia Weight",
"format": "double"
},
"indiciaPostage": {
"type": "number",
"description": "Indicia Postage",
"format": "double"
},
"indiciaTotalPostage": {
"type": "number",
"description": "Indicia Total Postage",
"format": "double"
},
"indiciaSKU": {
"type": "string",
"description": "Indicia SKU."
},
"indiciaMailClass": {
"type": "string",
"description": "Indicia Mailclass."
},
"LFManifestVersion": {
"type": "string",
"description": "LF Manifest Version."
},
"LFManifestCreateDateTime": {
"type": "string",
"description": "LF Manifest Create DateTime.",
"format": "date-time"
}
}
},
"Links": {
"title": "Hypermedia Links",
"type": "array",
"description": "Hypermedia links to related resources.",
"items": {
"required": [
"href",
"rel"
],
"type": "object",
"properties": {
"rel": {
"type": "array",
"description": "The short name(s) of the relationship corresponding to the link.",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"description": "A human-readable description of the link relationship."
},
"href": {
"type": "string",
"description": "The URL to a related resource.",
"format": "uri"
},
"method": {
"type": "string",
"description": "The HTTP method to use to access this link.",
"enum": [
"GET",
"POST",
"PUT",
"DELETE"
]
},
"submissionMediaType": {
"type": "string",
"description": "The media type of the resource request."
},
"targetMediaType": {
"type": "string",
"description": "The media type of the resource response."
}
},
"additionalProperties": false
}
},
"Notification": {
"title": "Subscription Event",
"type": "object",
"properties": {
"subscriptionId": {
"type": "string",
"description": "Unique identifier created for this Subscription"
},
"subscriptionType": {
"type": "string",
"description": "The name of the topic related to this event."
},
"timestamp": {
"type": "string",
"description": "Timestamp message was generated, in ISO-8601 format.",
"format": "date-time"
},
"links": {
"$ref": "#/$defs/Links"
}
},
"additionalProperties": true,
"description": "Subscription Event"
},
"UnusedLabelDetails": {
"type": "object",
"properties": {
"requestType": {
"type": "string",
"enum": [
"UNUSED_LABEL"
]
},
"requestStatus": {
"type": "string",
"enum": [
"APPROVED",
"CREATED",
"ACCEPTED",
"PENDING",
"REJECTED"
],
"description": "Current status of the Request."
},
"CRID": {
"type": "number",
"description": "Customer Registration ID."
},
"recordType": {
"type": "string",
"description": "Record Type- D1 for manifest detail record."
},
"MID": {
"type": "number",
"description": "Mailer ID (MID)."
},
"usageIndicator": {
"type": "string",
"description": "UL - Unused Labels."
},
"PIC": {
"type": "string",
"description": "Package Identification Code (PIC)."
},
"customerReferenceNumber": {
"type": "string",
"description": "Customer Reference Number."
},
"EFN": {
"type": "string",
"description": "Electronic File Number (EFN)."
},
"dateOfMailing": {
"type": "string",
"description": "Date of Mailing.",
"format": "date-time"
},
"packageScanDate": {
"type": "string",
"description": "Package Scan Date.",
"format": "date-time"
},
"manifestDestinationZIPCode": {
"type": "number",
"description": "Manifest Destination ZIP Code."
},
"scanZIPCode": {
"type": "number",
"description": "Scan ZIP Code."
},
"manifestMailClass": {
"type": "string",
"description": "Manifest Mail Class."
},
"manifestProcessingCategory": {
"type": "string",
"description": "Manifest Processing Category."
},
"manifestRoutingBarCode": {
"type": "string",
"description": "Manifest Routing Bar Code."
},
"manifestWeight": {
"type": "number",
"description": "Manifest Weight."
},
"manifestRateIndicator": {
"type": "string",
"description": "Manifest Rate Indicator."
},
"unusedLabelRefundAmount": {
"type": "number",
"description": "Unused label refund amount",
"format": "double"
},
"extraServiceCode1": {
"type": "string",
"description": "Extra Service Code – 1st Service."
},
"extraService1Amount": {
"type": "number",
"description": "Extra Service1 Amount",
"format": "double"
},
"extraServiceCode2": {
"type": "string",
"description": "Extra Service Code – 2nd Service."
},
"extraService2Amount": {
"type": "number",
"description": "Extra Service2 Amount",
"format": "double"
},
"extraServiceCode3": {
"type": "string",
"description": "Extra Service Code – 3rd Service."
},
"extraService3Amount": {
"type": "number",
"description": "Extra Service3 Amount",
"format": "double"
},
"extraServiceCode4": {
"type": "string",
"description": "Extra Service Code – 4th Service."
},
"extraService4Amount": {
"type": "number",
"description": "Extra Service4 Amount",
"format": "double"
},
"extraServiceCode5": {
"type": "string",
"description": "Extra Service Code – 5th Service."
},
"extraService5Amount": {
"type": "number",
"description": "Extra Service5 Amount",
"format": "double"
},
"rejectionReason": {
"type": "string",
"description": "Reject Reason"
},
"transactionID": {
"type": "number",
"description": "Enterprise Payment System (EPS) Transaction ID."
},
"ACHWithdrawalID": {
"type": "number",
"description": "ACH Withdrawal ID"
},
"MRDisputeID": {
"type": "string",
"description": "Mailer Review Dispute ID"
}
}
}
}
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/usps-dispute-notification"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.