Returns Package Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-return-label-request-schema.json",
  "title": "Returns Package Request",
  "description": "Domestic Package Request",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-domestic-labels-openapi.yml#/components/schemas/ReturnLabelRequest",
  "required": [
    "fromAddress",
    "packageDescription",
    "toAddress"
  ],
  "type": "object",
  "properties": {
    "imageInfo": {
      "description": "Image information",
      "allOf": [
        {
          "$ref": "#/$defs/ImageInfo"
        },
        {
          "type": "object",
          "properties": {
            "suppressPostage": {
              "type": "boolean",
              "deprecated": true,
              "description": "This field has been deprecated.  Postage value is not printed on Return Labels.\n",
              "default": true
            },
            "suppressMailDate": {
              "type": "boolean",
              "deprecated": true,
              "description": "This field has been deprecated.\n\nNote:\n * Mail Date will not be printed on Return Labels without a customs form.\n * Mail Date will be printed on Domestic Customs Forms. The customs form will always display the Date of Mailing.\n * The date the label was created cannot be suppressed and will always print on the label.\n",
              "default": true
            },
            "returnLabel": {
              "type": "boolean",
              "deprecated": true,
              "description": "This field has been deprecated.  A return label cannot be generated with a return label.  This field will be ignored in the request.",
              "default": false
            },
            "receiptOption": {
              "description": "Receipt Option",
              "type": "string",
              "default": "NONE"
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "toAddress": {
      "description": "The address where the return package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing.\n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* For return labels, the `toAddress` ZIP Plus 4 is looked up by the API, unless the `ignoreBadAddress` field is set to true or the address cannot be found. If `ignoreBadAddress` field is true then ZIP Plus 4 is required.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        }
      ]
    },
    "fromAddress": {
      "description": "The address where the return package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing.\n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* If the `returnAddress` is not provided, the `fromAddress` will be used as the `returnAddress`.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        }
      ]
    },
    "senderAddress": {
      "description": "The address of the business involved (typically the sender of the original package). The `senderAddress` can be different from the `toAddress` when the business address is not where the package is being shipped to.\n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelSenderAddress"
        }
      ]
    },
    "returnAddress": {
      "description": "The address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label. This could be a secondary return address in case the toAddress is deemed undeliverable or returned to sender. \n\nNote:\n* The First and Last Name or Firm Name are always required.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        }
      ]
    },
    "packageDescription": {
      "description": "package description",
      "oneOf": [
        {
          "$ref": "#/$defs/ReturnsPackageDescription"
        },
        {
          "$ref": "#/$defs/ReturnsPackageDescriptionWithoutRateIndicator"
        }
      ]
    },
    "customsForm": {
      "$ref": "#/$defs/DomesticReturnsCustomsForm"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Address": {
      "title": "Address",
      "type": "object",
      "properties": {
        "streetAddress": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "The number of a building along with the name of the road or street on which it is located."
        },
        "streetAddressAbbreviation": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "This is the abbreviation of street address line for the address.",
          "readOnly": true
        },
        "secondaryAddress": {
          "maxLength": 50,
          "type": "string",
          "description": "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
        },
        "cityAbbreviation": {
          "type": "string",
          "description": "This is the abbreviation of city name for the address.",
          "readOnly": true
        }
      },
      "additionalProperties": true,
      "description": "Address fields standard to all locations."
    },
    "Addressee": {
      "title": "Addressee",
      "type": "object",
      "properties": {
        "firstName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "First Name corresponding to the address."
        },
        "lastName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "Last Name corresponding to the address."
        },
        "firm": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "Firm/business name corresponding to the address."
        }
      },
      "additionalProperties": true,
      "description": "Fields used to identity the entity receiving a mail piece or package"
    },
    "BaseReturnsPackageDescription": {
      "title": "Returns Package",
      "allOf": [
        {
          "$ref": "#/$defs/PackageDescription"
        },
        {
          "required": [
            "height",
            "length",
            "mailClass",
            "processingCategory",
            "weight",
            "width"
          ],
          "type": "object",
          "properties": {
            "mailClass": {
              "type": "string",
              "description": "The mail service requested.\n\nNote:\n- `FIRST-CLASS_PACKAGE_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`\n- `GROUND_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`\n",
              "enum": [
                "FIRST-CLASS_PACKAGE_RETURN_SERVICE",
                "GROUND_RETURN_SERVICE",
                "PRIORITY_MAIL_EXPRESS_RETURN_SERVICE",
                "PRIORITY_MAIL_RETURN_SERVICE",
                "USPS_GROUND_ADVANTAGE_RETURN_SERVICE"
              ]
            },
            "processingCategory": {
              "type": "string",
              "description": "Value designates if the shipment is `MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`.\n\nNote:\n* The processing category `LETTERS` is only valid when the mail class is `PRIORITY_MAIL_RETURN_SERVICE` or `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` for returns shipments.\n* The processing category `FLATS` is not valid for mail class `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`.\n* `IRREGULAR` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.\n* `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.",
              "enum": [
                "LETTERS",
                "FLATS",
                "MACHINABLE",
                "IRREGULAR",
                "NON_MACHINABLE",
                "NONSTANDARD"
              ]
            },
            "customerReference": {
              "maxItems": 4,
              "type": "array",
              "description": "Used for shippers to print a value on a label and included in the Shipping Services Files.",
              "items": {
                "$ref": "#/$defs/DomesticCustomerReference"
              }
            },
            "extraServices": {
              "maxItems": 5,
              "minItems": 0,
              "type": "array",
              "description": "Extra Service Code requested.\n* 365 - Global Direct Entry\n* 415 - USPS Label Delivery\n* 480 - Tracking Plus 6 Months\n* 481 - Tracking Plus 1 Year\n* 482 - Tracking Plus 3 Years\n* 483 - Tracking Plus 5 Years\n* 484 - Tracking Plus 7 Years\n* 485 - Tracking Plus 10 Years\n* 486 - Tracking Plus Signature 3 Years\n* 487 - Tracking Plus Signature 5 Years\n* 488 - Tracking Plus Signature 7 Years\n* 489 - Tracking Plus Signature 10 Years\n* 810 - HAZMAT Air Eligible Ethanol Package\n* 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package\n* 812 - HAZMAT Class 3 – Flammable Liquid Package\n* 813 - HAZMAT Class 7 - Radioactive Materials Package\n* 814 - HAZMAT Class 8 - Corrosive Materials Package\n* 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package\n* 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package\n* 817 - HAZMAT Class 9 - Lithium Battery - Returns Package\n* 818 - HAZMAT Class 9 - Lithium batteries, marked package\n* 819 - HAZMAT Class 9 - Dry Ice Package\n* 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n* 821 - HAZMAT Class 9 - Magnetized Materials Package\n* 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package\n* 823 - HAZMAT Division 5.1 - Oxidizers Package\n* 824 - HAZMAT Division 5.2 - Organic Peroxides Package\n* 825 - HAZMAT Division 6.1 – Toxic Materials Package\n* 826 - HAZMAT Division 6.2 – Infectious Substances Package\n* 827 - HAZMAT Excepted Quantity Provision Package\n* 828 - HAZMAT Ground Only\n* 829 - HAZMAT ID8000 Consumer Commodity Package\n* 830 - HAZMAT Lighters Package\n* 831 - HAZMAT LTD QTY Ground Package\n* 832 - HAZMAT Small Quantity Provision Package\n* 857 - Hazardous Material\n* 910 - Certified Mail\n* 911 - Certified Mail Restricted Delivery\n* 912 - Certified Mail Adult Signature Required\n* 913 - Certified Mail Adult Signature Restricted Delivery\n* 920 - USPS Tracking\n* 921 - Signature Confirmation\n* 922 - Adult Signature Required 21 or Over\n* 923 - Adult Signature Restricted Delivery 21 or Over\n* 924 - Signature Confirmation Restricted Delivery\n* 925 - Priority Mail Express Merchandise Insurance\n* 930 - Insurance <= $500\n* 931 - Insurance > $500\n* 934 - Insurance Restricted Delivery\n* 955 - Return Receipt\n* 957 - Return Receipt Electronic\n* 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)\n* 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)\n* 991 - Sunday Delivery\n\nNote:\n * When the extra service code \"930\" is provided in the request, if the item value is over $500, \"930\" will automatically be replaced with \"931\" - Insurance (Greater than $500).\n * USPS Label Delivery (Extra Service Code \"415\"): When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page. This service is not available at all locations.\n * Some service codes require a combination with extra services such as \"955\" and \"957\". For all valid combinations, visit [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).",
              "items": {
                "$ref": "#/$defs/ExtraService"
              }
            },
            "packageOptions": {
              "$ref": "#/$defs/DomesticPackageReturnOptions"
            },
            "destinationEntryFacilityAddress": {
              "deprecated": true,
              "description": "Destination entry facility address",
              "allOf": [
                {
                  "$ref": "#/$defs/DomesticAddress"
                }
              ]
            },
            "inductionZIPCode": {
              "$ref": "#/$defs/InductionZIPCode"
            },
            "shipperVisibilityMethod": {
              "type": "string",
              "description": "When generating labels for a third party shipper the label provider must capture and provide contact details of the individual or entity to whom they provide the label. For return labels, there is one method for reporting shipper information to USPS:\n\n1. An alternative method allows for the label provider to assign a unique alphanumeric value known as a `platformUserId` to each shipper and to report the `platformUserId` together with the required shipper contact details. When using this method the shipper contact details are required in the `senderAddress` object (including `streetAddress`, `city`, `state`, `ZIPCode`, `phone`, `email`, `platformUserId` & `firstName`/`lastName` or `firm`) and this field should be populated with 'SENDER_INFORMATION'.\n",
              "enum": [
                "SENDER_INFORMATION"
              ]
            }
          },
          "additionalProperties": true,
          "description": "Details on the package being returned."
        }
      ]
    },
    "Container": {
      "title": "Container",
      "required": [
        "containerID",
        "sortType"
      ],
      "type": "object",
      "properties": {
        "containerID": {
          "maxLength": 34,
          "type": "string",
          "description": "Unique identifier for a container."
        },
        "sortType": {
          "type": "string",
          "description": "Sort Types requested.",
          "enum": [
            "TRUCK_BEDLOAD",
            "OPEN_DISTRIBUTION_FULL_POSTAL_PAKS",
            "OPEN_DISTRIBUTE_EMM_TRAY_BOX",
            "OPEN_DISTRIBUTE_FULL_TRAY_BOX",
            "OPEN_DISTRIBUTE_HALF_TRAY_BOX",
            "OPEN_DISTRIBUTE_HALF_POSTAL_PAKS",
            "OPEN_DISTRIBUTE_PALLET",
            "OPEN_DISTRIBUTE_FLAT_TUB_TRAY_BOX",
            "PALLET",
            "RECEPTACLE",
            "SACK"
          ]
        }
      },
      "additionalProperties": false,
      "description": "containers"
    },
    "CustomerReference": {
      "title": "Customer Reference",
      "description": "Customer Reference",
      "type": "object",
      "properties": {
        "referenceNumber": {
          "maxLength": 30,
          "minLength": 1,
          "type": "string",
          "description": "A user-assigned number for internal use, such as Order, Invoice, Customer, or Return Merchandise Authorization Numbers. \n\nNote:\n* Domestic outbound label and return label with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` will display the entire value.\n* Return label with `labelType` of `4X6LABEL` with `brandingImageFormat` of `TWO_SQUARES` will show the first 25 characters.\n* These values will also be included in the Shipping Services File.\n"
        }
      },
      "additionalProperties": true
    },
    "CustomsForm": {
      "title": "Customs Form",
      "type": "object",
      "properties": {
        "contentComments": {
          "maxLength": 25,
          "type": "string",
          "description": "Required when customContentType is OTHER."
        },
        "restrictionType": {
          "type": "string",
          "description": "Restriction Types\n  * QUARANTINE\n  * SANITARY_INSPECTION\n  * PHYTOSANITARY_INSPECTION\n  * OTHER",
          "enum": [
            "QUARANTINE",
            "SANITARY_INSPECTION",
            "PHYTOSANITARY_INSPECTION",
            "OTHER"
          ]
        },
        "restrictionComments": {
          "maxLength": 25,
          "type": "string",
          "description": "Restriction Comments.  Required when `restrictionType`=`OTHER`."
        },
        "AESITN": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "AES/ITN Exemption should be populated with the electronic export internal transaction number (if required), or the appropriate Exemption/Exclusion Legend.\n\n* **AES - Automated Export System /   ITN - Internal Transaction Number**\\\n  The [internal transaction number (ITN)](https://pe.usps.com/text/imm/immc5_010.htm) is a 14-digit number that corresponds to an export transaction in the Automated Export System. It serves as proof that an exporter met his or her legal obligation to inform the U.S. government about the details of an export shipment.\n* **EEL- Exemptions, Exclusions, Legend**\\\n  An [AES exemption](https://pe.usps.com/text/imm/immc5_012.htm) is an instance in which you would not have to file in AES to get the 14-digit ITN. Instead of the ITN, you would enter the exemption’s section in the U.S. Foreign Trade Regulations on the export documentation where you would otherwise put the ITN.\n\nSample - `NO EEI 30.37(a)`: Shipments valued at $2,500 or less.\n"
        },
        "invoiceNumber": {
          "maxLength": 15,
          "minLength": 1,
          "type": "string",
          "description": "Invoice Number"
        },
        "licenseNumber": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "License Number"
        },
        "certificateNumber": {
          "maxLength": 12,
          "minLength": 1,
          "type": "string",
          "description": "Certificate Number"
        }
      },
      "additionalProperties": true,
      "description": "Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).\nRequired only if a customs form is required based on Customs Content Type and Weight.\n\nNote:\n  - Mail addressed to military and diplomatic post offices overseas is subject to certain conditions or restrictions of mailing regarding content, preparation, and handling. The APO/FPO/DPO table may be found on the most recent [postal bulletin](https://about.usps.com/resources/postal-bulletin.htm) found under `Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`"
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "additionalProperties": true,
      "description": "Address fields for US locations",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        },
        {
          "type": "object",
          "properties": {
            "city": {
              "maxLength": 28,
              "minLength": 1,
              "type": "string",
              "description": "This is the city name of the address."
            },
            "state": {
              "$ref": "#/$defs/State"
            },
            "ZIPCode": {
              "pattern": "^\\d{5}$",
              "type": "string",
              "description": "This is the 5-digit ZIP code."
            },
            "ZIPPlus4": {
              "pattern": "^\\d{4}$",
              "type": [
                "string",
                "null"
              ],
              "description": "This is the 4-digit component of the ZIP+4 code. Using the correct Zip+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error."
            },
            "urbanization": {
              "maxLength": 96,
              "type": "string",
              "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)."
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DomesticCustomerReference": {
      "title": "Customer Reference",
      "allOf": [
        {
          "$ref": "#/$defs/CustomerReference"
        },
        {
          "type": "object",
          "properties": {
            "printReferenceNumber": {
              "type": "boolean",
              "default": false,
              "description": "Indicates whether or not to print the customer reference number on the label in the Additional Information and User Segment.\n\nNote: \n- Customer Reference numbers are not displayed on label types `2X7LABEL` or `4X4LABEL`.\n- Customer Reference numbers are not displayed with Customs Forms.\n"
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DomesticLabelAddress": {
      "title": "Domestic Label Address",
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "type": "object",
      "additionalProperties": true,
      "description": "The address where the package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing. \n\nNotes:\n* The First and Last Name or Firm Name are always required.\n* If the `returnAddress` is not provided, the `fromAddress` will be used as the `returnAddress`.\n* If the `returnLabel` field is set to “true”, then the `fromAddress` ZIP Plus 4 is looked up by the API, unless the `ignoreBadAddress` field is set to true or the address cannot be found. If `ignoreBadAddress` field is true then ZIP Plus 4 is required.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticAddress"
        },
        {
          "$ref": "#/$defs/Addressee"
        },
        {
          "type": "object",
          "properties": {
            "phone": {
              "$ref": "#/$defs/Phone"
            },
            "email": {
              "$ref": "#/$defs/Email"
            },
            "ignoreBadAddress": {
              "type": "boolean",
              "description": "Allows Non-Validated Origin Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.\n\nNote: Integrators are recommended to always use `false` to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when `true` is indicated to allow label creation which could impact delivery.\n"
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DomesticLabelSenderAddress": {
      "title": "Domestic Label Sender Address",
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "type": "object",
      "additionalProperties": true,
      "description": "The address of the business involved. The senderAddress can be different from the fromAddress when the business address is not where the package is being shipped from.\n\nNotes:\n- The First and Last Name or Firm Name are always required.\n- `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        },
        {
          "$ref": "#/$defs/Addressee"
        },
        {
          "type": "object",
          "properties": {
            "platformUserId": {
              "maxLength": 30,
              "type": "string",
              "description": "This is a third-party unique identifier for the sender used for correlation purposes."
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DomesticPackageReturnOptions": {
      "title": "Package Options",
      "description": "Options added to packages that are less frequently used",
      "allOf": [
        {
          "$ref": "#/$defs/PackageOptions"
        },
        {
          "type": "object",
          "properties": {
            "immediateManifest": {
              "type": "boolean",
              "default": false,
              "description": "Setting this field to `true` will send electronic data to Postal systems within 15 minutes of label creation.\n"
            },
            "redirectAddress": {
              "deprecated": true,
              "description": "**Deprecated**: Use the `ancillaryServiceEndorsements` field instead.\n\nAddress to send the package to if it is not deliverable.\n\nNote:\n  - Required when `nonDeliveryOption` is a value of `REDIRECT`.\n",
              "allOf": [
                {
                  "$ref": "#/$defs/DomesticLabelAddress"
                }
              ]
            },
            "contentType": {
              "type": "string",
              "description": "The type of contents in the package.\n* HAZMAT\n* CREMATED_REMAINS\n* BEES\n* DAY_OLD_POULTRY\n* ADULT_BIRDS\n* OTHER_LIVES\n* PERISHABLE\n* PHARMACEUTICALS\n* MEDICAL_SUPPLIES\n* FRUITS\n* VEGETABLES\n* LIVE_PLANTS\n\nNote:\n* `CREMATED_REMAINS` is currently only eligible for the `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` mail class.  Please refer to [Publication 139](https://about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.\n* `HAZMAT` domestic labels with destination addresses to APO/FPO/DPO and PTFAS (except Puerto Rico) will not contain any Hazmat markings/indicators, including service type codes in the IMpb. When users indicate a shipment contains hazmat materials in the API request (via content type and/or extra services), that information will still be captured and sent in the shipping services file. For more information, please review the [USPS APIs release notes](https://postalpro.usps.gov/usps-apis-releases)\n* For guidelines on shipping Hazardous Material, please refer to [Publication 52](https://pe.usps.com/text/pub52/welcome.htm).\n",
              "enum": [
                "HAZMAT",
                "CREMATED_REMAINS",
                "BEES",
                "DAY_OLD_POULTRY",
                "ADULT_BIRDS",
                "OTHER_LIVES",
                "PERISHABLE",
                "PHARMACEUTICALS",
                "MEDICAL_SUPPLIES",
                "FRUITS",
                "VEGETABLES",
                "LIVE_PLANTS"
              ]
            },
            "generateGXEvent": {
              "type": "boolean",
              "description": "Provides the option for a user to not create a \"GX\" event for the package. By default, a GX event will be created.",
              "default": true
            },
            "containers": {
              "maxItems": 3,
              "type": "array",
              "description": "containers",
              "items": {
                "$ref": "#/$defs/Container"
              }
            },
            "ancillaryServiceEndorsements": {
              "type": "string",
              "description": "Endorsements allow the sender to obtain the addressee's new (forwarding) address (provided the appropriate endorsement is used \nand if the addressee filed a Change-of-Address Order with the Postal Service) or the reason for non-delivery. \nFor more information see [PostalPro](https://postalpro.usps.com/address-quality/ancillary-service-endorsements)\n",
              "deprecated": true,
              "enum": [
                "CHANGE_SERVICE_REQUESTED",
                "ADDRESS_SERVICE_REQUESTED",
                "ELECTRONIC_SERVICE_REQUESTED",
                "RETURN_SERVICE_REQUESTED",
                "TEMP_RETURN_SERVICE_REQUESTED",
                "FORWARDING_SERVICE_REQUESTED"
              ]
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "DomesticReturnsCustomsForm": {
      "title": "Customs Form",
      "description": "Domestic Returns Custom Form",
      "allOf": [
        {
          "$ref": "#/$defs/CustomsForm"
        },
        {
          "type": "object",
          "properties": {
            "customsContentType": {
              "type": "string",
              "description": "Specifies the content of the package or envelope.\n * MERCHANDISE\n * GIFT\n * DOCUMENT\n * COMMERCIAL_SAMPLE\n * RETURNED_GOODS\n * OTHER\n * HUMANITARIAN_DONATIONS\n * DANGEROUS_GOODS\n",
              "enum": [
                "MERCHANDISE",
                "GIFT",
                "DOCUMENT",
                "COMMERCIAL_SAMPLE",
                "RETURNED_GOODS",
                "OTHER",
                "HUMANITARIAN_DONATIONS",
                "DANGEROUS_GOODS"
              ]
            },
            "importersReference": {
              "maxLength": 40,
              "type": "string",
              "description": "Importers Reference. The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            },
            "importersContact": {
              "maxLength": 30,
              "type": "string",
              "description": "Importers Contact. Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            },
            "exportersReference": {
              "maxLength": 40,
              "type": "string",
              "description": "Exporters Reference. The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            },
            "exportersContact": {
              "maxLength": 30,
              "type": "string",
              "description": "Exporters Contact. Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            },
            "contents": {
              "minItems": 1,
              "maxItems": 30,
              "type": "array",
              "description": "Details of the contents of the package. The first five items will print on the label of the customs form, and the rest will print on a separate continuation page.",
              "items": {
                "$ref": "#/$defs/ShippingContents"
              }
            }
          },
          "additionalProperties": true,
          "description": "Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).\nRequired only if a customs form is required based on Customs Content Type and Weight.\n\nNote:\n  * A domestic return label with a customs form cannot have an extra service of \"USPS Label Delivery\" (415)."
        }
      ]
    },
    "Email": {
      "maxLength": 50,
      "pattern": "^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$",
      "type": "string",
      "description": "Email address used for redirect notification via email. ",
      "format": "email"
    },
    "ExtraService": {
      "title": "Extra Service Codes",
      "type": "integer",
      "description": "Extra Service Code (ESC) requested.\n\nExtra Service Code list:\n  * 365 - Global Direct Entry\n  * 415 - USPS Label Delivery\n  * 480 - Tracking Plus 6 Months\n  * 481 - Tracking Plus 1 Year\n  * 482 - Tracking Plus 3 Years\n  * 483 - Tracking Plus 5 Years\n  * 484 - Tracking Plus 7 Years\n  * 485 - Tracking Plus 10 Years\n  * 486 - Tracking Plus Signature 3 Years\n  * 487 - Tracking Plus Signature 5 Years\n  * 488 - Tracking Plus Signature 7 Years\n  * 489 - Tracking Plus Signature 10 Years\n  * 810 - HAZMAT Air Eligible Ethanol Package\n  * 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package\n  * 812 - HAZMAT Class 3 – Flammable Liquid Package\n  * 813 - HAZMAT Class 7 - Radioactive Materials Package\n  * 814 - HAZMAT Class 8 - Corrosive Materials Package\n  * 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package\n  * 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package\n  * 817 - HAZMAT Class 9 - Lithium Battery - Returns Package\n  * 818 - HAZMAT Class 9 - Lithium batteries, marked package\n  * 819 - HAZMAT Class 9 - Dry Ice Package\n  * 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n  * 821 - HAZMAT Class 9 - Magnetized Materials Package\n  * 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package\n  * 823 - HAZMAT Division 5.1 - Oxidizers Package\n  * 824 - HAZMAT Division 5.2 - Organic Peroxides P

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://artifacts.apis.io/usps/json-schema/usps-return-label-request-schema.json