Merchant Returns API
The Merchant Returns API is a USPS web service that makes return shipping labels for customers of merchants enrolled in the USPS Merchant Return Program.Domestic Merchant Returns API: User Guidepage 12“The United States Postal Service (USPS®) Merchant Return web service provides free and easy generation of USPS® return labels for customers of merchants enrolled in the USPS® Merchant Return Program.”USPS original A merchant's application requests one label or a bulk set, as a PDF, TIF or PNG image.Domestic Merchant Returns API: User Guidepage 14“It is used to generate single or bulk return shipping labels in either a TIF, PDF or PNG format.”USPS original Merchants offer the labels from their own websites and pay for them.PostalPro: Merchant Returns API“The API allows merchants to directly offer merchant-funded USPS return labels from their own websites.”USPS original
What it is
The Merchant Returns API is one of two ways into the USPS Merchant Return web service.Domestic Merchant Returns API: User Guidepage 12“USPS® Merchant Return web service provides 2 ways to generate labels.”USPS original The other is the USPS Merchant Return website, a label page the merchant links its customers to.Domestic Merchant Returns API: User Guidepage 14“Each merchant receives a set of URL links that lead to a label generation web page.”USPS original The website needs no programming at all.Domestic Merchant Returns API: User Guidepage 14“The USPS® Merchant Return website is a free service provided to merchants that totally removes the need for any API development.”USPS original
The API is for experienced programmers who know internet and website development.Domestic Merchant Returns API: User Guidepage 14“The API is for experienced programmers who are familiar with internet and website development tools and techniques.”USPS original Its users are merchants that have signed up for Scan Based Payment.PostalPro: Merchant Returns API“The Returns APIs allow merchants that have signed up for the Scan Based Payment service access to the online serices of the Unites States Postal Service (USPS).”USPS original A merchant's server talks to a USPS server over HTTP, in XML.Domestic Merchant Returns API: User Guidepage 12“Your server communicates through a USPS® server over Hyper Text Transfer Protocol (HTTP)/s using eXtensible Markup Language (XML).”USPS original Each label carries an Intelligent Mail Package Barcode that tracks on USPS.com.PostalPro: Merchant Returns API“The return labels also each have an Intelligent Mail Package Barcode (IMpb) that can be tracked on USPS.com.”USPS original
A merchant can't open an account alone: a USPS administrator registers it.PostalPro: Merchant Returns API“Important Note: In order to begin using the API, you must first become a registered user with the assistance of a USPS administrator (see contact information below).”USPS original A USPS Merchant Return Administrator enters the merchant's return address and services, then issues a Merchant Account Code.Domestic Merchant Returns API: User Guidepage 31“Once an administrator has set up an account for you, they are able to input your information (destination address, services offered to customers, etc.) and you are provided a new Merchant Account Code.”USPS original That code is the identifier of the merchant's account in the Merchant Return system.Domestic Merchant Returns API: User Guidepage 28“Identification code of Merchant Account in the USPS® Merchant Return system (to be assigned when a merchant is onboarded by a USPS® Merchant Return Administrator).”USPS original
How it works
A label request is one XML document, URL-encoded and sent with HTTP GET.Domestic Merchant Returns API: User Guidepage 79“All requests should be made via HTTP GET. … XML should be encoded using standard HTTP/URL encoding.”USPS original Single labels go to GetLabel, and bulk sets go to GetBulkLabels.Domestic Merchant Returns API: User Guidepage 32“https://returns.usps.com/services/GetLabel?externalReturnLabelRequest=”USPS originalDomestic Merchant Returns API: User Guidepage 35“https://returns.usps.com/Services/GetBulkLabels?externalReturnLabelRequest=”USPS original
- A USPS Merchant Return Administrator sets up the account and issues its Merchant Account Code.Domestic Merchant Returns API: User Guidepage 31“Once an administrator has set up an account for you, they are able to input your information (destination address, services offered to customers, etc.) and you are provided a new Merchant Account Code.”USPS original
- The merchant's application builds an XML request and sends it to the web service.Domestic Merchant Returns API: User Guidepage 14“An XML request must be built and sent to the USPS® Merchant Return web service.”USPS original
- The web service returns either a success document or an error document.Domestic Merchant Returns API: User Guidepage 14“When the USPS® Merchant Return web service returns a response, it will either return a successful response document or an error document.”USPS original
- A success document carries the label as Base64, with its postal routing and tracking numbers.Domestic Merchant Returns API: User Guidepage 39“The response contains a Base-64 encoded label. … It also contains the postal routing number and the label tracking number.”USPS original
- The application decodes the Base64 text to get the label image.Domestic Merchant Returns API: User Guidepage 64“The Base-64 encoded label must be decoded using a Base-64 decoder to obtain the return label.”USPS original
The request
A request whose start and end tags don't match exactly gets an error.Domestic Merchant Returns API: User Guidepage 23“An error message is returned if an incorrect value is entered or the begin and end tags to not match exactly.”USPS original An empty tag is ignored.Domestic Merchant Returns API: User Guidepage 23“If you provide an empty tag, it will be ignored.”USPS original
A single-label request carries these tags:
MerchantAccountCode, the merchant's Merchant Account Code.Domestic Merchant Returns API: User Guidepage 28“Identification code of Merchant Account in the USPS® Merchant Return system (to be assigned when a merchant is onboarded by a USPS® Merchant Return Administrator).”USPS originalMID, the merchant's Mailer ID, which must be the one tied to that account code.Domestic Merchant Returns API: User Guidepage 28“The MID used must be the MID associated with the Merchant Account Code passed with the request.”USPS originalCustomerNameand theCustomeraddress tags, for the customer returning the package.Domestic Merchant Returns API: User Guidepage 25“Address of customer returning the package.”USPS originalLabelDefinition, the size of the label.Domestic Merchant Returns API: User Guidepage 27“Size of the label.”USPS originalServiceTypeCode, the service type, from those set up in the merchant's profile.Domestic Merchant Returns API: User GuidePDF page 29“Service type of the label as specified in the merchant profile setup.”USPS originalCallCenterOrSelfService, which says whether a call center agent or the customer is asking.Domestic Merchant Returns API: User Guidepage 25“Used to determine if the return label request is coming from a merchant call center agent or an end customer.”USPS original
A bulk request uses the same tags and adds two.Domestic Merchant Returns API: User Guidepage 30“Bulk Label requests use all the common parameters along with the following:”USPS original ConfirmCRID holds the merchant's Customer Registration ID.Domestic Merchant Returns API: User Guidepage 30“Actual Customer Registration ID (CRID).”USPS original Quantity sets the number of labels, from 2 to 100.Domestic Merchant Returns API: User Guidepage 30“value=between 2 and 100”USPS original
Some optional tags carry the merchant's own references:
PackageInformation, an RMA, invoice or order number that prints on the label.Domestic Merchant Returns API: User Guidepage 28“Package information can be one of three types: RMA, Invoice or Order Number. … This appears on the generated label.”USPS originalMerchandiseDescription, which the system stores and reports to the merchant but never prints.Domestic Merchant Returns API: User Guidepage 79“It is not displayed on the label, but rather stored internally on the USPS® Merchant Return application. … It is contained in the transaction reports that can be sent to merchants that request a summary of their label activity.”USPS originalRecipientEmail, an address the system emails the label to.Domestic Merchant Returns API: User GuidePDF page 29““To:” email address in an email sent by the system containing the return label attachment and message.”USPS original
Labels
The label is 3 by 6, 4 by 4 or 4 by 6 inches, from the sizes the account allows.Domestic Merchant Returns API: User Guidepage 41“(The label definition must be one of the label sizes (4X4, 4X6, 3X6, etc.) specified for the Merchant Account.”USPS original Each prints on a full 8 ½ x 11 sheet unless a cropped format trims it.Domestic Merchant Returns API: User Guidepage 49“Label dimension in inches, full 8 ½ x 11 paper size”USPS originalDomestic Merchant Returns API: User Guidepage 50“The image is cropped so that its actual size matches the label size.”USPS original
LabelFormat sets the layout:
- Left off or blank: a label with instructions, the only format the website makes.Domestic Merchant Returns API: User Guidepage 50“Leaving the <LabelFormat> tag off an API request or setting the tag value to blank or spaces will generate a label with instructions. … This is the only format allowed for creating labels through the website.”USPS original
NOI: one label per sheet with no instructions.Domestic Merchant Returns API: User Guidepage 50“Generate one label per 8 ½” sheet with NO instructions at the bottom.”USPS originalTWO: two labels on one page, each with its own RMA and tracking number, for 4X6 only.Domestic Merchant Returns API: User Guidepage 50“Generates two labels on the same page, each with their own distinct RMA and Tracking Numbers. … Currently valid for 4X6 only.”USPS originalHCROP: an image cropped to the label, long side horizontal, for 4X6 only.Domestic Merchant Returns API: User Guidepage 50“Image contains a label with the longest dimension horizontal. … Currently valid for 4X6 only.”USPS originalVCROP: an image cropped to the label, long side vertical, which with 4X6 prints on a Zebra printer.Domestic Merchant Returns API: User Guidepage 50“Image contains a label with the longest dimension vertical.”USPS originalDomestic Merchant Returns API: User Guidepage 80“Labels can be printed for Zebra printers by setting the “LabelFormat” field to “VCROP” (vertical crop) and the “Label Definition” field to “4X6”.”USPS original
ImageType picks PDF, TIF or PNG, and a blank or unknown value gives a PDF.Domestic Merchant Returns API: User Guidepage 14“It is used to generate single or bulk return shipping labels in either a TIF, PDF or PNG format.”USPS originalDomestic Merchant Returns API: User Guidepage 27“If the ImageType tag is blank or unrecognized, the default format is a PDF.”USPS original
In CallCenterOrSelfService, the display type CallCenter allows insurance and endorsements, and Customer allows neither.Domestic Merchant Returns API: User Guidepage 67“The “CallCenter” interfaces allow insurance, the “Customer” interfaces don’t. … The “CallCenter” interface also shows the endorsements section on the user interface and lets it be used on an API call, the “Customer” interface doesn’t.”USPS original A label can carry up to three endorsements, such as TIME SENSITIVE, and automatic hazmat endorsements count toward the three.Domestic Merchant Returns API: User Guidepage 26“Max 3 endorsements can be included. This includes any automatic Hazmat endorsements required by <HazmatCode> or user hazmat selection.”USPS originalDomestic Merchant Returns API: User Guidepage 68“Add “TIME SENSITIVE” endorsement to label”USPS original
Service type codes
The service type code sets the mail class of the label.Domestic Merchant Returns API: User Guidepage 52“These service type codes can be used to generate specific mail class labels by the USPS® Merchant Return API.”USPS original Each account allows only the codes its merchant chose with a USPS Merchant Return Administrator.Domestic Merchant Returns API: User Guidepage 52“NOTE: It is up to the Merchant to work with a USPS® Merchant Return Administrator to select the Service Type and Label Size combinations enabled for the merchant’s customers. … They can be further restricted by the merchant during account setup.”USPS original
The service type codes the API can put on a label.Domestic Merchant Returns API: User Guidepage 52“These service type codes can be used to generate specific mail class labels by the USPS® Merchant Return API.”USPS original
| Code | Description | Mail class | Extra service codes |
|---|---|---|---|
| 019 | Priority Mail Return | PM | 452 |
| 020 | USPS Ground Advantage Return: Up to 15.999oz | FC | 452 |
| 022 | USPS Ground Advantage Return: One Pound or More | FC | 452 |
| 037 | Priority Mail Return: Hazardous Materials | PM | 452, 857 |
| 187 | USPS Ground Advantage Return: Up to 15.999oz Hazardous Materials | FC | 452, 857 |
| 190 | USPS Ground Advantage Return: Up to 15.999oz Insurance <= $500 Hazardous Materials | FC | 930, 452, 857 |
| 191 | USPS Ground Advantage Return: Up to 15.999oz Insurance > $500 Hazardous Materials | FC | 931, 452, 857 |
| 217 | USPS Ground Advantage Return: Up to 15.999oz Division 6.2 Hazardous Materials | FC | 452, 826 |
| 218 | USPS Ground Advantage Return: One Pound or More Division 6.2 Hazardous Materials | FC | 452, 826 |
| 219 | Priority Mail Return: Division 6.2 Hazardous Materials | PM | 452, 826, 857 |
1 to 10 of 29 codes in the IMpb Service Type Code List, Appendix I, where Code is 019 or 020 or 022 or 596 or 597 or 598 or 599 or 600 or 601 or 187 or 190 or 191 or 385 or 388 or 399 or 037 or 515 or 517 or 217 or 218 or 219 or 796 or 797 or 798 or 837 or 838 or 839 or 667 or 668.
Hazardous materials
A hazmat return needs a hazmat service type code and one HazmatCode, an extra service code for the kind of material.Domestic Merchant Returns API: User Guidepage 27“Required if ServiceTypeCode provided is a hazmat service type”USPS originalDomestic Merchant Returns API: User Guidepage 53“Only 1 hazmat extra service code is allowed per request. … These extra service codes can be used to classify the type of hazmat included in the package for API requests.”USPS original HazmatCode replaced the ContentType and ExtraServiceCodes tags in Release 2.3 of July 22, 2025.Domestic Merchant Returns API: User Guidepage 10“1.1. Release 2.3 (7/22/2025) … Deprecate use of <ContentType> and <ExtraServiceCodes>”USPS original
The hazmat extra service codes HazmatCode takes.Domestic Merchant Returns API: User Guidepage 53“These extra service codes can be used to classify the type of hazmat included in the package for API requests.”USPS original
| Code | Extra service |
|---|---|
| 810 | HAZMAT Air Eligible Ethanol Package |
| 811 | HAZMAT Class 1 - Toy Propellant/Safety Fuse Package |
| 812 | HAZMAT Class 3 – Flammable Liquid Package |
| 813 | HAZMAT Class 7 - Radioactive Materials Package |
| 814 | HAZMAT Class 8 - Corrosive Materials Package |
| 815 | HAZMAT Class 8 - Nonspillable Wet Battery Package |
| 816 | HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package |
| 817 | HAZMAT Class 9 - Lithium Battery - Returns Package |
| 818 | HAZMAT Class 9 - Lithium batteries, marked package |
| 819 | HAZMAT Class 9 - Dry Ice Package |
1 to 10 of 23 codes in the Extra Service Codes, Pub 199 Appendix J Table 7, where Code is 810 or 811 or 812 or 813 or 814 or 815 or 816 or 817 or 818 or 819 or 820 or 821 or 822 or 823 or 824 or 825 or 826 or 827 or 828 or 829 or 830 or 831 or 832.
Hazmat from military and territory addresses
Returns from military and diplomatic addresses and from PTFAS, the U.S. possessions, territories and freely associated states, allow only three kinds of hazmat.Domestic Merchant Returns API: User Guidepage 81“NOTE 1: PTFAS are U.S. Possessions, Territories, and Freely Associated States”USPS originalDomestic Merchant Returns API: User Guidepage 56“Only these types of HAZMAT are allowed from APO/DPO/PTFAS Addresses:”USPS original
The hazmat codes allowed from APO, DPO and PTFAS addresses.Domestic Merchant Returns API: User Guidepage 56“Only these types of HAZMAT are allowed from APO/DPO/PTFAS Addresses:”USPS original
| Code | Extra service |
|---|---|
| 813 | HAZMAT Class 7 - Radioactive Materials Package |
| 820 | HAZMAT Class 9 - Lithium batteries, unmarked package |
| 826 | HAZMAT Division 6.2 – Infectious Substances Package |
3 codes in the Extra Service Codes, Pub 199 Appendix J Table 7, where Code is 813 or 820 or 826.
Labels for these addresses print no hazmat markings.Domestic Merchant Returns API: User Guidepage 56“Any label generated for APO/DPO/PTFAS (whether Hazmat or non-Hazmat) will not have hazmat markings on the label.”USPS original The manifest record for the label still carries the hazmat service type code and extra service codes.Domestic Merchant Returns API: User Guidepage 56“The manifest record generated for the label WILL have the Hazmat service type code (STC) and Extra Service Codes (ESC).”USPS original
Cubic labels
Marking a package cubic gets it better shipping rates, and the API prints the cubic marking, tier and size on the label.Domestic Merchant Returns API: User Guidepage 57“Marking a package cubic enables it for better shipping rates. … MRA allows labels to be marked with the Cubic Postal Marking, tier, and Size.”USPS original A cubic request sets PostalMarking to CUBIC and names a container type, BOX or SOFTPACK.Domestic Merchant Returns API: User Guidepage 57“If CUBIC is requested, the Container Type is required. … It can be either “BOX” or “SOFTPACK”.”USPS original
A cubic package:
- weighs 20 pounds or less, given in pounds and ounces.Domestic Merchant Returns API: User Guidepage 57“Must be 20 lbs. or under, weight in pounds and ounces is required.”USPS original
- has no dimension over 22 inches.Domestic Merchant Returns API: User Guidepage 57“No dimension can be over 22”.”USPS original
- goes by USPS Ground Advantage at 1 pound or more, or by Priority Mail.Domestic Merchant Returns API: User Guidepage 57“Is only valid for USPS® Ground Advantage™ 1 lb. or over or USPS® Priority Mail©.”USPS original
- as a box, gives its length, width and height.Domestic Merchant Returns API: User Guidepage 57“If ContainerType is “BOX”, then 3 dimensions of the box (Length, Width, Height) are required so they can be used in the cubic dimension calculation.”USPS original
- as a softpack, a padded envelope, gives length and width, which together can't pass 36 inches.Domestic Merchant Returns API: User Guidepage 58““SOFTPACK” is used for padded envelopes. … If ContainerType is “SOFTPACK”, then only 2 dimensions of the box (Length, Width) are required – height is not used in the cubic dimension calculation.”USPS originalDomestic Merchant Returns API: User Guidepage 57“For CUBIC SOFTPACK the total of the length and width dimensions can’t be more than 36”.”USPS original
The API calculates the cubic tier from the measurements and prints it on the label.Domestic Merchant Returns API: User Guidepage 58“Using the measurements given, the Cubic Tier is calculated and printed on the label.”USPS original Since Release 2.6 of July 20, 2026, Ground Advantage softpacks use the same cubic tiers as Priority Mail.Domestic Merchant Returns API: User Guidepage 10“1.3. Release 2.6 (7/20/2026) … Updated label website and API to reflect the new Cubic Softpack tiers for Ground Advantage. … The tiers now match those used for Priority Mail.”USPS original
The response
A success response carries the label in ReturnLabel, Base64-encoded for transport over the internet.Domestic Merchant Returns API: User Guidepage 64“The <ReturnLabel> tag contains the label and is Base-64 encoded for transport over the internet.”USPS original It also carries the PostalRouting number and the TrackingNumber, which prints on the label below the barcode.Domestic Merchant Returns API: User Guidepage 39“It also contains the postal routing number and the label tracking number. … The tracking number is displayed on the label, below the barcode.”USPS original A TWO request adds TrackingNumber2 for the second label, and the two labels share one postal routing number.Domestic Merchant Returns API: User Guidepage 39“Tracking Number of second label when a request with <LabelFormat> TWO</LabelFormat> is sent.”USPS originalDomestic Merchant Returns API: User Guidepage 50“The double labels will share a Postal Routing number, as they are delivered to the same location.”USPS original
The tracking number in USPS's sample success response, which fails the IMpb length check.Domestic Merchant Returns API: User Guidepage 39“<TrackingNumber>920449378838000030687</TrackingNumber>”USPS original
The Mailer ID and serial number are examples.
- FailedThat’s 21 digits. Package barcodes have 22, 26, 30 or 34, so check for a missing or extra digit.Intelligent Mail® Package Barcode (IMpb) Specificationpage 15“Format C03 - Commercial Mail (9 digit MID, ZIP) 30 digits”USPS originalPublication 199: Intelligent Mail Package Barcode (IMpb) Implementation Guide for Confirmation Services and Electronic Payment Systemspage 52““92” - used with Commercial Mailer (Nine-digit MID) “93” - used with Commercial Mailer (Six-digit MID)”USPS original
Label Broker
USPS Label Broker is a service for customers without a printer.Domestic Merchant Returns API: User Guidepage 60“The USPS® Label Broker® service facilitates shipping for consumers without access to a printer.”USPS original They print the label at a Post Office or through USPS.com, using a QR code or Label Broker ID.Domestic Merchant Returns API: User Guidepage 60“It allows customers to print labels using a QR Code or Label Broker Label ID at a USPS® Post Office® or via USPS.com.”USPS original
A request sends its label to Label Broker by setting Broker to Y.Domestic Merchant Returns API: User Guidepage 25“Allowed Value = Y … Send the label to the USPS® Label Broker.”USPS original It must also ask for a 4X6 label in the VCROP format as a PNG image, and it can't be a bulk request.Domestic Merchant Returns API: User Guidepage 25“Label Definition = 4X6 LabelFormat = VCROP ImageType = PNG Not Valid for Bulk Requests”USPS original It needs the customer's ZIP Code.Domestic Merchant Returns API: User Guidepage 43“A valid Zip Code is required to use the Label Broker.”USPS original
Label Broker stores the label and returns a unique code for it.Domestic Merchant Returns API: User Guidepage 61“The USPS Label Broker® will generate a unique code to identify the saved label.”USPS original The response also carries a notice that Label Broker's terms require the merchant to give the customer.Domestic Merchant Returns API: User Guidepage 61“A notice to the customer is also generated and is required by USPS Label Broker® use terms to be given to the user.”USPS original The customer shows the code to a USPS retail associate, who prints the label and applies it.Domestic Merchant Returns API: User Guidepage 60“The consumer will need to show the Label Broker code to the USPS® Retail Associate at the Retail Counter who will print and apply the linked label to the shipment.”USPS original
With the code, a merchant can check a stored label's status or void it so it can't be printed.Domestic Merchant Returns API: User Guidepage 61“Using the unique code generated when a label is stored in USPS Label Broker®, merchants can query the label’s status. … Using the unique code generated when a label is stored in USPS Label Broker®, merchants can void a label such that it will not be retained and can no longer be printed.”USPS original A merchant can see or void only the labels it stored.Domestic Merchant Returns API: User Guidepage 61“Only status information for label broker IDs stored by a merchant can be retrieved by that merchant. … Only label broker IDs stored by a merchant can be voided by that merchant.”USPS original
Proximity routing
Proximity Routing is a feature for merchants with several accounts that serve as different return locations.Domestic Merchant Returns API: User Guidepage 62“Proximity Routing is a feature on the Return tool intended for merchants who have multiple accounts that serve as different return locations.”USPS original It picks the destination printed on the label by the customer's distance to each return location.Domestic Merchant Returns API: User Guidepage 62“Proximity Routing allows the merchant to determine what destination address to print on the label, based on the distance of the customer to the merchant’s return locations.”USPS original
A proximity merchant's requests use the default account's Merchant Account Code, label sizes and service type codes.Domestic Merchant Returns API: User Guidepage 63“The only difference in the request is that a user will use the Merchant Account Code, Label Definition, and Service Type Code available for the default account.”USPS original An error in the distance calculation sends the package to the default account.Domestic Merchant Returns API: User Guidepage 63“Any error in distance calculation would result in the package being sent to the default account, in this case Texas.”USPS original A single-label request in the TWO format can't use it, because those labels print a blank return address.Domestic Merchant Returns API: User Guidepage 63“The Proximity Routing feature cannot be utilized on labels printed in the “Double Label” format.”USPS originalDomestic Merchant Returns API: User Guidepage 81“Single API labels with label format of TWO automatically use a blank return address.”USPS original
The Merchant Return website
Each enrolled merchant gets a free label website for its customers, embedded in the merchant's site or reached directly.Domestic Merchant Returns API: User Guidepage 67“Each merchant enrolled is automatically provided (free of charge) a website for their customers to generate return labels. … This website can be embedded in the merchant’s website or can be accessed directly.”USPS original USPS gives each merchant four URLs to the site.Domestic Merchant Returns API: User Guidepage 67“Each enrolled merchant will be provided with 4 URLs.”USPS original URL parameters can fill in most of the label form for the customer.Domestic Merchant Returns API: User Guidepage 68“Merchants can add additional parameters to the URL to pre-fill most values needed for creating the label.”USPS original
Rules
To use the USPS Label Broker®, Merchants must abide by the terms and conditions.Domestic Merchant Returns API: User Guidepage 60“To use the USPS Label Broker®, Merchants must abide by the terms and conditions.”USPS original
A merchant that uses Label Broker must follow its terms and conditions. The customer must ask for Label Broker delivery before the merchant's application stores a label.Domestic Merchant Returns API: User Guidepage 60“Please note that it is a condition of Label Broker usage that the end-user request Label Broker label delivery prior to any application making a USPS® APIs-Label Broker request.”USPS original USPS watches each merchant's ratio of stored labels to printed ones to enforce this.Domestic Merchant Returns API: User Guidepage 60“It is against the Terms and Conditions to store any labels in the Label Broker application without a consumer request and USPS® monitors the label store-to-print ratio to ensure compliance.”USPS original
When sending a request, the MID must be passed with the specific Merchant Account Code it is associated with.Domestic Merchant Returns API: User Guidepage 79“When sending a request, the MID must be passed with the specific Merchant Account Code it is associated with.”USPS original
Each request must pair the merchant's MID with the Merchant Account Code that MID belongs to. A merchant with several accounts has a MID for each one.Domestic Merchant Returns API: User Guidepage 79“If a merchant has multiple accounts, they will be provided with a MID and Merchant Account ID for each account.”USPS original
You do not have the ability to self-register or make changes to your account, you must work through an administrator.Domestic Merchant Returns API: User Guidepage 31“You do not have the ability to self-register or make changes to your account, you must work through an administrator.”USPS original
A merchant must go through a USPS Merchant Return Administrator to open or change an account, such as its service types and label sizes.Domestic Merchant Returns API: User Guidepage 80“The service types and label sizes can only be changed by a USPS® Merchant Return Administrator.”USPS original
Whether APO/DPO/PTFAS addresses are sent to or returned from these locations they must adhere to international HAZMAT/Dangerous Goods rules, therefore the domestic HAZMAT labels should not be applied.Domestic Merchant Returns API: User Guidepage 56“Whether APO/DPO/PTFAS addresses are sent to or returned from these locations they must adhere to international HAZMAT/Dangerous Goods rules, therefore the domestic HAZMAT labels should not be applied.”USPS original
Hazmat sent to or returned from these addresses must follow international dangerous goods rules. Domestic hazmat labels should not go on these packages.
Only 1 hazmat extra service code is allowed per request.Domestic Merchant Returns API: User Guidepage 53“Only 1 hazmat extra service code is allowed per request.”USPS original
A request must not carry more than one hazmat extra service code.
The hazmat information can’t be bypassed, the customer must declare whether hazmat is included in the package.Domestic Merchant Returns API: User Guidepage 68“The hazmat information can’t be bypassed, the customer must declare whether hazmat is included in the package.”USPS original
On the website, the customer must say whether the package holds hazardous materials, and URL parameters can't answer for them.
If CUBIC is requested, the Container Type is required.Domestic Merchant Returns API: User Guidepage 57“If CUBIC is requested, the Container Type is required.”USPS original
A cubic request must name its container type.
All requests should be made via HTTP GET.Domestic Merchant Returns API: User Guidepage 79“All requests should be made via HTTP GET.”USPS original
Requests should use HTTP GET. Other methods get errors.Domestic Merchant Returns API: User Guidepage 79“Attempts to access the web service using other protocols will result in errors.”USPS original
What goes wrong
A value longer than a tag's maximum gets no error.Domestic Merchant Returns API: User Guidepage 23“If the user enters more than those amounts, an error is not generated.”USPS original The web service keeps the characters up to the maximum and drops the rest.Domestic Merchant Returns API: User Guidepage 23“The web service will simply pass in the characters up to the maximum amount allowed and disregard the rest.”USPS original The cut value can prevent delivery.Domestic Merchant Returns API: User Guidepage 23“This is important since the resulting value could prevent delivery.”USPS original
A failed request gets an error response instead of a label.Domestic Merchant Returns API: User Guidepage 40“If the API does not successfully return a response with the return label and tracking number, an error message response is sent back to the requestor.”USPS original It holds an error number and description from the API, and sometimes an error number from an external system.Domestic Merchant Returns API: User Guidepage 40“Description of error number coming from the USPS® Merchant Return API. … Error number of an error coming from an external system.”USPS original Some errors a merchant meets:
1062: the service type code isn't in the merchant's profile.Domestic Merchant Returns API: User Guidepage 41“1062 Service Type Code isn’t found for this merchant profile.”USPS original1063: the label size isn't one the account allows.Domestic Merchant Returns API: User Guidepage 41“1063 LabelDefinition provided is incorrect. … (The label definition must be one of the label sizes (4X4, 4X6, 3X6, etc.) specified for the Merchant Account.”USPS original1070: the merchant account wasn't found.Domestic Merchant Returns API: User Guidepage 42“1070 Merchant Account wasn’t found in the applications database.”USPS original2000: an address problem, such as an address that needs an apartment or suite number.Domestic Merchant Returns API: User Guidepage 44“2000 Multiple messages are possible. … Address entered was found but more information is needed (such as apartment, suite, or box number) to match to a specific address.”USPS original4001: the MID doesn't belong to the Merchant Account Code.Domestic Merchant Returns API: User Guidepage 44“4001 Authorization error. MID must correspond to MerchantAccountCode.”USPS original4002: the CRID doesn't belong to the Merchant Account Code.Domestic Merchant Returns API: User Guidepage 44“4002 Authorization error. CRID must correspond to MerchantAccountCode.”USPS original4003: a label request for a deactivated account.Domestic Merchant Returns API: User Guidepage 44“A create label attempt was made for a deactivated account {0} 4003”USPS original
The API checks each customer address with a USPS Address Validation API.Domestic Merchant Returns API: User Guidepage 79“The USPS® Merchant Return API uses a USPS® Address Validation API to validate the customers address passed with the request.”USPS original AddressValidation set to false skips that check.Domestic Merchant Returns API: User Guidepage 24“If the AddressValidation tag is true or left blank, the address is validated against WebTools; if it is false, the system bypasses the validation.”USPS original AddressOverrideNotification bypasses an address that lacks a unit number or can't be found, when a valid ZIP Code comes with it.Domestic Merchant Returns API: User Guidepage 79“The parameter can be used to bypass this error and continue without providing the additional address information, provided that a valid ZIP is sent with the request. … The parameter can also be used to bypass addresses that the system cannot find.”USPS original
The API takes no password.Domestic Merchant Returns API: User Guidepage 79“No, there is no password needed with the USPS® Merchant Return API.”USPS original A request's only credentials are the merchant's account identifier and its MID.Domestic Merchant Returns API: User Guidepage 79“The only credentials that need to be sent with the request are the Merchant Account ID and the MID.”USPS original
The label tester's images are valid shipping labels for the merchant code used.Domestic Merchant Returns API: User Guidepage 65“Note that the label images returned are valid shipping labels for the merchant code used.”USPS original
A merchant that generates many unused Label Broker labels may lose its use of Label Broker.Domestic Merchant Returns API: User Guidepage 60“Merchants that generate many unused labels may have their ability to use Label Broker suspended.”USPS original
A website link whose URL parameters cause an error shows the customer a generic error page.Domestic Merchant Returns API: User Guidepage 77“If you as a merchant give your customer a link URL parameters that causes an error, they will see the generic error page.”USPS original The page's HTML source holds the error number in a hidden field.Domestic Merchant Returns API: User Guidepage 77“If you use the url and get the error, then “show page source”, the html will contain a <hidden> tag with the id number of the error.”USPS original
The system rejects misspelled versions of common email domains, such as aol.com and gmail.com.Domestic Merchant Returns API: User Guidepage 10“Update email validation list – reject misspelled variations of aol.com, gmail.com, Hotmail.com, etc.”USPS original
Terms
- USPS Merchant Return web service
- provides free and easy generation of USPS® return labels for customers of merchants enrolled in the USPS® Merchant Return Program.Domestic Merchant Returns API: User Guidepage 12“provides free and easy generation of USPS® return labels for customers of merchants enrolled in the USPS® Merchant Return Program.”USPS original
- USPS Merchant Return website
- Each merchant enrolled is automatically provided (free of charge) a website for their customers to generate return labels.Domestic Merchant Returns API: User Guidepage 67“Each merchant enrolled is automatically provided (free of charge) a website for their customers to generate return labels.”USPS original
- Mailer IdentifierMID, Mailer IDs, Mailer Identification, Mailer Identification Number, USPS Mailer ID
- MID is a unique 6- or 9-digit number that identifies the mailer or the mailer’s client.Publication 199: Intelligent Mail Package Barcode (IMpb) Implementation Guide for Confirmation Services and Electronic Payment Systemspage 474“MID is a unique 6- or 9-digit number that identifies the mailer or the mailer’s client.”USPS original
- Customer Registration IDCRID, Customer Registration Identification Number, Customer Registration Identifier, Customer Identifier, Customer Reference ID, Customer Registration Identifications
- a USPS-generated numeric code of up to 15 digits that uniquely identifies a business at a specific locationCRID ManagementPDF page 1“a USPS-generated numeric code of up to 15 digits that uniquely identifies a business at a specific location”USPS original
- Service Type CodeSTC
- Service Type Codes are designators used to represent USPS classes of mail in conjunction with the type of Extra Service(s) being requested.Publication 199: Intelligent Mail Package Barcode (IMpb) Implementation Guide for Confirmation Services and Electronic Payment Systemspage 476“Service Type Codes are designators used to represent USPS classes of mail in conjunction with the type of Extra Service(s) being requested.”USPS original
- return merchandise authorizationRMA, Return Merchant Authorization
- Return Merchandise Authorization (also known as “package information” or “packageInfo”. Maps to “Customer Reference 1” in the shipping services file.Domestic Merchant Returns API: User Guidepage 12“Return Merchandise Authorization (also known as “package information” or “packageInfo”. Maps to “Customer Reference 1” in the shipping services file.”USPS original
- No InstructionsNOI
- A label without instruction at the bottomDomestic Merchant Returns API: User Guidepage 12“A label without instruction at the bottom”USPS original
- USPS Label Broker serviceUSPS Label Broker
- facilitates shipping for consumers without access to a printer. It allows customers to print labels using a QR Code or Label Broker Label ID at a USPS® Post Office® or via USPS.com.Domestic Merchant Returns API: User Guidepage 60“facilitates shipping for consumers without access to a printer. It allows customers to print labels using a QR Code or Label Broker Label ID at a USPS® Post Office® or via USPS.com.”USPS original
- Proximity Routing
- Proximity Routing is a feature on the Return tool intended for merchants who have multiple accounts that serve as different return locations.Domestic Merchant Returns API: User Guidepage 62“Proximity Routing is a feature on the Return tool intended for merchants who have multiple accounts that serve as different return locations.”USPS original
- PTFAS
- U.S. Possessions, Territories, and Freely Associated StatesDomestic Merchant Returns API: User Guidepage 81“U.S. Possessions, Territories, and Freely Associated States”USPS original
- USPS Address Validation API
- to validate the customers address passed with the requestDomestic Merchant Returns API: User Guidepage 79“to validate the customers address passed with the request”USPS original
Documents
User Guides
- Domestic Merchant Returns API: User GuideJuly 20, 2026
Contacts
For help with the Merchant Returns API, email the Merchant Return Support Team at Merchant.Returns.Support@usps.gov.PostalPro: Merchant Returns API“For more information on the Merchant Returns API, contact support at Merchant.Returns.Support@usps.gov.”USPS originalDomestic Merchant Returns API: User Guidepage 11“For help with any issues regarding the implementation of the Merchant Return Service, you can contact your sales representative directly or the Merchant Return Support Team via email at: Merchant.Returns.Support@usps.gov.”USPS original The team monitors the mailbox daily.Domestic Merchant Returns API: User Guidepage 11“This mailbox is monitored daily, and the team is committed to your success.”USPS original For Label Broker requirements and best practices, contact a USPS account manager or labelbroker@usps.gov.Domestic Merchant Returns API: User Guidepage 60“For more information on the Label Broker, its requirements, and best practices, contact your USPS® account manager or labelbroker@usps.gov.”USPS original
Sources
- Domestic Merchant Returns API: User GuideUSPS original1page 122page 144page 315page 286page 797page 328page 359page 3910page 6411page 2312page 2513page 2714PDF page 2915page 3016page 4117page 4918page 5019page 8020page 6721page 2622page 6823page 5224page 5325page 1026page 8127page 5628page 5729page 5832page 6033page 4334page 6135page 6236page 6337page 4038page 4239page 4440page 2441page 6542page 7746page 11
- PostalPro: Merchant Returns APIUSPS original
- Intelligent Mail® Package Barcode (IMpb) SpecificationUSPS original
- Publication 199: Intelligent Mail Package Barcode (IMpb) Implementation Guide for Confirmation Services and Electronic Payment SystemsUSPS original
- CRID ManagementUSPS original