United States Postal Service · Schema
Label Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`.
GovernmentPostal ServiceShippingLogisticsAddress ValidationPackage Tracking
Properties
| Name | Type | Description |
|---|---|---|
| labelAddress | object | |
| routingInformation | string | The "420" 3-digit GS1 Application Identifier and the 5 or 9 digit Destination ZIP Code™. |
| trackingNumber | string | The human-readable version of the package tracking number. |
| constructCode | string | The barcode construct code associated with the tracking number. |
| SKU | string | Pricing SKU. |
| postage | number | Amount of Postage Required, does not include insurance or other extra service fees. |
| extraServices | object | |
| serviceTypeCode | string | The Service Type Code associated with the package. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes |
| zone | string | Indicates the calculated zone used for pricing between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, `rateIndicator`, and `weight`. |
| mailingDate | string | The date on which the package will be mailed as provided in the request. If the time was not provided, it will be defaulted to 10:00 p.m. local time. |
| commitment | object | |
| weightUOM | string | Weight Unit of Measurement * lb - Pounds |
| weight | number | The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less. |
| dimensionalWeight | number | The dimensional weight of the package, if greater than specified in weight, in ounces. |
| fees | array | Fees associated with the package. |
| permitHolderName | string | The permit holder name. |
| inductionType | object | The permit holder induction type. |
| labelBrokerID | string | Unique Label Broker ID that can be used as an alternative to the Label Broker QR Code to retrieve the label at a Post Office. Will only be provided when an imageType of LABEL_BROKER is requested. |
| bannerText | string | Banner text printed on the label. |
| retailDistributionCode | string | Retail Description Code associated with label. |
| returnReceiptTrackingNumber | string | The human-readable version of the return Receipt tracking number. * Note: This will be included in the response when `packageOptions.returnReceiptTracking` is set to true in the request. |
| links | object | |
| warnings | object | |
| labelImage | string | Contains the Base64-encoded file contents of the label image. Provided only when `imageInfo.imageType` is not `NONE`. Note: - Not provided when Extra Service Code `415 - USPS Label Delivery` is reques |
| receiptImage | string | Contains the Base64-encoded file contents of the label receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`. Note: - When `imageInfo.imageType` is `ZPL203DPI`, `ZPL300DPI`, o |
| labelBrokerQR | string | The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`. |
| returnLabel | object | Return label |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/usps/json-schema/usps-label-vendor-response-schema.json",
"title": "Label Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`.",
"x-generated": "2026-11-11",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/usps-domestic-labels-openapi.yml#/components/schemas/LabelVendorResponse",
"type": "object",
"allOf": [
{
"$ref": "#/$defs/LabelMetadata"
},
{
"type": "object",
"properties": {
"labelImage": {
"type": "string",
"description": "Contains the Base64-encoded file contents of the label image. Provided only when `imageInfo.imageType` is not `NONE`.\n\nNote:\n- Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.\n",
"format": "byte"
},
"receiptImage": {
"type": "string",
"description": "Contains the Base64-encoded file contents of the label receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.\n\nNote:\n- When `imageInfo.imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL or EPL payload in `labelImage`. In this case, `receiptImage` will not be populated.\n- Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.\n",
"format": "byte"
},
"labelBrokerQR": {
"type": "string",
"description": "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`.",
"format": "byte"
},
"returnLabel": {
"description": "Return label",
"allOf": [
{
"$ref": "#/$defs/ReturnLabelMetadata"
},
{
"type": "object",
"properties": {
"returnLabelImage": {
"type": "string",
"description": "Contains the Base64-encoded file contents of the return label image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.imageType` is not `NONE`.\n",
"format": "byte"
},
"returnReceiptImage": {
"type": "string",
"description": "Contains the Base64-encoded file contents of the return receipt image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.receiptOption` is `SEPARATE_PAGE`.\n\nNote:\n- When `imageInfo.imageType` is `ZPL203DPI` or `ZPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.\n",
"format": "byte"
},
"labelBrokerQR": {
"type": "string",
"description": "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`.",
"format": "byte"
}
}
}
]
}
}
}
],
"$defs": {
"Address": {
"title": "Address",
"type": "object",
"properties": {
"streetAddress": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "The number of a building along with the name of the road or street on which it is located."
},
"streetAddressAbbreviation": {
"maxLength": 50,
"minLength": 0,
"type": "string",
"description": "This is the abbreviation of street address line for the address.",
"readOnly": true
},
"secondaryAddress": {
"maxLength": 50,
"type": "string",
"description": "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building. For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
},
"cityAbbreviation": {
"type": "string",
"description": "This is the abbreviation of city name for the address.",
"readOnly": true
}
},
"additionalProperties": true,
"description": "Address fields standard to all locations."
},
"Addressee": {
"title": "Addressee",
"type": "object",
"properties": {
"firstName": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "First Name corresponding to the address."
},
"lastName": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "Last Name corresponding to the address."
},
"firm": {
"maxLength": 50,
"minLength": 0,
"type": "string",
"description": "Firm/business name corresponding to the address."
}
},
"additionalProperties": true,
"description": "Fields used to identity the entity receiving a mail piece or package"
},
"Commitment": {
"title": "Commitment",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Commitment name such as 1-day, 2-day, 3-day, Military, DPO."
},
"scheduleDeliveryDate": {
"type": "string",
"description": "Date in the `YYYY-MM-DD` format. Date USPS expects that the package or mailpiece will be delivered based on the origin, destination, and drop-off time and date in the request. Actual delivery date may vary based on when the package or mailpiece is entered or other conditions.\n\nNote: This field has been deprecated in favor of `expectedDeliveryDate` and will be removed in a future release. Please transition to using `expectedDeliveryDate`.\n",
"deprecated": true
},
"expectedDeliveryDate": {
"type": "string",
"description": "Date in the YYYY-MM-DD format."
},
"isPriorityMailNextDay": {
"type": "boolean",
"description": "Indicates if the commitment is for Priority Mail Next Day service."
}
},
"additionalProperties": true,
"description": "The commitment and scheduled delivery date of the package."
},
"DomesticAddress": {
"title": "Domestic Address",
"additionalProperties": true,
"description": "Address fields for US locations",
"allOf": [
{
"$ref": "#/$defs/Address"
},
{
"type": "object",
"properties": {
"city": {
"maxLength": 28,
"minLength": 1,
"type": "string",
"description": "This is the city name of the address."
},
"state": {
"$ref": "#/$defs/State"
},
"ZIPCode": {
"pattern": "^\\d{5}$",
"type": "string",
"description": "This is the 5-digit ZIP code."
},
"ZIPPlus4": {
"pattern": "^\\d{4}$",
"type": [
"string",
"null"
],
"description": "This is the 4-digit component of the ZIP+4 code. Using the correct Zip+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error."
},
"urbanization": {
"maxLength": 96,
"type": "string",
"description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)."
}
},
"additionalProperties": true
}
]
},
"DomesticLabelAddress": {
"title": "Domestic Label Address",
"required": [
"ZIPCode",
"city",
"state",
"streetAddress"
],
"type": "object",
"additionalProperties": true,
"description": "The address where the package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing. \n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* If the `returnAddress` is not provided, the `fromAddress` will be used as the `returnAddress`.\n* If the `returnLabel` field is set to “true”, then the `fromAddress` ZIP Plus 4 is looked up by the API, unless the `ignoreBadAddress` field is set to true or the address cannot be found. If `ignoreBadAddress` field is true then ZIP Plus 4 is required.\n",
"allOf": [
{
"$ref": "#/$defs/DomesticAddress"
},
{
"$ref": "#/$defs/Addressee"
},
{
"type": "object",
"properties": {
"phone": {
"$ref": "#/$defs/Phone"
},
"email": {
"$ref": "#/$defs/Email"
},
"ignoreBadAddress": {
"type": "boolean",
"description": "Allows Non-Validated Origin Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.\n\nNote: Integrators are recommended to always use `false` to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when `true` is indicated to allow label creation which could impact delivery.\n"
}
},
"additionalProperties": true
}
]
},
"Email": {
"maxLength": 50,
"pattern": "^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$",
"type": "string",
"description": "Email address used for redirect notification via email. ",
"format": "email"
},
"ExtraServiceResponse": {
"title": "Extra Service Response",
"type": "array",
"minItems": 0,
"description": "Extra services requested on the mailpiece.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the extra service."
},
"SKU": {
"type": "string",
"description": "SKU of the extra service."
},
"price": {
"type": "number",
"description": "The price for the extra service.",
"format": "float"
},
"warnings": {
"type": "array",
"description": "Warnings and additional details around the Extra Services.",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"warningCode": {
"type": "string",
"description": "Code corresponding to the warning"
},
"warningDescription": {
"type": "string",
"description": "Warning or additional information regarding the Extra Service."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"LabelMetadata": {
"title": "Label Metadata",
"type": "object",
"properties": {
"labelAddress": {
"$ref": "#/$defs/DomesticLabelAddress"
},
"routingInformation": {
"type": "string",
"description": "The \"420\" 3-digit GS1 Application Identifier and the 5 or 9 digit Destination ZIP Code™."
},
"trackingNumber": {
"type": "string",
"description": "The human-readable version of the package tracking number."
},
"constructCode": {
"type": "string",
"description": "The barcode construct code associated with the tracking number."
},
"SKU": {
"type": "string",
"description": "Pricing SKU."
},
"postage": {
"type": "number",
"description": "Amount of Postage Required, does not include insurance or other extra service fees."
},
"extraServices": {
"$ref": "#/$defs/ExtraServiceResponse"
},
"serviceTypeCode": {
"type": "string",
"description": "The Service Type Code associated with the package. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).\n"
},
"zone": {
"type": "string",
"description": "Indicates the calculated zone used for pricing between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, `rateIndicator`, and `weight`."
},
"mailingDate": {
"type": "string",
"description": "The date on which the package will be mailed as provided in the request. If the time was not provided, it will be defaulted to 10:00 p.m. local time.",
"format": "date-time"
},
"commitment": {
"$ref": "#/$defs/Commitment"
},
"weightUOM": {
"type": "string",
"description": "Weight Unit of Measurement\n * lb - Pounds"
},
"weight": {
"type": "number",
"description": "The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less."
},
"dimensionalWeight": {
"type": "number",
"description": "The dimensional weight of the package, if greater than specified in weight, in ounces."
},
"fees": {
"type": "array",
"description": "Fees associated with the package.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the fee."
},
"SKU": {
"type": "string",
"description": "Pricing SKU."
},
"price": {
"type": "number",
"description": "The price for the fee.",
"format": "float"
}
},
"additionalProperties": false
}
},
"permitHolderName": {
"type": "string",
"description": "The permit holder name."
},
"inductionType": {
"type": "object",
"additionalProperties": false,
"description": "The permit holder induction type."
},
"labelBrokerID": {
"maxLength": 10,
"type": "string",
"description": "Unique Label Broker ID that can be used as an alternative to the Label Broker QR Code to retrieve the label at a Post Office. Will only be provided when an imageType of LABEL_BROKER is requested."
},
"bannerText": {
"type": "string",
"description": "Banner text printed on the label."
},
"retailDistributionCode": {
"type": "string",
"description": "Retail Description Code associated with label."
},
"returnReceiptTrackingNumber": {
"type": "string",
"description": "The human-readable version of the return Receipt tracking number.\n\n* Note: This will be included in the response when `packageOptions.returnReceiptTracking` is set to true in the request.\n"
},
"links": {
"$ref": "#/$defs/Links"
},
"warnings": {
"$ref": "#/$defs/Warnings"
}
},
"additionalProperties": true,
"description": "Label Metadata returned from label creation and label edit."
},
"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
}
},
"Phone": {
"pattern": "^\\+?[1-9][0-9]{7,14}$|^[0-9]{6,15}$",
"type": "string",
"description": "The phone number, including the country extension and area code or the local national format, with no punctuation."
},
"ReturnLabelMetadata": {
"title": "Return Label Metadata",
"description": "Return Label Metadata",
"type": "object",
"properties": {
"labelAddress": {
"$ref": "#/$defs/DomesticLabelAddress"
},
"routingInformation": {
"type": "string",
"description": "The \"420\" 3-digit GS1 Application Identifier and the 5 or 9 digit Destination ZIP Code™"
},
"trackingNumber": {
"type": "string",
"description": "The human readable version of the package tracking number"
},
"SKU": {
"type": "string",
"description": "Pricing SKU"
},
"sku": {
"type": "string",
"description": "Pricing SKU",
"deprecated": true
},
"postage": {
"type": "number",
"description": "Amount of Postage Required, does not include insurance or other extra service fees."
},
"extraServices": {
"$ref": "#/$defs/ExtraServiceResponse"
},
"serviceTypeCode": {
"type": "string",
"description": "The Service Type Code associated with the package. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes)\n"
},
"zone": {
"type": "string",
"description": "Indicates the calculated zone used for pricing between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, `rateIndicator`, and `weight`."
},
"mailingDate": {
"type": "string",
"description": "The date and time when the request was processed, with a two-hour offset applied.",
"format": "date-time"
},
"weightUOM": {
"type": "string",
"description": "Weight Unit of Measurement\n * lb - Pounds"
},
"weight": {
"type": "number",
"description": "The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less."
},
"dimensionalWeight": {
"type": "number",
"description": "The dimensional weight of package, if greater than specified in weight, in ounces."
},
"fees": {
"type": "array",
"description": "Fees associated to the package.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the fee."
},
"SKU": {
"type": "string",
"description": "Pricing SKU"
},
"price": {
"type": "number",
"description": "The price for the fee.",
"format": "float"
}
},
"additionalProperties": false
}
},
"labelBrokerID": {
"maxLength": 10,
"type": "string",
"description": "Unique Label Broker ID that can be used as an alternative to the Label Broker QR Code to retrieve the label at a Post Office. Will only be provided when an imageType of LABEL_BROKER is requested."
},
"bannerText": {
"type": "string",
"description": "Banner text printed on the label"
},
"retailDistributionCode": {
"type": "string",
"description": "Retail Description Code associated with the label"
},
"links": {
"$ref": "#/$defs/Links"
},
"warnings": {
"$ref": "#/$defs/Warnings"
}
}
},
"State": {
"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",
"description": "This is the two-character state code of the address."
},
"Warnings": {
"title": "Warnings",
"type": "array",
"description": "Warnings and additional details around the Label.",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"warningCode": {
"type": "string",
"description": "Code corresponding to the warning"
},
"warningDescription": {
"type": "string",
"description": "Warning or additional information regarding the Label."
}
},
"additionalProperties": false
}
}
}
}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-label-vendor-response"
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.