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: 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).
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.