{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/usps/json-schema/usps-label-request-schema.json", "title": "Domestic Package Request", "description": "Destination address of the recipient. Used in pricing as the destination ZIP Code™.", "x-generated": "2026-11-11", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/usps-domestic-labels-openapi.yml#/components/schemas/LabelRequest", "required": [ "fromAddress", "packageDescription", "toAddress" ], "type": "object", "properties": { "imageInfo": { "description": "Image Information", "allOf": [ { "$ref": "#/$defs/ImageInfo" }, { "type": "object", "additionalProperties": true, "properties": { "suppressPostage": { "type": "boolean", "description": "Indicates if postage is printed on the label. If omitted then the request will be defaulted to true.\n", "default": true }, "suppressMailDate": { "type": "boolean", "description": "Indicates if the `mailingDate` is printed on the label. If omitted then the value will default to true.\n\nNote:\n * Mail Date cannot be suppressed 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", "description": "Indicates if a pay on use returns label is requested along with the outbound label. If omitted then the request will be defaulted to false.\n\nThe mail class of the generated return label will be based off of the mail class provided in `packageDescription.mailClass`.\n* Priority Mail Express Return Service label will be generated with `packageDescription.mailClass` of `PRIORITY_MAIL_EXPRESS`.\n* Priority Mail Return Service label will be generated with `packageDescription.mailClass` of `PRIORITY_MAIL`.\n* USPS Ground Advantage Return Service label will be generated with all other `packageDescription.mailClass` enumerations.\n\nNote:\n * An `imageType` value of `LABEL_BROKER` is currently not supported when `returnLabel` is set to true.\n * A `packageDescription.mailClass` value of `USPS_CONNECT_MAIL` is currently not supported when `returnLabel` is set to true.\n * `returnLabel` cannot be set to `true` when generating customs forms.\n * `returnLabel` is not available when Extra Service Code `415 - USPS Label Delivery` is used.", "default": false }, "packageNumber": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "The package number in a series such as 1 of 3, 2 of 3, etc. If `totalPackages` is populated then `packageNumber` is required. `packageNumber` must be less than or equal to `totalPackages`. This feature is not supported on the 2x7 or 4x4 label format.\n\nNote:\n* When `packageNumber` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label." }, "totalPackages": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "The total number of packages in a series such as 999. If packageNumber is populated then totalPackages is required. totalPackages must be greater than or equal to packageNumber. This feature is not supported by the 2x7 or 4x4 label format." } } } ], "additionalProperties": true }, "toAddress": { "$ref": "#/$defs/DomesticLabelToAddress" }, "fromAddress": { "$ref": "#/$defs/DomesticLabelAddress" }, "senderAddress": { "$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.\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/DomesticPackageDescription" }, { "$ref": "#/$defs/DomesticPackageDescriptionWithoutRateIndicator" } ] }, "customsForm": { "$ref": "#/$defs/DomesticCustomsForm" } }, "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" }, "BaseDomesticPackageDescription": { "title": "Package Description", "additionalProperties": true, "allOf": [ { "$ref": "#/$defs/PackageDescription" }, { "required": [ "destinationEntryFacilityType", "height", "length", "mailClass", "mailingDate", "processingCategory", "weight", "width" ], "type": "object", "properties": { "mailClass": { "type": "string", "description": "The mail service requested.\n\nNote:\n- `PARCEL_SELECT` with a `destinationEntryFacilityType` of `NONE` will convert to `USPS_GROUND_ADVANTAGE`.\n- `PARCEL_SELECT_LIGHTWEIGHT` is deprecated and will convert to `PARCEL_SELECT`.\n- `FIRST-CLASS_PACKAGE_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE`.\n- Certain mail classes, such as `MEDIA_MAIL`, `BOUND_PRINTED_MATTER`, and `LIBRARY_MAIL`, have eligibility rules on what can be mailed using that service. For more details on these mail classes, please visit [What are Package Services?](https://faq.usps.com/s/article/What-are-Package-Services).\n- The Heavy Printed Matter product is supported with `MARKETING_MAIL_PARCELS`. To create Heavy Printed Matter labels, the `rateIndicator` should be set to `PR` or `NP` for Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter or to `PN` or `NN` for Nonprofit Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter respectively.\n", "enum": [ "PARCEL_SELECT", "PARCEL_SELECT_LIGHTWEIGHT", "USPS_CONNECT_LOCAL", "USPS_CONNECT_REGIONAL", "USPS_CONNECT_MAIL", "USPS_GROUND_ADVANTAGE", "PRIORITY_MAIL_EXPRESS", "PRIORITY_MAIL", "FIRST-CLASS_PACKAGE_SERVICE", "LIBRARY_MAIL", "MEDIA_MAIL", "BOUND_PRINTED_MATTER", "MARKETING_MAIL_PARCELS" ] }, "processingCategory": { "type": "string", "description": "Value designates if shipment is `MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`.\n\nNote:\n* When requesting the mail class `USPS_CONNECT_MAIL`, users are required to use a processing category of `FLATS`.\n* The processing category `LETTERS` is only valid for mail classes `PRIORITY_MAIL` and `PRIORITY_MAIL_EXPRESS` for outbound shipments.\n* The processing category `FLATS` is not valid for mail class `USPS_GROUND_ADVANTAGE`.\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" ] }, "destinationEntryFacilityType": { "type": "string", "description": "Types of Facilities:\n* `NONE` - Translate to Destination Rate Indicator N\n* `DESTINATION_NETWORK_DISTRIBUTION_CENTER` - Translate to Destination Rate Indicator B\n* `DESTINATION_SECTIONAL_CENTER_FACILITY` - Translate to Destination Rate Indicator S\n* `DESTINATION_DELIVERY_UNIT` - Translate to Destination Rate Indicator D\n* `DESTINATION_SERVICE_HUB` - Translate to Destination Rate Indicator H\n* `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` - Translate to Destination Rate Indicator B\n\nNote:\n* If any value other than `NONE` is selected, a destinationEntryFacilityAddress is required.\n* The destinationEntryFacilityAddress must be a valid facility to drop your package\n* The destination entry facility type must be set to `NONE` when there is a value provided for the 'inductionZipCode' field\n* Effective 01/19/2025: `DESTINATION_DELIVERY_UNIT` is the only valid enumeration when using the 'USPS_CONNECT_MAIL' mail class\n* Effective 01/18/2026: `DESTINATION_NETWORK_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is no longer eligible.\n* Effective 01/18/2026: (NSA Only) `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is available as an option.", "enum": [ "NONE", "DESTINATION_NETWORK_DISTRIBUTION_CENTER", "DESTINATION_SECTIONAL_CENTER_FACILITY", "DESTINATION_DELIVERY_UNIT", "DESTINATION_SERVICE_HUB", "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER" ] }, "destinationEntryFacilityAddress": { "$ref": "#/$defs/DomesticAddress" }, "packageOptions": { "allOf": [ { "$ref": "#/$defs/DomesticPackageOptions" }, { "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\nIf invoked, this label cannot be canceled. Instead, one must request an unused label refund – which may be subject to an admin fee. \n\nDepending on time of label creation, your packages could be charged same day instead of next day.\n" }, "originalPackage": { "required": [ "originalConstructCode", "originalTrackingNumber" ], "type": "object", "description": "* Note: packageOptions.originalPackage fields cannot be used in combination with packageOptions.returnReceiptTracking.\n", "properties": { "originalTrackingNumber": { "maxLength": 34, "minLength": 22, "type": "string", "description": "The tracking number associated with the package before it was over labeled.\nFor accurate tracking, this field requires a concatenated string consisting of the routingInformation and trackingNumber from the original label response.\n" }, "originalConstructCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A 3-character code to identify the construct of the Original Label Tracking Number" } } } }, "additionalProperties": true } ] }, "customerReference": { "maxItems": 4, "minItems": 0, "type": "array", "description": "Used for shippers to print a value on a label and included in the Shipping Services File (SSF).\n\nNote:\n * Customer Reference #3-4 are only supported with label types `4X5LABEL`, `4X6LABEL`, and `6X4LABEL`.\n * Customer Reference #3-4 cannot be used with a customs form.\n * Customer Reference #3-4 will not be added to the SSF.\n * Customer Reference will not display with `imageInfo.brandingImageFormat` value of `RECTANGLE`.\n * When Customer Reference #4 is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.", "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 (Print and Deliver, 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" } }, "mailingDate": { "type": "string", "description": "The local date on which the package will be mailed. If the time is not provided, it will be defaulted to 10:00 p.m. local time. Local time will be based on the `destinationEntryFacilityAddress.ZIPCode` or `inductionZIPCode` when provided, otherwise `fromAddress.ZIPCode` will be used as the origin ZIP Code.\n", "oneOf": [ { "$ref": "#/$defs/MailingDate" }, { "$ref": "#/$defs/MailingDateTime" } ] }, "carrierRelease": { "type": "boolean", "description": "Indicates whether recipients authorize a carrier to leave a shipment if no one is available to receive it at the time of delivery. Priority Mail Express® shipments or items requiring a signature at delivery are not eligible (e.g. Signature Confirmation, Insurance > $500).\n\nNote:\n * Carrier Release is currently not supported when `holdForPickup` is set to `true`.\n * Carrier Release is currently not supported with mail class values of `PRIORITY_MAIL`, `PRIORITY_MAIL_EXPRESS`, or `USPS_GROUND_ADVANTAGE`.\n * Carrier Release is currently not supported with `extraServices` `910`, `911`, `912`, `913`, `921`, `922`, `923`, `924`, `925`, `930`, `931`, `934`, `955`, or `981`.\n" }, "physicalSignatureRequired": { "type": "boolean", "description": "Indicates the method for the signature that will be used when signing for the package. Required when requesting signature `extraServices` including `910`, `911`, `912`, `913`, `921`, `922`, `923`, `924`, `925`, `931`, `934`, `955`, and `981`. Additionally required when requesting `extraServices` code `930` with a `packageValue` greater than $500.\n\nWhen `physicalSignatureRequired` is `false`, a USPS Electronic Signature Online (USPS eSOL) may be used to sign for the item. For more information on USPS eSOL, please visit the [USPS eSOL FAQ](https://faq.usps.com/s/article/USPS-Electronic-Signature-Online).\n\nWhen `physicalSignatureRequired` is `true`, the recipient will be required to physically sign for the item. A USPS eSOL on record will not be accepted as a valid signature for the item.\n\nNotes:\n * Regardless of the boolean, the printed label will still display \"SIGNATURE REQUIRED\" if a signature service is included with the label.\n * `carrierRelease` is not eligible to be used with `physicalSignatureRequired`.\n" }, "inductionZIPCode": { "$ref": "#/$defs/InductionZIPCode" }, "serialNumberFormat": { "$ref": "#/$defs/SerialNumberFormat" }, "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. There are two methods for reporting shipper information to USPS:\n\n1. The label provider creates a unique USPS Mailer ID (MID) using the name, validated address, phone, and email contact information of each shipper. When using this method the Mailer ID should be submitted in the MID field in the LABEL_OWNER role when generating the payment authorization token and this field should be populated with 'MID_INFORMATION'\n\n2. 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", "MID_INFORMATION" ] }, "mailOwnerMID": { "pattern": "^(\\d{6}|\\d{9})$", "type": "string", "description": "This is the mailer ID associated with the mail owner for this label This provides an additional copy of the scan extract file to the MID's outbound folder." }, "logisticsManagerMID": { "pattern": "^(\\d{6}|\\d{9})$", "type": "string", "description": "This is the mailer ID associated with the logistics manager for this label This provides an additional copy of the scan extract file to the MID's outbound folder." }, "nonprofit": { "$ref": "#/$defs/Nonprofit" } }, "additionalProperties": true, "description": "Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more.\n" } ] }, "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 } ] }, "DomesticCustomsForm": { "title": "Customs Form", "description": "Domestic Customs Form", "allOf": [ { "$ref": "#/$defs/CustomsForm" }, { "required": [ "contents", "customsContentType" ], "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": { "required": [ "itemDescription", "itemQuantity", "itemTotalValue", "itemTotalWeight", "weightUOM" ], "allOf": [ { "$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 label with customs forms are currently ineligible to be used with the extra service of \"USPS Label Delivery\" (415)." } ] }, "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 } ] }, "DomesticLabelToAddress": { "title": "Domestic Label To Address", "type": "object", "additionalProperties": true, "description": "The address where the 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 are always required.\n* Address elements `streetAddress`, `city`, `state`, `ZIPCode` are required unless a parcel locker is requested in which case the `facilityId`, Recipient Email, First and Last Name or Firm are required.\n* If the `holdForPickup` field is set to `true` then the `toAddress` object `facilityID`, `email`, and `phone` fields as well as the `fromAddress` object `firstName`, `lastName`, `email`, and `phone` fields are required.", "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 Destination 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. \n\nIn 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\nThis will automatically be set to `false` if extra service code `415 - USPS Label Delivery` is requested.\n" }, "parcelLockerDelivery": { "type": "boolean", "description": "Indicator to request delivery to a parcel locker instead of the recipient's address. If this field is set as true then the facilityId, email, and firstName/lastName or firm fields are required.\n\nNote:\n* Packages that require customs forms are not eligible to be shipped to a Smart Locker. Parcel lockers are not eligible for Hold for Pickup shipments.\n", "default": false }, "holdForPickup": { "type": "boolean", "description": "Indicator to request Hold for Pickup at a Post Office Facility. If this field is set as true then the `toAddress` object: 'facilityID', 'email', and 'phone' as well as the `fromAddress` object: 'firstName', 'lastName', 'email', and 'phone' fields are required.", "default": false }, "facilityId": { "maxLength": 7, "type": "string", "description": "Facility ID is required when generating a label for Parcel Locker delivery or Hold for Pickup. Facility ID can be retrieved through the Locations API (v3).\n\nNotes:\n* For Hold for Pickup services, the Facility ID is obtained from the `GET /post-office-locations` endpoint.\n* For Parcel Locker delivery, the Facility ID is obtained from the `GET /parcel-locker-locations` endpoint.\n" } }, "additionalProperties": true } ] }, "DomesticPackageDescription": { "title": "Package Description with Rate Indicators", "additionalProperties": true, "allOf": [ { "$ref": "#/$defs/BaseDomesticPackageDescription" }, { "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 * 3D - 3-Digit\n * 3N - 3-Digit Dimensional Rectangular\n * 3R - 3-Digit Dimensional Nonrectangular\n * 5D - 5-Digit\n * BA - Basic\n * BB - Mixed NDC\n * CP - Cubic Parcel\n * CM - USPS Connect® Local Mail\n * DC - NDC\n * DE - SCF\n * DF - 5-Digit\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 * LC - USPS Connect® Local Single Piece\n * LF - USPS Connect® Local Flat Rate Box\n * LL - USPS Connect® Local Large Flat Rate Bag\n * LO - USPS Connect® Local Oversized\n * LS - USPS Connect® Local Small Flat Rate Bag\n * NN - Non-Presorted Nonprofit\n * NP - Non-Presorted\n * OS - Oversized\n * PN - Presorted Nonprofit\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 * PR - Presorted\n * SN - SCF Dimensional Nonrectangular\n * SP - Single Piece\n * SR - SCF Dimensional Rectangular\n", "default": "SP", "enum": [ "3D", "3N", "3R", "5D", "BA", "BB", "CP", "CM", "DC", "DE", "DF", "DN", "DR", "E4", "E6", "FA", "FB", "FE", "FP", "FS", "LC", "LF", "LL", "LO", "LS", "NN", "NP", "OS", "PN", "P5", "P6", "P7", "P8", "P9", "Q6", "Q7", "Q8", "Q9", "Q0", "PA", "PL", "PM", "PR", "SN", "SP", "SR" ] } }, "additionalProperties": true } ] }, "DomesticPackageDescriptionWithoutRateIndicator": { "title": "Package Description without Rate Indicators", "additionalProperties": true, "allOf": [ { "$ref": "#/$defs/BaseDomesticPackageDescription" }, { "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`.\n", "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", "CONNECT_LOCAL_FLAT_RATE_BOX", "CONNECT_LOCAL_SMALL_FLAT_RATE_BAG", "CONNECT_LOCAL_LARGE_FLAT_RATE_BAG" ] } }, "additionalProperties": true } ] }, "DomesticPackageOptions": { "title": "Package Options", "description": "Options added to packages that are less frequently used.", "allOf": [ { "$ref": "#/$defs/PackageOptions" }, { "type": "object", "properties": { "redirectAddress": { "deprecated": true, "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" } ] }, "contentType": { "type": "string", "description": "The type of contents in the package.\n\nNote:\n* `CREMATED_REMAINS` is currently only eligible for the `PRIORITY_MAIL_EXPRESS` mail class and is not eligible for Hold for Pickup shipments. Please refer to [Publication 139](https://about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.\n* `DAY_OLD_POULTRY` is currently only eligible with mail class values of `USPS_GROUND_ADVANTAGE`, `PRIORITY_MAIL` and `PRIORITY_MAIL_EXPRESS`.\n* Shipments that contain Live Animals or Perishables will incur a Live Animal and Perishables Handling Fee per mail piece. Content types `HAZMAT`, `CREMATED_REMAINS`, and `MEDICAL_SUPPLIES` do not apply and will not incur a fee. For `DAY_OLD_POULTRY` shipments only, an additional Live Animal Transport Fee per pound is applied. For more information, please visit [Live Animals Transportation Fee FAQ](https://faq.usps.com/s/article/Live-Animal-Transportation-Fee#:~:text=The%20Live%20Animal%20Transportation%20fee%20is%20charged%20%240.20%20per%20pound,prices%20to%20Zones%205%2D9)\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 Perishable and Hazardous Material, please refer to [Publication 52](https://pe.usps.com/text/pub52/welcome.htm).\n* For ZIP codes with restrictions:\n * Please refer to the most recent [Postal Bulletin](https://about.usps.com/resources/postal-bulletin.htm) ZIP restriction table for more information. You can find this data under `Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`.\n * When restriction `M` applies, then `BEES`, `DAY_OLD_POULTRY`, `ADULT_BIRDS`, `OTHER_LIVES`, `FRUITS`, `VEGETABLES`, and `LIVE_PLANTS` are not allowed.\n * When restriction `X` applies, then `CREMATED_REMAINS` are not allowed.\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 \n(provided the appropriate endorsement is used and if the addressee filed a \nChange-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\nNote: \n * Ancillary Service Endorsements are currently not supported when 'holdForPickup' is set to 'true'.\n * 'CHANGE_SERVICE_REQUESTED' with a mail class value of 'PRIORITY_MAIL' currently only supports a contentType of 'PERISHABLE'.\n * 'CHANGE_SERVICE_REQUESTED' cannot be requested with a 'contentType' of 'HAZMAT' or any hazmat shipments.\n * 'CHANGE_SERVICE_REQUESTED' with mail classes 'PARCEL_SELECT', 'USPS_GROUND_ADVANTAGE', and 'PRIORITY_MAIL' can only be used with extraServices '920' and '921'.\n * Ancillary Service Endorsements are currently only supported with mail class values 'PARCEL_SELECT', 'USPS_GROUND_ADVANTAGE', 'PRIORITY_MAIL', and 'PRIORITY_MAIL_EXPRESS'.\n * 'ELECTRONIC_SERVICE_REQUESTED' with a mail class value of 'PARCEL_SELECT' cannot be requested with a 'contentType' of 'HAZMAT' or any hazmat shipments.\n", "enum": [ "CHANGE_SERVICE_REQUESTED", "ADDRESS_SERVICE_REQUESTED", "ELECTRONIC_SERVICE_REQUESTED", "RETURN_SERVICE_REQUESTED", "TEMP_RETURN_SERVICE_REQUESTED", "FORWARDING_SERVICE_REQUESTED" ] }, "returnReceiptTracking": { "type": "boolean", "description": "Indicates whether a return receipt tracking number should be generated for the package.\nIf set to `true`, the system will automatically add the Extra Service Code (ESC) `955`\nif it is not already present. When enabled, the `returnReceiptTrackingNumber` field will be populated in the response.\n\nNote: \n * `returnReceiptTracking` cannot be used in combination with `packageOptions.originalPackage` fields.\n * Utilizing `returnReceiptTracking` will incur the `955` ESC associated fee.\n", "default": false } }, "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" }, "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`." }, "MailingDate": { "type": "string", "description": "The date the package will be mailed.\n\nThe mailing date may be today plus 0 to 7 days in advance.\n\nThe time will default to 10 p.m. local time (based on the induction location of the package) for calculating the commitment and scheduled delivery date of the package.\n\nEnter the date in the full-date notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).\n", "format": "date" }, "MailingDateTime": { "type": "string", "description": "The date and time a package will be mailed.\n\nThe mailing date may be today plus 0 to 7 days in advance.\n\nEnter the date in the date-time notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).\n", "format": "date-time" }, "Nonprofit": { "title": "Nonprofit Indicator", "type": "boolean", "description": "Used to specify if the shipment is a nonprofit mailing. Shippers must be authorized for nonprofit mailings to qualify for nonprofit pricing. All nonprofit mailings must not be used for product fulfillment. For more details on Nonprofit Mailers, visit [Nonprofit Mailers](https://pe.usps.com/BusinessMail101?ViewName=NonprofitPrices).\n\nWhen `nonprofit` is `true` and `mailClass` is `MARKETING_MAIL_PARCELS`, nonprofit rates will be applied. When using `rateIndicator` values, the `rateIndicator` must also be `NN` or `PN`.\n\nWhen `nonprofit` is `false` and `mailClass` is `MARKETING_MAIL_PARCELS`, standard rates will be applied.\n\n`nonprofit` is not supported for any other mail class.\n", "default": false }, "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." }, "SerialNumberFormat": { "title": "Serial Number Format", "type": "string", "description": "Used to specify the barcode construct used for the generated tracking number. For details on barcode constructs, reference Appendix J in [Pub 199](https://postalpro.usps.com/pub199).\n\n`STANDARD` - Will generate a `C01`, `C03`, `C05`, or `C07` barcode construct, based on the Label Owner's `MID` in the Payment Authorization Token.\n\n`EXTENDED` - Will generate a `C02` or `C06` barcode construct, based on the Label Owner's `MID` in the Payment Authorization Token.\n", "default": "STANDARD", "enum": [ "STANDARD", "EXTENDED" ] }, "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." } } }