Overview
The Label Broker™ is a service offered by USPS to allow small business and retail customers to present a QR code at the Post Office and have their shipping label printed at the counter. The goal is to make shipping easier for those who may not have access to a printer.
This doc outlines how a merchant can use EasyPost’s APIs to generate a unique QR code for their USPS or USPS Returns shipment. EasyPost will store the shipment’s label with USPS’s secure Label Broker repository and return back a QR code image which can be shared with a consumer. Recommended format of how to present QR code with supporting information can be found in this article. The consumer can then present the QR code image at a USPS Post Office to obtain a shipping label for their package.
Onboarding
EasyPost users will first need a USPS and/or USPS Returns carrier account, which will be used for rating and purchasing shipments.
USPS
Each EasyPost user is automatically provided a USPS account managed by EasyPost. EasyPost users with their own rate cards can also work with their EasyPost account representative to set up a custom USPS account.
USPS Returns
USPS Returns accounts are not provided by default. EasyPost users can work with their EasyPost account representative to set up an account for generating USPS returns shipments.
Generating QR Codes
After a shipment has been created and purchased, a separate request to the /shipment/<shipment_id>/forms endpoint is made to generate a QR code. This will store the shipping label in USPS’s secure Label Broker repository and return a form containing the newly generated QR code image.
Example Request
Request URL: https://api.easypost.com/v2/shipments/<shipment_id>/forms
Request Method: POST
Request Body:
{
"form":{
"type":"label_qr_code"
}
}
Example (cURL):
curl -X POST https://api.easypost.com/v2/shipments/shp.../forms \
-u <YOUR_TEST/PRODUCTION_API_KEY>: \
-d "form[type]=label_qr_code"Request Properties
|
Field Name |
Req? |
Default |
Type |
Example |
Description |
|
form |
|||||
|
form[type] |
Y |
— |
str |
"label_qr_code" |
The type of form to be generated. |
Example Response
The /shipment/<shipment_id>/forms endpoint will return the shipment object with the new form appended to the “forms” element on the shipment. The “form” object will contain the following fields.
Response Properties
|
Field Name |
Type |
Example |
Description |
|
object |
string |
“Form” |
The name of the Easypost object. |
|
id |
string |
“form_123..” |
The Easypost ID of the newly created form object. |
|
created_at |
string |
"2020-06-29T22:02:43Z" |
The timestamp of when the object was created. |
|
updated_at |
string |
"2020-06-29T22:02:43Z" |
The timestamp of when the object was updated. |
|
mode |
string |
“test” |
Indicates whether the object was created in the test or production environment. |
|
form_type |
string |
"label_qr_code" |
The type of form created. |
|
form_url |
string |
“https://easypost-files…..png” |
A URL to the generated form. In this case, it will be a link to the image of your USPS Label Broker QR Code. |
|
submitted_electionically |
bool |
null |
This field is meant for submitting customs information electronically to a customs office for other form types where that’s necessary. It will be null for Label Broker QR codes. |
Success
{
"shipment":{
...
"forms": [
{
"object": "Form",
"id": "form_6fc6bddb972f41eb8b5eebcbd83158a3",
"created_at": "2020-06-29T22:02:43Z",
"updated_at": "2020-06-29T22:02:43Z",
"mode": "test",
"form_type": "label_qr_code",
"form_url": "https://easypost-files/…./abc123.png",
"submitted_electronically": null
}
],
}
}
Error
There are some constraints on what kind of labels can be used with the Label Broker service. These constraints include:
- Label dates must not be in the past
- Shipments cannot require customs forms
- Shipments must not have been refunded
A sample error response is shown below.
{
"error":{
"code":"UNPROCESSABLE_ENTITY",
"message":"ship date must be in the future",
"errors":[]
}
}