Overview
When using USPS for return shipments, the ZIP+4 postal code format (e.g., 12345-6789) is required under certain address validation settings. Specifically, this requirement applies when the toAddress.ignoreBadAddress parameter is set to true.
Error messages
ZIPPlus4 is required for return label when toAddress.ignoreBadAddress is true
What does this means
If toAddress.ignoreBadAddress is set to true, the USPS return label system expects the full ZIP+4 code in the ship_to address field. A standard 5-digit ZIP code (e.g., 12345) will not be accepted in this case.
How to resolve this error
There are two ways to address this issue:
Bypass address validation
Go to your USPS carrier account settings.
Enable the "Bypass address validation" checkbox.
This allows shipments to proceed using a standard 5-digit ZIP code (
xxxxx).
2. Use the full ZIP+4 Format
Update the
ship_toaddress to include the complete ZIP+4 postal code (e.g.,12345-6789).This ensures USPS recognizes the address as valid under the existing validation rules.