USPS API Integration: Rates, Labels, Address Validation and SCAN Forms
RocketShipIt connects to the USPS APIs (the OAuth JSON APIs at
apis.usps.com that replaced Web Tools) as the usps-rest carrier. You
send one JSON request format, and RocketShipIt handles the OAuth token,
the payment authorization header and USPS's multipart label responses.
With usps-rest you can:
| Action | What it does | USPS API |
|---|---|---|
authenticate |
Exchange your client id and secret for an access token | OAuth 2.0 |
purchasepostage |
Get the payment token that labels are charged to | Payments |
getallrates |
Domestic, international and letter rates | Domestic / International Prices |
submitshipment |
Domestic shipping labels and return labels | Labels |
voidshipment |
Cancel (refund) an unused label | Labels |
createmanifest |
A SCAN form (PS Form 5630) for the day's labels | SCAN Forms |
addressvalidate |
Standardize an address, or look up city and state from a ZIP | Addresses |
timeintransit |
Delivery estimates between two ZIP codes | Service Standards |
track |
Tracking events for a package | Tracking |
Pickups are not available through usps-rest; see
Schedule a Pickup for the carriers that do support
them. International labels and customs forms are not available through
usps-rest yet either (international rates are).
Which USPS carrier to use#
| Carrier | USPS API | Use it for |
|---|---|---|
usps-rest |
The USPS APIs (apis.usps.com, OAuth) |
All new integrations |
usps |
Web Tools XML (ShippingAPI.dll, USERID) |
Existing integrations only |
usps-evs |
eVS on the Web Tools hosts | Existing integrations only |
USPS has retired the Web Tools APIs; see
Carrier API REST Migration Deadlines
for the dates. If you still send "carrier": "usps", the
migration section below covers what changes.
If you would rather buy postage through a reseller account than through your own USPS EPS account, Stamps.com is also supported as a separate carrier.
Credentials#
You need three things from USPS:
- An app on the USPS developer portal (developers.usps.com). Its
consumer key and secret are your
client_idandclient_secret. - An Enterprise Payment System (EPS) account, which postage is
charged to. Its number is
account_number. - Your CRID and MID (Customer Registration ID and Mailer ID) from the USPS Business Customer Gateway. Labels are issued against them.
| Parameter | Value |
|---|---|
client_id |
The app's consumer key |
client_secret |
The app's consumer secret |
scope |
Optional, e.g. "prices labels tracking" |
key |
An access token from authenticate (see below) |
test |
true sends requests to the USPS test environment (apis-tem.usps.com) instead of apis.usps.com |
endpoint |
Optional: overrides the base URL entirely |
Get an access token, and reuse it#
If you send client_id and client_secret without a key, RocketShipIt
fetches a new token before every request. That works, but it is slow, and
USPS throttles clients that request too many tokens. In production, call
authenticate once, keep the token until it expires, and send it as
key:
{
"carrier": "USPS-REST",
"action": "authenticate",
"params": {
"client_id": "abc123",
"client_secret": "def987",
"test": true
}
}
The response has access_token, token_type, scope, issued_at and
expires_in. Pass access_token as key on every other request until
expires_in runs out. REST Authentication covers
the same pattern for every OAuth carrier.
Get a payment token (needed for labels)#
Labels, return labels and voids also need a payment token, which tells
USPS which account to charge. Get one with purchasepostage:
{
"carrier": "USPS-REST",
"action": "purchasepostage",
"params": {
"key": "your-key-from-authenticate-request",
"account_number": "1000005549",
"crid": "94879959",
"mid": "901097701",
"manifest_id": "901097701",
"test": true
}
}
The response's payment_token goes into each submitshipment and
voidshipment request. RocketShipIt uses the same CRID, MID and EPS
account for the shipper, the label owner and the payer.
Rates#
{
"carrier": "USPS-REST",
"action": "getallrates",
"params": {
"test": true,
"key": "your-key-from-authenticate-request",
"price_type": "RETAIL",
"packages": [
{
"weight": 6
}
],
"ship_code": "59759",
"to_code": "90210"
}
}
Without service, RocketShipIt asks USPS for every eligible mail class
(USPS's total-rates search). With service, it rates that one mail class.
Each rate in the response has:
| Field | Meaning |
|---|---|
local_service_code |
The mail class, e.g. USPS_GROUND_ADVANTAGE |
service_code |
The USPS SKU for that price |
zone |
The USPS zone |
billing_weight |
The weight USPS billed (dimensional weight where it applies) |
Rate parameters that matter:
| Parameter | Default | Notes |
|---|---|---|
price_type |
RETAIL |
COMMERCIAL or CONTRACT for business pricing |
account_type |
e.g. EPS, with account_number, to get your account's prices |
|
service |
all mail classes | A USPS mail class (see below) |
rate_indicator |
SP |
Single piece. Use PA for Priority Mail Express single piece, FE/FS/FB for flat rate, CP for cubic |
processing_category |
NON_MACHINABLE |
MACHINABLE or NONSTANDARD. USPS now treats NON_MACHINABLE as NONSTANDARD, so send MACHINABLE for ordinary small boxes |
packaging_type |
letter switches to USPS letter rates |
|
ship_date |
today | YYYY-MM-DD |
International rates: send a to_country other than US, with the
destination postal code in to_code_extended if the country uses one. RocketShipIt then uses the
USPS international prices API. Extra services go in addons as USPS's
numeric extra service codes, and insured_value sets the item value.
Missing package dimensions default to 5 × 5 × 5 inches for domestic rates. USPS prices large and light parcels by dimensional weight, so send real dimensions if you have them.
Mail classes#
service is passed to USPS unchanged as the mail class:
service |
Mail class |
|---|---|
USPS_GROUND_ADVANTAGE |
USPS Ground Advantage |
PRIORITY_MAIL |
Priority Mail |
PRIORITY_MAIL_EXPRESS |
Priority Mail Express |
PARCEL_SELECT |
Parcel Select (the label default) |
PARCEL_SELECT_LIGHTWEIGHT |
Parcel Select Lightweight |
MEDIA_MAIL |
Media Mail |
LIBRARY_MAIL |
Library Mail |
BOUND_PRINTED_MATTER |
Bound Printed Matter |
USPS_CONNECT_LOCAL |
USPS Connect Local |
The full list, and how it maps from the old Web Tools codes such as
PRIORITY and EXPRESS, is in
Shipping Service Codes.
Shipping labels#
{
"carrier": "USPS-REST",
"action": "submitshipment",
"params": {
"key": "your-key-from-authenticate-request",
"payment_token": "key-from-PurchasePostage-response",
"packages": [
{
"weight": 4.3,
"length": 7,
"width": 7,
"height": 8,
"reference_value": "reference1",
"reference_value2": "reference2"
}
],
"service": "USPS_GROUND_ADVANTAGE",
"shipper": "RocketShipIt",
"ship_contact": "John Doe",
"ship_addr1": "123 Main St",
"ship_city": "Whitehall",
"ship_state": "MT",
"ship_code": "59759",
"to_name": "John Doe",
"to_addr1": "940 Presidio Ave",
"to_addr2": "#103",
"to_city": "San Francisco",
"to_state": "CA",
"to_code": "94115",
"image_type": "PDF",
"label_stock_type": "4X6LABEL",
"test": true
}
}
The response has the tracking_number (also returned as shipment_id,
which voidshipment takes), charges (postage plus any USPS fees) and the
label in packages[0].label, with its MIME type in label_format.
reference_value and reference_value2 print on the label as customer
references.
usps-rest labels are domestic only.
Label format and size#
| Parameter | Default | Values |
|---|---|---|
image_type |
PDF |
PDF, PNG, TIFF, JPG, GIF, SVG, ZPL203DPI, ZPL300DPI |
label_stock_type |
4X5LABEL |
4X6LABEL, 4X5LABEL, 4X4LABEL, 6X4LABEL, 2X7LABEL |
receipt_option |
SAME_PAGE, SEPARATE_PAGE, NONE |
Two things catch people out:
- For ZPL, send
ZPL203DPIorZPL300DPI, notZPL. The value is passed to USPS unchanged, and USPS only accepts the DPI-specific names. See Thermal Printing. - The default label size is 4×5. For standard 4×6 thermal stock, send
"label_stock_type": "4X6LABEL".
Any image_type other than PDF also sets receipt_option to NONE.
Packages, weights and addresses#
- Weight is in pounds, always;
weight_unitis not used byusps-rest. For 8 oz, send0.5. - Dimensions are in inches.
length_unit: "CM"is converted for you. - One package per request. Only the first entry in
packagesis used for rates and labels; send a request per package. - Validate addresses first. RocketShipIt asks USPS to accept the
addresses as given rather than reject them, so a bad address produces
a label rather than an error. Use
addressvalidatebefore shipping. to_codecan include the ZIP+4 (94115-1234), or send the +4 asto_code_extended.hold_at_location: trueholds the package at the destination post office.- A one-word
to_namewith noto_companyis sent as the company name. Send both first and last name for a person.
Return labels#
Set return_code to PRINT_RETURN_LABEL and use a return mail class
as service, such as USPS_GROUND_ADVANTAGE_RETURN_SERVICE or
PRIORITY_MAIL_RETURN_SERVICE. A payment_token is still required. See
Return Labels for every carrier's return options.
Void a label#
{
"carrier": "USPS-REST",
"action": "voidshipment",
"params": {
"key": "your-key-from-authenticate-request",
"payment_token": "key-from-PurchasePostage-response",
"shipment_id": "9205500000000000000000",
"test": true
}
}
SCAN forms#
A SCAN form (PS Form 5630) lets the carrier scan one barcode for the
whole day's packages instead of each label. Create one with
createmanifest and the tracking numbers to include:
{
"carrier": "USPS-REST",
"action": "createmanifest",
"params": {
"key": "your-key-from-authenticate-request",
"shipment_ids": ["9205500000000000000000", "9205500000000000000001"],
"shipper": "RocketShipIt",
"ship_addr1": "123 Main St",
"ship_city": "Whitehall",
"ship_state": "MT",
"ship_code": "59759",
"test": true
}
}
ship_code is also the ZIP of the entry facility. ship_date defaults
to tomorrow for SCAN forms. The form comes back as a PDF in
documents, with the manifest number as its code. See
End of Day for how manifests work across carriers.
Address validation#
addressvalidate standardizes a US address with the USPS Addresses API:
{
"carrier": "USPS-REST",
"action": "addressvalidate",
"params": {
"key": "your-key-from-authenticate-request",
"to_addr1": "940 Presidio Ave",
"to_addr2": "#103",
"to_city": "San Francisco",
"to_state": "CA",
"to_code": "94115"
}
}
The response includes the corrected address, whether it is residential,
and USPS's delivery point checks (DPV confirmation, CMRA, vacant, business,
central delivery point). Corrections come back as warnings. Send only
to_code and you get the city and state for that ZIP instead. More in
Address Validation.
Delivery estimates and tracking#
timeintransit needs only ship_code and to_code and returns USPS's
delivery estimates; see
Time in Transit.
track takes a tracking_number and returns USPS's tracking events; see
Tracking for the request, the response and test numbers.
Errors#
USPS errors come back in data.errors, each with a code (USPS's error
title and the parameter it refers to) and a description. Authentication
failures appear there too. Errors from the international and letter
price APIs are the exception: they are returned in meta.error_message.
Carrier Errors covers the response format.
Moving from Web Tools to usps-rest#
Web Tools ("carrier": "usps") |
USPS APIs ("carrier": "usps-rest") |
|---|---|
username (USERID), and password for tracking |
client_id + client_secret, or key |
| No test switch for most calls | test: true uses apis-tem.usps.com |
| Labels without postage (or eVS for postage) | Postage-paid labels charged to your EPS account via payment_token |
PRIORITY, EXPRESS, MEDIA, … |
PRIORITY_MAIL, PRIORITY_MAIL_EXPRESS, MEDIA_MAIL, … |
| International labels and customs | Not yet: international rates only |
The rest of the request (ship_*, to_*, packages) stays the same, so
most integrations change only the carrier, the credentials, the service
codes and the label step (add purchasepostage and payment_token).