{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/usps/json-schema/usps-international-label-request-schema.json", "title": "International Package Request", "description": "International Shipment Request", "x-generated": "2026-11-11", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/usps-international-labels-openapi.yml#/components/schemas/InternationalLabelRequest", "required": [ "customsForm", "fromAddress", "packageDescription", "toAddress" ], "type": "object", "properties": { "imageInfo": { "$ref": "#/$defs/ImageInfo" }, "toAddress": { "$ref": "#/$defs/InternationalLabelAddress" }, "fromAddress": { "$ref": "#/$defs/DomesticLabelAddress" }, "senderAddress": { "$ref": "#/$defs/DomesticLabelSenderAddress" }, "packageDescription": { "$ref": "#/$defs/InternationalPackageDescription" }, "customsForm": { "$ref": "#/$defs/InternationalCustomsForm" } }, "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 corresponding to the address." } }, "additionalProperties": true, "description": "Fields used to identity the entity receiving a mail piece or package." }, "CustomerReference": { "title": "Customer Reference", "description": "User-assigned reference numbers for internal tracking purposes such as order, invoice, or customer numbers.", "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. These values will be included in the Shipping Services File.\n\nNote:\n- Customer Reference numbers are not displayed with Customs Forms.\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": "USPS requires the ITN **_or_** the Exemption.\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 International shipments." }, "CustomsReference": { "title": "Customs Reference Information", "description": "Reference information for customs processing including tax codes, VAT numbers, importer codes, and contact details.", "type": "object", "properties": { "referenceType": { "type": "string", "description": "The type of reference number being provided.", "enum": [ "TAX_CODE", "VAT_NUMBER", "IMPORTER_CODE" ] }, "reference": { "maxLength": 28, "minLength": 1, "type": "string", "description": "Customs Reference.\n" }, "contact": { "description": "Contact information for customs reference. When multiple contact methods are provided, the customs form will prioritize printing phone number, then email address, then the fax number. All contact methods will be manifested electronically.", "type": "object", "properties": { "phone": { "$ref": "#/$defs/Phone" }, "fax": { "$ref": "#/$defs/Phone" }, "email": { "$ref": "#/$defs/Email" } } } }, "additionalProperties": false }, "DomesticAddress": { "title": "Domestic Address", "additionalProperties": true, "description": "Address fields for US locations", "allOf": [ { "$ref": "#/$defs/Address" }, { "type": "object", "properties": { "city": { "maxLength": 28, "minLength": 1, "type": "string", "description": "This is the city name of the address." }, "state": { "$ref": "#/$defs/State" }, "ZIPCode": { "pattern": "^\\d{5}$", "type": "string", "description": "This is the 5-digit ZIP code." }, "ZIPPlus4": { "pattern": "^\\d{4}$", "type": [ "string", "null" ], "description": "This is the 4-digit component of the ZIP+4 code. Using the correct Zip+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error." }, "urbanization": { "maxLength": 96, "type": "string", "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)." } }, "additionalProperties": true } ] }, "DomesticLabelAddress": { "title": "Domestic Label Address", "required": [ "ZIPCode", "city", "state", "streetAddress" ], "type": "object", "additionalProperties": true, "description": "Uses for:\n\nThe address of the business where the package is being mailed from. \n\nNote:\n- The First and Last Name or Firm Name are always 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 Origin Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.\n\n**Note:** 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" } } } ] }, "DomesticLabelSenderAddress": { "title": "Domestic Label Sender Address", "required": [ "ZIPCode", "city", "state", "streetAddress" ], "type": "object", "additionalProperties": true, "description": "Uses for:\n\n The address of the business sending the package. Can differ from the `fromAddress` in the case the business is using a third-party logistics provider or mailing from off-site locations.\n\n Note:\n - The First and Last Name or Firm Name are always required.", "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 } ] }, "EUProductIDFields": { "type": "object", "description": "Additional values specific to European Union Shipments. Required when shipping `customsContentType` of `MERCHANDISE` or `COMMERCIAL_SAMPLE` to European Union destinations with `incoterm` value of `1`.\n\nIf `incoterm` is not provided, these fields should not be populated.\n", "required": [ "merchantProductIdentifier", "nonstandardizedManufacturerProductIdentifier" ], "properties": { "merchantProductIdentifier": { "type": "string", "pattern": "^(?!.*[\\[\\];=]).{1,50}$", "description": "European Union Merchant Product Identifier. Required for all shipments with `customsForm.incoterm` value of `1` (Business to Consumer) going to the European Union.\n\nAssigned by the online seller, marketplace, or platform. It uniquely identifies the product within that platform (e.g., Product ID, internal SKU) \n" }, "nonstandardizedManufacturerProductIdentifier": { "type": "string", "pattern": "^(?!.*[\\[\\];=]).{1,70}$", "description": "European Union Non-standardized Manufacturer Product Identifier. Required for all shipments with `customsForm.incoterm` value of `1` (Business to Consumer) going to the European Union.\n\nAssigned by the manufacturer, producer, or supplier. It does not rely on an international standard; if none exists, the manufacturer must create one.\n" }, "standardizedManufacturerProductIdentifier": { "type": "string", "pattern": "^(?!.*[\\[\\];=]).{1,50}$", "description": "European Union Standardized Manufacturer Product Identifier.\n\nA globally recognized identifier such as a UPC or ISBN, when available. Required only when available and when shipping with `customsForm.incoterm` value of `1` (Business to Consumer) going to the European Union. If unavailable, this field is not required.\n" } } }, "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": "International Extra Service Codes", "pattern": "\\d{3}", "type": "integer", "description": "Available extra service codes", "enum": [ 480, 481, 482, 483, 484, 486, 487, 488, 813, 820, 826, 857, 930, 931, 955 ] }, "ImageInfo": { "title": "International Image Info", "type": "object", "properties": { "imageType": { "type": "string", "description": "The type of label image requested.\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).\n * 'PDF'\n * 'TIFF'\n * 'ZPL203DPI'\n * 'ZPL300DPI'\n * 'NONE'\n\nNote:\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": [ "LABEL_BROKER", "PDF", "TIFF", "ZPL203DPI", "ZPL300DPI", "NONE" ] }, "labelType": { "type": "string", "description": "The requested label image size to generate.", "default": "4X6LABEL", "enum": [ "4X6LABEL" ] }, "holdForManifest": { "type": "boolean", "description": "This field is deprecated and will be removed in a future release.\nBy default, all international packages are manifested at the end of the day.\nUse `packageDescription.packageOptions.immediateManifest` to trigger an immediate manifest.\n", "deprecated": true, "default": false }, "suppressPostage": { "type": "boolean", "description": "Indicates if Insured Fees and Postal Charges/Fees should be\nomitted from the label image. If true, Insured Fees and Postal\nCharges/Fees values will be removed.\n", "default": false }, "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, "description": "Applicable 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" } }, "additionalProperties": false, "description": "The Image Object defines label characteristics" }, "InternationalAddress": { "title": "International Address", "additionalProperties": true, "description": "Address fields for International locations.", "allOf": [ { "$ref": "#/$defs/Address" }, { "type": "object", "properties": { "city": { "maxLength": 28, "minLength": 1, "type": "string", "description": "This is the city name of the address." }, "postalCode": { "maxLength": 11, "type": "string", "description": "This is the Postal Code used for international addresses.\n\nNote:\n- When shipping to Canada, this field must start with a letter (A-Z)\n- Different shipping destinations may require a postal code for shipping. For more details, review the [Individual Country Listing](https://pe.usps.com/text/imm/immctry.htm) for your shipping destination\n" }, "province": { "maxLength": 40, "type": "string", "description": "This is the province used for international addresses." }, "provinceISOAlpha2Code": { "$ref": "#/$defs/ProvinceISOAlpha2Code" }, "country": { "minLength": 1, "type": "string", "description": "This is the country name used in an international address." }, "countryISOAlpha2Code": { "pattern": "^([a-zA-Z]){2}", "type": "string", "description": "ISO 3166-1 alpha-2 codes are two-letter country codes defined in ISO 3166-1, part of the ISO 3166 standard[1] published by the International Organization for Standardization (ISO), to represent countries, dependent territories, and special areas of geographical interest. They are the most widely used of the country codes published by ISO (the others being alpha-3 and numeric), and are used most prominently for the Internet's country code top-level domains (with a few exceptions). They are also used as country identifiers extending the postal code when appropriate within the international postal system for paper mail, and have replaced the previous one consisting of one-letter codes. They were first included as part of the ISO 3166 standard in its first edition in 1974." } }, "additionalProperties": true } ] }, "InternationalCustomsForm": { "title": "International Customs Form", "description": "Customs form information required for international shipments including content type, item details, and references.", "additionalProperties": false, "allOf": [ { "$ref": "#/$defs/CustomsForm" }, { "required": [ "AESITN", "contents", "customsContentType" ], "type": "object", "properties": { "customsContentType": { "type": "string", "description": "Specifies the content of the package or envelope.\n\nNote: \n* `CREMATED_REMAINS` is only supported by mailClass `PRIORITY_MAIL_EXPRESS_INTERNATIONAL`\n* `customsContentType` `DANGEROUS_GOODS` will be deprecated on 1/17/2027 and will no longer be a valid enumeration.\n", "enum": [ "MERCHANDISE", "GIFT", "DOCUMENT", "COMMERCIAL_SAMPLE", "RETURNED_GOODS", "OTHER", "HUMANITARIAN_DONATIONS", "DANGEROUS_GOODS", "CREMATED_REMAINS", "NON_NEGOTIABLE_DOCUMENT", "MEDICAL_SUPPLIES", "PHARMACEUTICALS" ] }, "importersReference": { "$ref": "#/$defs/CustomsReference" }, "exportersReference": { "$ref": "#/$defs/CustomsReference" }, "incoterm": { "type": [ "string", "null" ], "description": "Shipment classification for international transactions. Required for commercial shipments to the European Union. If neither, the field should be omitted from the request.\n\n* `1` - Business to Consumer\n* `2` - Business to Business\n", "enum": [ "1", "2" ] }, "contents": { "maxItems": 30, "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/InternationalShippingContents" }, "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.\n\nNote:\n- One of either `itemValue` and `itemWeight` or `itemTotalValue` and `itemTotalWeight` are required.\n" } }, "description": "Required for international labels to create s required based on Customs Content Type and Weight." } ] }, "InternationalLabelAddress": { "title": "International Label Address", "required": [ "city", "country", "countryISOAlpha2Code", "streetAddress" ], "type": "object", "additionalProperties": true, "description": "Uses for:\n\nThe international address where the package is being mailed to. The destination Country Code is used for calculating pricing.\n\nFor guidelines on acceptable international addresses, please reference [Section 122 of the International Mail Manual](https://pe.usps.com/text/imm/immc1_008.htm).\n\nNote:\n- The First and Last Name or Firm Name are always required.", "allOf": [ { "$ref": "#/$defs/InternationalAddress" }, { "$ref": "#/$defs/Addressee" }, { "type": "object", "properties": { "phone": { "$ref": "#/$defs/Phone" }, "provinceISOAlpha2Code": { "$ref": "#/$defs/ProvinceISOAlpha2Code" } } } ] }, "InternationalPackageDescription": { "title": "International Package Description", "description": "Physical and service characteristics of an international package including dimensions, weight, mail class, and processing requirements.", "allOf": [ { "$ref": "#/$defs/PackageDescription" }, { "required": [ "destinationEntryFacilityType", "height", "length", "mailClass", "mailingDate", "processingCategory", "weight", "width" ], "type": "object", "properties": { "mailClass": { "title": "International Mail Class of the label", "type": "string", "description": "International Mail classes for label The mail service requested.\n * FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE\n * PRIORITY_MAIL_INTERNATIONAL\n * PRIORITY_MAIL_EXPRESS_INTERNATIONAL", "enum": [ "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE", "PRIORITY_MAIL_INTERNATIONAL", "PRIORITY_MAIL_EXPRESS_INTERNATIONAL" ] }, "rateIndicator": { "type": "string", "description": "Use to specify USPS® containers/packaging or container attributes that may affect postage. A rate indicator value will be required if a value for `packagingType` is not provided.\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 * PA - Priority Mail Express International Single Piece\n * PL - Large Flat Rate Box\n * SP - Single Piece", "default": "SP", "enum": [ "E4", "E6", "FA", "FB", "FE", "FP", "FS", "PA", "PL", "SP" ] }, "packagingType": { "type": "string", "description": "Used to specify USPS® packaging attributes that may affect postage. Can be used instead of a rate indicator. Either packagingType or rate indicator is required.\n * FLAT_RATE_ENVELOPE\n * LEGAL_FLAT_RATE_ENVELOPE\n * PADDED_FLAT_RATE_ENVELOPE\n * SM_FLAT_RATE_BOX\n * MD_FLAT_RATE_BOX\n * LG_FLAT_RATE_BOX\n * VARIABLE\n", "enum": [ "FLAT_RATE_ENVELOPE", "LEGAL_FLAT_RATE_ENVELOPE", "PADDED_FLAT_RATE_ENVELOPE", "SM_FLAT_RATE_BOX", "MD_FLAT_RATE_BOX", "LG_FLAT_RATE_BOX", "VARIABLE" ] }, "diameter": { "minimum": 0, "type": "number", "description": "Future Use - The diameter of the package, in dimensionsUOM." }, "shape": { "type": "string", "description": "Indicates the mail piece shape.\n * RECTANGLE", "enum": [ "RECTANGLE" ] }, "processingCategory": { "type": "string", "description": "USPS® categorizes international parcels into four processing categories. These categories are based on the physical dimensions of the piece and impact how the mail will be processed.\n * `LETTERS`\n * `FLATS`\n * `MACHINABLE`\n * `NONSTANDARD`\n * `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025\n", "enum": [ "LETTERS", "FLATS", "MACHINABLE", "NON_MACHINABLE", "NONSTANDARD" ] }, "destinationEntryFacilityType": { "type": "string", "description": "Types of Facilities.\n * NONE - Translate to Destination Rate Indicator of N in USPS® Pub 205\n * INTERNATIONAL_SERVICE_CENTER - Translate to Destination Rate Indicator of I in USPS® Pub 205\n", "enum": [ "NONE", "INTERNATIONAL_SERVICE_CENTER" ] }, "mailingDate": { "type": "string", "description": "The date package will be mailed. The mailing date may be today plus 0 to 7 days in advance. Enter 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).", "format": "date" }, "packageOptions": { "$ref": "#/$defs/InternationalPackageOptions" }, "customerReference": { "description": "Customer reference information for the package. Up to two customer references may be provided.", "maxItems": 2, "minItems": 0, "type": "array", "items": { "$ref": "#/$defs/CustomerReference" } }, "extraServices": { "maxItems": 3, "minItems": 0, "type": "array", "description": "Extra Service Code requested on the package.\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* 486 - Tracking Plus Signature 3 Years\n* 487 - Tracking Plus Signature 5 Years\n* 488 - Tracking Plus Signature 7 Years\n* 813 - HAZMAT Class 7 - Radioactive Materials Package\n* 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n* 826 - HAZMAT Division 6.2 – Infectious Substances Package\n* 857 - Hazardous Material\n* 930 - Insurance <= $500\n* 931 - Insurance > $500\n* 955 - Return Receipt (Unsupported as of 01/19/2025)\n\nNote:\n* Only one USPS Tracking Plus® extra service and one Insurance extra service may be selected per package\n", "items": { "$ref": "#/$defs/ExtraService" } }, "inductionZIPCode": { "pattern": "^\\d{5}$", "type": "string", "description": "This is the 5-digit ZIP code where the package is being mailed from." }, "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." }, "prepayDutiesTaxesFees": { "type": "boolean", "description": "When set to `true`, duties, taxes, and import fees will be calculated and will be prepaid on behalf of the recipient if supported by the destination country. The resulting cost will be returned as `response.prepaidDutiesTaxesFees`.\n\nBy continuing, you agree to the [terms and conditions](https://zonos.com/docs/legal/usps-terms-of-service) for paying international duties, taxes, and fees (DDP), and certify that you will use DDP to ship goods to customers.\n\nWhen set to `false`, duties, taxes, and import fees will not be calculated and you will not have the option to pay duties, taxes, and import fees in advance, on behalf of the recipient.\n", "default": false } }, "additionalProperties": false } ] }, "InternationalPackageOptions": { "title": "International Package Options", "description": "Additional options for international package shipments including redirect addresses, over-labeling information, and manifest preferences.", "allOf": [ { "$ref": "#/$defs/PackageOptions" }, { "type": "object", "properties": { "redirectAddress": { "description": "Address where the package will be redirected to if undeliverable and a `nonDeliveryOption` of REDIRECT is provided. This field is required if REDIRECT `nonDeliveryOption` is provided.\n\nNote:\n- The First and Last Name or Firm Name are required when `redirectAddress` is populated.\n", "allOf": [ { "$ref": "#/$defs/DomesticLabelAddress" }, { "type": "object", "properties": { "email": { "$ref": "#/$defs/Email" } } } ] }, "originalPackage": { "required": [ "originalConstructCode", "originalTrackingNumber" ], "type": "object", "description": "Information about the original package when an over labeled package is being created.", "properties": { "originalTrackingNumber": { "maxLength": 13, "minLength": 13, "type": "string", "description": "The tracking number associated with the package before it was over labeled." }, "originalConstructCode": { "maxLength": 3, "minLength": 3, "type": "string", "description": "A 3-character code to identify the construct of the Original Label Tracking Number.", "default": "I01", "enum": [ "G01", "I01" ] } } }, "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 }, "immediateManifest": { "type": "boolean", "default": false, "description": "Setting this field to `true` will send electronic data to Postal systems within 15 minutes of label creation.\nIf invoked, this label cannot be cancelled. Instead, one must request an unused label refund – which may be subject to an admin fee.\nDepending on time of label creation, your packages could be charged same day instead of next day.\n" } }, "additionalProperties": false } ] }, "InternationalShippingContents": { "title": "International Customs Form Package Contents", "description": "Detailed information about items included in an international shipment for customs documentation purposes.", "additionalProperties": false, "allOf": [ { "$ref": "#/$defs/ShippingContents" }, { "required": [ "countryofOrigin", "itemDescription", "itemQuantity" ], "type": "object" } ] }, "PackageDescription": { "title": "Package Description", "description": "Basic physical characteristics of a package including weight, dimensions, and destination entry facility address.", "type": "object", "properties": { "weightUOM": { "type": "string", "description": "Weight Unit of Measure\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.\n" }, "dimensionsUOM": { "type": "string", "description": "Dimensions unit of measurement.\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`, 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." }, "destinationEntryFacilityAddress": { "$ref": "#/$defs/DomesticAddress" } }, "additionalProperties": true }, "PackageOptions": { "title": "Package Options", "description": "Additional options for package shipments including package value and non-delivery preferences.", "type": "object", "properties": { "packageValue": { "minimum": 0, "type": "number", "description": "The merchandise value of the package, in US dollars. Used to calculate Insurance Fees if requested." }, "nonDeliveryOption": { "type": "string", "description": "Requested action in the case a package is undeliverable: * RETURN for the package to be returned to `fromAddress`. * REDIRECT to return the package to address specified in the `redirectAddress`. * ABANDON to dispose of the undeliverable package", "enum": [ "RETURN", "REDIRECT", "ABANDON" ] } }, "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." }, "ProvinceISOAlpha2Code": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^([a-zA-Z]){2}", "description": "The 2 letter abbreviation representing the destination province. Required for select destination countries when `prepayDutiesTaxesFees` is `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." }, "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: 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]`. " }, "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: This field has been deprecated in favor of itemTotalWeight and will be removed in a future release. Please transition to using itemTotalWeight.", "deprecated": true }, "itemTotalWeight": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "Provide the total weight in weightUOM for the all the items matching the `[itemDescription]`." }, "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 an international address." }, "itemCategory": { "type": "string", "description": "Category of the item being shipped." }, "itemSubcategory": { "type": "string", "description": "Subcategory of the item being shipped." }, "europeanUnionProductID": { "$ref": "#/$defs/EUProductIDFields" } }, "additionalProperties": true, "description": "Required repeating up to 30 times." }, "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." } } }