{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/usps/json-schema/usps-return-label-request-schema.json", "title": "Returns Package Request", "description": "Domestic Package Request", "x-generated": "2026-11-11", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/usps-domestic-labels-openapi.yml#/components/schemas/ReturnLabelRequest", "required": [ "fromAddress", "packageDescription", "toAddress" ], "type": "object", "properties": { "imageInfo": { "description": "Image information", "allOf": [ { "$ref": "#/$defs/ImageInfo" }, { "type": "object", "properties": { "suppressPostage": { "type": "boolean", "deprecated": true, "description": "This field has been deprecated. Postage value is not printed on Return Labels.\n", "default": true }, "suppressMailDate": { "type": "boolean", "deprecated": true, "description": "This field has been deprecated.\n\nNote:\n * Mail Date will not be printed on Return Labels without a customs form.\n * Mail Date will be printed on Domestic Customs Forms. The customs form will always display the Date of Mailing.\n * The date the label was created cannot be suppressed and will always print on the label.\n", "default": true }, "returnLabel": { "type": "boolean", "deprecated": true, "description": "This field has been deprecated. A return label cannot be generated with a return label. This field will be ignored in the request.", "default": false }, "receiptOption": { "description": "Receipt Option", "type": "string", "default": "NONE" } }, "additionalProperties": true } ] }, "toAddress": { "description": "The address where the return package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing.\n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* For return labels, the `toAddress` 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/DomesticLabelAddress" } ] }, "fromAddress": { "description": "The address where the return 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", "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" } ] }, "senderAddress": { "description": "The address of the business involved (typically the sender of the original package). The `senderAddress` can be different from the `toAddress` when the business address is not where the package is being shipped to.\n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.\n", "allOf": [ { "$ref": "#/$defs/DomesticLabelSenderAddress" } ] }, "returnAddress": { "description": "The address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label. This could be a secondary return address in case the toAddress is deemed undeliverable or returned to sender. \n\nNote:\n* The First and Last Name or Firm Name are always required.\n", "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" } ] }, "packageDescription": { "description": "package description", "oneOf": [ { "$ref": "#/$defs/ReturnsPackageDescription" }, { "$ref": "#/$defs/ReturnsPackageDescriptionWithoutRateIndicator" } ] }, "customsForm": { "$ref": "#/$defs/DomesticReturnsCustomsForm" } }, "additionalProperties": false, "$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" }, "BaseReturnsPackageDescription": { "title": "Returns Package", "allOf": [ { "$ref": "#/$defs/PackageDescription" }, { "required": [ "height", "length", "mailClass", "processingCategory", "weight", "width" ], "type": "object", "properties": { "mailClass": { "type": "string", "description": "The mail service requested.\n\nNote:\n- `FIRST-CLASS_PACKAGE_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`\n- `GROUND_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`\n", "enum": [ "FIRST-CLASS_PACKAGE_RETURN_SERVICE", "GROUND_RETURN_SERVICE", "PRIORITY_MAIL_EXPRESS_RETURN_SERVICE", "PRIORITY_MAIL_RETURN_SERVICE", "USPS_GROUND_ADVANTAGE_RETURN_SERVICE" ] }, "processingCategory": { "type": "string", "description": "Value designates if the shipment is `MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`.\n\nNote:\n* The processing category `LETTERS` is only valid when the mail class is `PRIORITY_MAIL_RETURN_SERVICE` or `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` for returns shipments.\n* The processing category `FLATS` is not valid for mail class `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`.\n* `IRREGULAR` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.\n* `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.", "enum": [ "LETTERS", "FLATS", "MACHINABLE", "IRREGULAR", "NON_MACHINABLE", "NONSTANDARD" ] }, "customerReference": { "maxItems": 4, "type": "array", "description": "Used for shippers to print a value on a label and included in the Shipping Services Files.", "items": { "$ref": "#/$defs/DomesticCustomerReference" } }, "extraServices": { "maxItems": 5, "minItems": 0, "type": "array", "description": "Extra Service Code requested.\n* 365 - Global Direct Entry\n* 415 - USPS Label Delivery\n* 480 - Tracking Plus 6 Months\n* 481 - Tracking Plus 1 Year\n* 482 - Tracking Plus 3 Years\n* 483 - Tracking Plus 5 Years\n* 484 - Tracking Plus 7 Years\n* 485 - Tracking Plus 10 Years\n* 486 - Tracking Plus Signature 3 Years\n* 487 - Tracking Plus Signature 5 Years\n* 488 - Tracking Plus Signature 7 Years\n* 489 - Tracking Plus Signature 10 Years\n* 810 - HAZMAT Air Eligible Ethanol Package\n* 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package\n* 812 - HAZMAT Class 3 – Flammable Liquid Package\n* 813 - HAZMAT Class 7 - Radioactive Materials Package\n* 814 - HAZMAT Class 8 - Corrosive Materials Package\n* 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package\n* 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package\n* 817 - HAZMAT Class 9 - Lithium Battery - Returns Package\n* 818 - HAZMAT Class 9 - Lithium batteries, marked package\n* 819 - HAZMAT Class 9 - Dry Ice Package\n* 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n* 821 - HAZMAT Class 9 - Magnetized Materials Package\n* 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package\n* 823 - HAZMAT Division 5.1 - Oxidizers Package\n* 824 - HAZMAT Division 5.2 - Organic Peroxides Package\n* 825 - HAZMAT Division 6.1 – Toxic Materials Package\n* 826 - HAZMAT Division 6.2 – Infectious Substances Package\n* 827 - HAZMAT Excepted Quantity Provision Package\n* 828 - HAZMAT Ground Only\n* 829 - HAZMAT ID8000 Consumer Commodity Package\n* 830 - HAZMAT Lighters Package\n* 831 - HAZMAT LTD QTY Ground Package\n* 832 - HAZMAT Small Quantity Provision Package\n* 857 - Hazardous Material\n* 910 - Certified Mail\n* 911 - Certified Mail Restricted Delivery\n* 912 - Certified Mail Adult Signature Required\n* 913 - Certified Mail Adult Signature Restricted Delivery\n* 920 - USPS Tracking\n* 921 - Signature Confirmation\n* 922 - Adult Signature Required 21 or Over\n* 923 - Adult Signature Restricted Delivery 21 or Over\n* 924 - Signature Confirmation Restricted Delivery\n* 925 - Priority Mail Express Merchandise Insurance\n* 930 - Insurance <= $500\n* 931 - Insurance > $500\n* 934 - Insurance Restricted Delivery\n* 955 - Return Receipt\n* 957 - Return Receipt Electronic\n* 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)\n* 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)\n* 991 - Sunday Delivery\n\nNote:\n * When the extra service code \"930\" is provided in the request, if the item value is over $500, \"930\" will automatically be replaced with \"931\" - Insurance (Greater than $500).\n * USPS Label Delivery (Extra Service Code \"415\"): When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page. This service is not available at all locations.\n * Some service codes require a combination with extra services such as \"955\" and \"957\". For all valid combinations, visit [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).", "items": { "$ref": "#/$defs/ExtraService" } }, "packageOptions": { "$ref": "#/$defs/DomesticPackageReturnOptions" }, "destinationEntryFacilityAddress": { "deprecated": true, "description": "Destination entry facility address", "allOf": [ { "$ref": "#/$defs/DomesticAddress" } ] }, "inductionZIPCode": { "$ref": "#/$defs/InductionZIPCode" }, "shipperVisibilityMethod": { "type": "string", "description": "When generating labels for a third party shipper the label provider must capture and provide contact details of the individual or entity to whom they provide the label. For return labels, there is one method for reporting shipper information to USPS:\n\n1. An alternative method allows for the label provider to assign a unique alphanumeric value known as a `platformUserId` to each shipper and to report the `platformUserId` together with the required shipper contact details. When using this method the shipper contact details are required in the `senderAddress` object (including `streetAddress`, `city`, `state`, `ZIPCode`, `phone`, `email`, `platformUserId` & `firstName`/`lastName` or `firm`) and this field should be populated with 'SENDER_INFORMATION'.\n", "enum": [ "SENDER_INFORMATION" ] } }, "additionalProperties": true, "description": "Details on the package being returned." } ] }, "Container": { "title": "Container", "required": [ "containerID", "sortType" ], "type": "object", "properties": { "containerID": { "maxLength": 34, "type": "string", "description": "Unique identifier for a container." }, "sortType": { "type": "string", "description": "Sort Types requested.", "enum": [ "TRUCK_BEDLOAD", "OPEN_DISTRIBUTION_FULL_POSTAL_PAKS", "OPEN_DISTRIBUTE_EMM_TRAY_BOX", "OPEN_DISTRIBUTE_FULL_TRAY_BOX", "OPEN_DISTRIBUTE_HALF_TRAY_BOX", "OPEN_DISTRIBUTE_HALF_POSTAL_PAKS", "OPEN_DISTRIBUTE_PALLET", "OPEN_DISTRIBUTE_FLAT_TUB_TRAY_BOX", "PALLET", "RECEPTACLE", "SACK" ] } }, "additionalProperties": false, "description": "containers" }, "CustomerReference": { "title": "Customer Reference", "description": "Customer Reference", "type": "object", "properties": { "referenceNumber": { "maxLength": 30, "minLength": 1, "type": "string", "description": "A user-assigned number for internal use, such as Order, Invoice, Customer, or Return Merchandise Authorization Numbers. \n\nNote:\n* Domestic outbound label and return label with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` will display the entire value.\n* Return label with `labelType` of `4X6LABEL` with `brandingImageFormat` of `TWO_SQUARES` will show the first 25 characters.\n* These values will also be included in the Shipping Services File.\n" } }, "additionalProperties": true }, "CustomsForm": { "title": "Customs Form", "type": "object", "properties": { "contentComments": { "maxLength": 25, "type": "string", "description": "Required when customContentType is OTHER." }, "restrictionType": { "type": "string", "description": "Restriction Types\n * QUARANTINE\n * SANITARY_INSPECTION\n * PHYTOSANITARY_INSPECTION\n * OTHER", "enum": [ "QUARANTINE", "SANITARY_INSPECTION", "PHYTOSANITARY_INSPECTION", "OTHER" ] }, "restrictionComments": { "maxLength": 25, "type": "string", "description": "Restriction Comments. Required when `restrictionType`=`OTHER`." }, "AESITN": { "maxLength": 35, "minLength": 1, "type": "string", "description": "AES/ITN Exemption should be populated with the electronic export internal transaction number (if required), or the appropriate Exemption/Exclusion Legend.\n\n* **AES - Automated Export System / ITN - Internal Transaction Number**\\\n The [internal transaction number (ITN)](https://pe.usps.com/text/imm/immc5_010.htm) is a 14-digit number that corresponds to an export transaction in the Automated Export System. It serves as proof that an exporter met his or her legal obligation to inform the U.S. government about the details of an export shipment.\n* **EEL- Exemptions, Exclusions, Legend**\\\n An [AES exemption](https://pe.usps.com/text/imm/immc5_012.htm) is an instance in which you would not have to file in AES to get the 14-digit ITN. Instead of the ITN, you would enter the exemption’s section in the U.S. Foreign Trade Regulations on the export documentation where you would otherwise put the ITN.\n\nSample - `NO EEI 30.37(a)`: Shipments valued at $2,500 or less.\n" }, "invoiceNumber": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Invoice Number" }, "licenseNumber": { "maxLength": 16, "minLength": 1, "type": "string", "description": "License Number" }, "certificateNumber": { "maxLength": 12, "minLength": 1, "type": "string", "description": "Certificate Number" } }, "additionalProperties": true, "description": "Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).\nRequired only if a customs form is required based on Customs Content Type and Weight.\n\nNote:\n - Mail addressed to military and diplomatic post offices overseas is subject to certain conditions or restrictions of mailing regarding content, preparation, and handling. The APO/FPO/DPO table may be found on the most recent [postal bulletin](https://about.usps.com/resources/postal-bulletin.htm) found under `Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`" }, "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 } ] }, "DomesticCustomerReference": { "title": "Customer Reference", "allOf": [ { "$ref": "#/$defs/CustomerReference" }, { "type": "object", "properties": { "printReferenceNumber": { "type": "boolean", "default": false, "description": "Indicates whether or not to print the customer reference number on the label in the Additional Information and User Segment.\n\nNote: \n- Customer Reference numbers are not displayed on label types `2X7LABEL` or `4X4LABEL`.\n- Customer Reference numbers are not displayed with Customs Forms.\n" } }, "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 } ] }, "DomesticLabelSenderAddress": { "title": "Domestic Label Sender Address", "required": [ "ZIPCode", "city", "state", "streetAddress" ], "type": "object", "additionalProperties": true, "description": "The address of the business involved. The senderAddress can be different from the fromAddress when the business address is not where the package is being shipped from.\n\nNotes:\n- The First and Last Name or Firm Name are always required.\n- `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.", "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" }, { "$ref": "#/$defs/Addressee" }, { "type": "object", "properties": { "platformUserId": { "maxLength": 30, "type": "string", "description": "This is a third-party unique identifier for the sender used for correlation purposes." } }, "additionalProperties": true } ] }, "DomesticPackageReturnOptions": { "title": "Package Options", "description": "Options added to packages that are less frequently used", "allOf": [ { "$ref": "#/$defs/PackageOptions" }, { "type": "object", "properties": { "immediateManifest": { "type": "boolean", "default": false, "description": "Setting this field to `true` will send electronic data to Postal systems within 15 minutes of label creation.\n" }, "redirectAddress": { "deprecated": true, "description": "**Deprecated**: Use the `ancillaryServiceEndorsements` field instead.\n\nAddress to send the package to if it is not deliverable.\n\nNote:\n - Required when `nonDeliveryOption` is a value of `REDIRECT`.\n", "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" } ] }, "contentType": { "type": "string", "description": "The type of contents in the package.\n* HAZMAT\n* CREMATED_REMAINS\n* BEES\n* DAY_OLD_POULTRY\n* ADULT_BIRDS\n* OTHER_LIVES\n* PERISHABLE\n* PHARMACEUTICALS\n* MEDICAL_SUPPLIES\n* FRUITS\n* VEGETABLES\n* LIVE_PLANTS\n\nNote:\n* `CREMATED_REMAINS` is currently only eligible for the `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` mail class. Please refer to [Publication 139](https://about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.\n* `HAZMAT` domestic labels with destination addresses to APO/FPO/DPO and PTFAS (except Puerto Rico) will not contain any Hazmat markings/indicators, including service type codes in the IMpb. When users indicate a shipment contains hazmat materials in the API request (via content type and/or extra services), that information will still be captured and sent in the shipping services file. For more information, please review the [USPS APIs release notes](https://postalpro.usps.gov/usps-apis-releases)\n* For guidelines on shipping Hazardous Material, please refer to [Publication 52](https://pe.usps.com/text/pub52/welcome.htm).\n", "enum": [ "HAZMAT", "CREMATED_REMAINS", "BEES", "DAY_OLD_POULTRY", "ADULT_BIRDS", "OTHER_LIVES", "PERISHABLE", "PHARMACEUTICALS", "MEDICAL_SUPPLIES", "FRUITS", "VEGETABLES", "LIVE_PLANTS" ] }, "generateGXEvent": { "type": "boolean", "description": "Provides the option for a user to not create a \"GX\" event for the package. By default, a GX event will be created.", "default": true }, "containers": { "maxItems": 3, "type": "array", "description": "containers", "items": { "$ref": "#/$defs/Container" } }, "ancillaryServiceEndorsements": { "type": "string", "description": "Endorsements allow the sender to obtain the addressee's new (forwarding) address (provided the appropriate endorsement is used \nand if the addressee filed a Change-of-Address Order with the Postal Service) or the reason for non-delivery. \nFor more information see [PostalPro](https://postalpro.usps.com/address-quality/ancillary-service-endorsements)\n", "deprecated": true, "enum": [ "CHANGE_SERVICE_REQUESTED", "ADDRESS_SERVICE_REQUESTED", "ELECTRONIC_SERVICE_REQUESTED", "RETURN_SERVICE_REQUESTED", "TEMP_RETURN_SERVICE_REQUESTED", "FORWARDING_SERVICE_REQUESTED" ] } }, "additionalProperties": true } ] }, "DomesticReturnsCustomsForm": { "title": "Customs Form", "description": "Domestic Returns Custom Form", "allOf": [ { "$ref": "#/$defs/CustomsForm" }, { "type": "object", "properties": { "customsContentType": { "type": "string", "description": "Specifies the content of the package or envelope.\n * MERCHANDISE\n * GIFT\n * DOCUMENT\n * COMMERCIAL_SAMPLE\n * RETURNED_GOODS\n * OTHER\n * HUMANITARIAN_DONATIONS\n * DANGEROUS_GOODS\n", "enum": [ "MERCHANDISE", "GIFT", "DOCUMENT", "COMMERCIAL_SAMPLE", "RETURNED_GOODS", "OTHER", "HUMANITARIAN_DONATIONS", "DANGEROUS_GOODS" ] }, "importersReference": { "maxLength": 40, "type": "string", "description": "Importers Reference. The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax." }, "importersContact": { "maxLength": 30, "type": "string", "description": "Importers Contact. Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery." }, "exportersReference": { "maxLength": 40, "type": "string", "description": "Exporters Reference. The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax." }, "exportersContact": { "maxLength": 30, "type": "string", "description": "Exporters Contact. Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery." }, "contents": { "minItems": 1, "maxItems": 30, "type": "array", "description": "Details of the contents of the package. The first five items will print on the label of the customs form, and the rest will print on a separate continuation page.", "items": { "$ref": "#/$defs/ShippingContents" } } }, "additionalProperties": true, "description": "Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).\nRequired only if a customs form is required based on Customs Content Type and Weight.\n\nNote:\n * A domestic return label with a customs form cannot have an extra service of \"USPS Label Delivery\" (415)." } ] }, "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" }, "ExtraService": { "title": "Extra Service Codes", "type": "integer", "description": "Extra Service Code (ESC) requested.\n\nExtra Service Code list:\n * 365 - Global Direct Entry\n * 415 - USPS Label Delivery\n * 480 - Tracking Plus 6 Months\n * 481 - Tracking Plus 1 Year\n * 482 - Tracking Plus 3 Years\n * 483 - Tracking Plus 5 Years\n * 484 - Tracking Plus 7 Years\n * 485 - Tracking Plus 10 Years\n * 486 - Tracking Plus Signature 3 Years\n * 487 - Tracking Plus Signature 5 Years\n * 488 - Tracking Plus Signature 7 Years\n * 489 - Tracking Plus Signature 10 Years\n * 810 - HAZMAT Air Eligible Ethanol Package\n * 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package\n * 812 - HAZMAT Class 3 – Flammable Liquid Package\n * 813 - HAZMAT Class 7 - Radioactive Materials Package\n * 814 - HAZMAT Class 8 - Corrosive Materials Package\n * 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package\n * 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package\n * 817 - HAZMAT Class 9 - Lithium Battery - Returns Package\n * 818 - HAZMAT Class 9 - Lithium batteries, marked package\n * 819 - HAZMAT Class 9 - Dry Ice Package\n * 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n * 821 - HAZMAT Class 9 - Magnetized Materials Package\n * 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package\n * 823 - HAZMAT Division 5.1 - Oxidizers Package\n * 824 - HAZMAT Division 5.2 - Organic Peroxides Package\n * 825 - HAZMAT Division 6.1 – Toxic Materials Package\n * 826 - HAZMAT Division 6.2 – Infectious Substances Package\n * 827 - HAZMAT Excepted Quantity Provision Package\n * 828 - HAZMAT Ground Only\n * 829 - HAZMAT ID8000 Consumer Commodity Package\n * 830 - HAZMAT Lighters Package\n * 831 - HAZMAT LTD QTY Ground Package\n * 832 - HAZMAT Small Quantity Provision Package\n * 857 - Hazardous Material\n * 910 - Certified Mail\n * 911 - Certified Mail Restricted Delivery\n * 912 - Certified Mail Adult Signature Required\n * 913 - Certified Mail Adult Signature Restricted Delivery\n * 920 - USPS Tracking\n * 921 - Signature Confirmation\n * 922 - Adult Signature Required 21 or Over\n * 923 - Adult Signature Restricted Delivery 21 or Over\n * 924 - Signature Confirmation Restricted Delivery\n * 925 - Priority Mail Express Merchandise Insurance\n * 930 - Insurance <= $500\n * 931 - Insurance > $500\n * 934 - Insurance Restricted Delivery\n * 955 - Return Receipt\n * 957 - Return Receipt Electronic\n * 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)\n * 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)\n * 991 - Sunday Delivery\n \n Note:\n - Extra Service Code \"415 - USPS Label Delivery\": When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page.\n", "enum": [ 365, 415, 480, 481, 482, 483, 484, 485, 486, 487, 488, 489, 810, 811, 812, 813, 814, 815, 816, 817, 818, 819, 820, 821, 822, 823, 824, 825, 826, 827, 828, 829, 830, 831, 832, 857, 910, 911, 912, 913, 920, 921, 922, 923, 924, 925, 930, 931, 934, 955, 957, 981, 986, 991 ] }, "ImageInfo": { "title": "Image Info", "type": "object", "properties": { "imageType": { "type": "string", "description": "The type of label image requested. If omitted then the default image type is PDF.\n* `PDF`\n* `TIFF`\n* `JPG`\n* `PNG`\n* `GIF`\n* `SVG`\n* `ZPL203DPI`\n* `ZPL300DPI`\n* `EPL300DPI`\n* `LABEL_BROKER` - Request a USPS QR code to allow your customers with no access to a printer to print at participating Post Office Locations. All USPS API users and third-party integrators utilizing QR codes are subject to the [Label Broker terms and conditions](https://www.usps.com/terms-conditions/label-broker.htm). For more information please see the Label Broker guide available on [GitHub](https://github.com/USPS/api-examples/blob/main/USPS%20APIs%20Domestic%20Labels%20API%20Documentation_2023_0901%20Published.pdf) (Note: Only supports labelType of `4X6LABEL` or `6X4LABEL` and receiptOption of `NONE`). A USPS Label Broker QR code image will be returned in the API response instead of a label image.\n* `NONE`\n\nNote:\n- Labels with customs forms only support formats of `PDF`, `TIFF`, `ZPL203DPI`, `ZPL300DPI`, `LABEL_BROKER`, and `NONE`.\n- Including Extra Service Code `415 - USPS Label Delivery` returns no images and is equivalent to requesting `NONE`.\n- `EPL300DPI` is not supported for Return Labels.\n- When the `imageType` is set to `LABEL_BROKER`, the QR code's embedded URL will be returned in the `links` array of the response.\n", "default": "PDF", "enum": [ "PDF", "TIFF", "JPG", "PNG", "GIF", "SVG", "ZPL203DPI", "ZPL300DPI", "EPL300DPI", "LABEL_BROKER", "NONE" ] }, "labelType": { "type": "string", "description": "Ability to select the label image size. If omitted then the default label size is `4X6LABEL`.\n\nNote:\n * Currently, customs forms only support `4X6LABEL`.\n * The `labelType` of `2X7LABEL` is not supported with the `imageType` of `ZPL203DPI` or `ZPL300DPI`.\n * The `labelType` of `4X6LABEL` is the only supported format with the `imageType` of `EPL300DPI`.\n", "default": "4X6LABEL", "enum": [ "4X4LABEL", "4X5LABEL", "4X6LABEL", "6X4LABEL", "2X7LABEL" ] }, "shipInfo": { "type": "boolean", "description": "indicates if revenue protection information is printed on the label. (true or false)", "deprecated": true }, "receiptOption": { "type": "string", "description": "Label & Receipt print out options: Enter `SAME_PAGE` to print the Label and the Receipt on a single page. Enter `SEPARATE_PAGE` to print the Label and the Receipt on separate pages. Enter `NONE` to print the Label only and no Receipt.\n\nNote:\n * The `labelType` of `4X4LABEL` or `6X4LABEL` with the image `imageType` of `ZPL203DPI` or `ZPL300DPI` does not support a `receiptOption` of `SEPARATE_PAGE`.\n * When `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`, a `receiptOption` of `SAME_PAGE` is not supported.\n * When `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI` and `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", "default": "SAME_PAGE", "enum": [ "SAME_PAGE", "SEPARATE_PAGE", "NONE" ] }, "brandingImageFormat": { "type": "string", "description": "The format of label branding images to be shown on the generated label image.\n\nNote:\n* Label branding images will not be shown on labels with customs forms.\n* Label branding images are not currently supported with an `imageType` of `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`.\n* Label branding images are not currently supported with a `labelType` of `4X4LABEL`.\n* When a `brandingImageFormat` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.\n* When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference #3-#4 cannot be provided since they will not be shown.\n* When a `brandingImageFormat` of `ONE_SQUARE` or `TWO_SQUARES` is provided, Customer Reference numbers will be shifted to the right to accommodate the image.\n* When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference numbers, package number, and total packages will not be displayed on the label.\n* A `brandingImageFormat` of `ONE_SQUARE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, `6X4LABEL`, and `2X7LABEL` for both outbound and return labels.\n* A `brandingImageFormat` of `TWO_SQUARES` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for both outbound and return labels.\n* A `brandingImageFormat` of `RECTANGLE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for outbound labels and `4X5LABEL` and `6X4LABEL` for return labels.\n", "default": "NONE", "enum": [ "ONE_SQUARE", "TWO_SQUARES", "RECTANGLE", "NONE" ] }, "brandingImageUUIDs": { "type": "array", "maxItems": 2, "minItems": 0, "default": [], "description": "The UUIDs associated with custom images uploaded in the Logo Branding endpoint: /branding\n\nNote:\n* These UUIDs must have been created with the same Payment Authorization Label Owner CRID in use when creating the label\n* When using `ONE_SQUARE` or `RECTANGLE` the brandingImageUUIDs list should include only one imageUUID string.\n* When using `TWO_SQUARES` the brandingImageUUIDs list should include only two imageUUID strings.\n", "items": { "maxLength": 36, "minLength": 36, "pattern": "[A-Fa-f0-9]{8}-([A-Fa-f0-9]{4}-){3}[A-Fa-f0-9]{12}", "type": "string" } }, "includeLabelBrokerPDF": { "type": "boolean", "default": false, "description": "Applicable only when `imageType` is `LABEL_BROKER`. When `includeLabelBrokerPDF` is `true`, two label images will be returned in the multi-part and vendor response as `labelBrokerQR` and `labelImage`. `labelBrokerQR` will contain the base64 PNG of the Label Broker QR Code and `labelImage` will contain the base64 PDF of the Label stored in Label Broker. When `includeLabelBrokerPDF` is `false`, one image will be returned in the multi-part and vendor response as `labelImage` as the base64 PNG of the Label Broker QR Code.\n" }, "addZPLComments": { "type": "boolean", "default": false, "deprecated": true, "description": "Note: This field has been deprecated in favor of `addImageComments`.\n\nApplicable only when `imageType` is `ZPL203DPI` or `ZPL300DPI`. When `addZPLComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label. When `addZPLComments` is `false`, no comments will be included in the ZPL text response. This will be ignored for any other `imageType`.\n\nExample of a ZPL comment: \n`^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`\n" }, "addImageComments": { "type": "boolean", "default": false, "description": "Applicable only when `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`. When `addImageComments` is `true`, comments will be visible within the ZPL or EPL text response to the user to denote different sections of their label. When `addImageComments` is `false`, no comments will be included in the ZPL or EPL text response. This will be ignored for any other `imageType`.\nExample of a ZPL comment:\n`^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`\n" } }, "additionalProperties": true, "description": "Additional details used to determine how to generate the label image." }, "InductionZIPCode": { "pattern": "^\\d{5}$", "type": "string", "description": "The 5-Digit ZIP Code representing the location where the package is being inducted (i.e. dropped off) into the mailstream. When provided, this ZIP Code will be used for pricing instead of `fromAddress.ZIPCode`." }, "PackageDescription": { "title": "Package Description", "type": "object", "properties": { "weightUOM": { "type": "string", "description": "Weight Unit of Measurement\n * lb - Pounds", "default": "lb", "enum": [ "lb" ] }, "weight": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The package weight, in weightUOM (Unit Of Measure). Items must weigh 70 pounds (1120 ounces) or less." }, "dimensionsUOM": { "type": "string", "description": "Dimensions unit of measure\n* in - Inches\n", "default": "in", "enum": [ "in" ] }, "length": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The length of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages." }, "height": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The height of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages." }, "width": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The width of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "girth": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The girth of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "hasNonstandardCharacteristics": { "default": false, "type": "boolean", "description": "Package is nonstandard. Nonstandard packages include cylindrical tubes and rolls, certain high-density items, cartons containing more than 24 ounces of liquids in one or more glass containers, cartons containing 1 gallon or more of liquid in metal or plastic containers, and items in [201.7.6.2](https://pe.usps.com/text/dmm300/201.htm#7.6.2)." } }, "additionalProperties": true, "description": "Package Definitions" }, "PackageOptions": { "title": "Package Options", "type": "object", "properties": { "packageValue": { "minimum": 0, "type": "number", "description": "The merchandise value of the package, in US dollars. Used as the declared value for Insurance and for fee calculation when provided.\n\n Note:\n * `packageValue` is required when `extraServices` includes `930` or `931`.\n" }, "nonDeliveryOption": { "type": "string", "description": "Requested action in the case a package is undeliverable:\n - `RETURN` for package to be returned to `fromAddress`.\n - `REDIRECT` to return package to address specified in the `redirectAddress`.\n - `ABANDON` to dispose of undeliverable package\n\nNote:\n * `REDIRECT` and `ABANDON` will not impact the domestic package endpoint. Please use ancillary service endorsements instead.\n * An address must be provided in `redirectAddress` when a value of `REDIRECT` is provided.", "enum": [ "RETURN", "REDIRECT", "ABANDON" ] }, "omas": { "type": "object", "description": "Fields specific to Official Mail Accounting System (OMAS). Used for Federal Agencies.", "properties": { "chargebackCode": { "type": "string", "maxLength": 6, "pattern": "^[A-Za-z0-9]{1,6}$", "description": "Code used with OMAS transactions." } } } }, "additionalProperties": true }, "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." }, "ReturnsPackageDescription": { "title": "Returns Package Description with Rate Indicators", "additionalProperties": true, "allOf": [ { "$ref": "#/$defs/BaseReturnsPackageDescription" }, { "required": [ "rateIndicator" ], "type": "object", "properties": { "rateIndicator": { "type": "string", "description": "Use to specify USPS containers/packaging or container attributes that may affect postage.\n\nNote:\n * Effective 07/12/2026: Rate indicators `Q6`, `Q7`, `Q8`, `Q9`, and `Q0` are no longer supported. The dimensions for Cubic Soft Pack tiers `P5`, `P6`, `P7`, `P8`, and `P9` will be updated to include the dimensions for Tiers 6-10. For updated tiers and more information, please view the [Postal Bulletin](https://about.usps.com/postal-bulletin/2026/pb22705/html/updt_001.htm).\n \nRate indicator list:\n * CP - Cubic Parcel\n * DN - Dimensional Nonrectangular\n * DR - Dimensional Rectangular\n * E4 - Priority Mail Express Flat Rate Envelope - Post Office To Addressee\n * E6 - Priority Mail Express Legal Flat Rate Envelope\n * FA - Legal Flat Rate Envelope\n * FB - Medium Flat Rate Box/Large Flat Rate Bag\n * FE - Flat Rate Envelope\n * FP - Padded Flat Rate Envelope\n * FS - Small Flat Rate Box\n * OS - Oversized\n * P5 - Cubic Soft Pack Tier 1\n * P6 - Cubic Soft Pack Tier 2\n * P7 - Cubic Soft Pack Tier 3\n * P8 - Cubic Soft Pack Tier 4\n * P9 - Cubic Soft Pack Tier 5\n * Q6 - Cubic Soft Pack Tier 6\n * Q7 - Cubic Soft Pack Tier 7\n * Q8 - Cubic Soft Pack Tier 8\n * Q9 - Cubic Soft Pack Tier 9\n * Q0 - Cubic Soft Pack Tier 10\n * PA - Priority Mail Express Single Piece\n * PL - Large Flat Rate Box\n * PM - Large Flat Rate Box APO/FPO/DPO\n * SP - Single Piece\n", "default": "SP", "enum": [ "CP", "DN", "DR", "E4", "E6", "FA", "FB", "FE", "FP", "FS", "OS", "P5", "P6", "P7", "P8", "P9", "PA", "PL", "PM", "Q6", "Q7", "Q8", "Q9", "Q0", "SP" ] } }, "additionalProperties": true } ] }, "ReturnsPackageDescriptionWithoutRateIndicator": { "title": "Returns Package Description without Rate Indicators", "additionalProperties": true, "allOf": [ { "$ref": "#/$defs/BaseReturnsPackageDescription" }, { "required": [ "packagingType", "shape" ], "type": "object", "properties": { "shape": { "type": "string", "description": "The shape of the package", "enum": [ "RECTANGULAR", "NON_RECTANGULAR" ] }, "packagingType": { "type": "string", "description": "USPS packaging or container attributes that may affect postage. If the packaging is customer provided, use `VARIABLE`.", "enum": [ "VARIABLE", "5-DIGIT_PRESORT", "BASIC_PRESORT", "FLAT_RATE_ENVELOPE", "LEGAL_FLAT_RATE_ENVELOPE", "PADDED_FLAT_RATE_ENVELOPE", "SM_FLAT_RATE_BOX", "MD_FLAT_RATE_BOX", "LG_FLAT_RATE_BOX", "CUBIC_PARCELS", "CUBIC_SOFT_PACK" ] } }, "additionalProperties": true } ] }, "ShippingContents": { "title": "Customs Form Package Contents", "type": "object", "properties": { "itemDescription": { "maxLength": 30, "minLength": 1, "type": "string", "description": "Description of the item. It is important to note that the following descriptions, regardless of case sensitivity, are not considered valid: None, Not Applicable, N/A, Null, Gift, and Merchandise.\n" }, "itemQuantity": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "Quantity of the item. Integer value required." }, "itemValue": { "maximum": 999999.99, "minimum": 0.01, "type": "number", "description": "Value of the individual item in USD.\n\nNote:\n* This field has been deprecated in favor of `itemTotalValue` and will be removed in a future release. Please transition to using `itemTotalValue`.\n", "deprecated": true }, "itemTotalValue": { "maximum": 999999.99, "minimum": 0.01, "type": "number", "description": "The total item value, in USD, of the items matching the `itemDescription`.\n" }, "weightUOM": { "type": "string", "description": "Weight Unit of Measurement\n * lb - Pounds", "default": "lb", "enum": [ "lb" ] }, "itemWeight": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "Provide the weight in `weightUOM` for the individual item listed with `itemDescription`.\n\nNote:\n* This field has been deprecated in favor of `itemTotalWeight` and will be removed in a future release. Please transition to using `itemTotalWeight`.\n", "deprecated": true }, "itemTotalWeight": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "Provide the total weight in `weightUOM` for the all items matching the `itemDescription`.\n" }, "HSTariffNumber": { "maxLength": 14, "minLength": 6, "type": "string", "description": "For commercial items only. The HS tariff number is based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. \nProviding this value is strongly recommended for faster processing. If not supplied, USPS will attempt to look up the HS tariff number, which may result in longer response times.\nThe value should follow the pattern: `^\\.*(?:[A-Za-z\\d]\\.*){6,14}$`.\nFor more information, see: [https://hts.usitc.gov/current](https://hts.usitc.gov/current).\n" }, "countryofOrigin": { "pattern": "[A-Z]{2}", "type": "string", "description": "2 digit Alpha Country Code defined by ISO is required for international address." }, "itemCategory": { "type": "string", "description": "Category of the item being shipped." }, "itemSubcategory": { "type": "string", "description": "Subcategory of the item being shipped." } }, "additionalProperties": true, "description": "Required repeating up to 30 times if generating an Integrated Customs Form, otherwise not required." }, "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." } } }