Stamps.com (USPS) Carrier Guide

Stamps.com with ShipEngine provides access to USPS domestic and international shipping services for packages originating in the United States.

This guide provides developers an overview of shipping services that Stamps.com offers and the service codes that you will use to create these shipments.

Connect Your Account

ShipEngine API allows you to connect your Stamps.com account programmatically without logging in to the ShipEngine API dashboard. This is useful if you have wrapped a custom UI around the ShipEngine API toolset and want to add or disconnect existing carrier accounts without exposing your end users to the API dashboard.

These APIs can be used in parallel with the ShipEngine Partner APIs to programmatically create new ShipEngine users, and then connect existing Stamps.com accounts all via the API without logging into a dashboard. Together these APIs empower you to completely white-label the ShipEngine experience for your end users.

Continue below for instructions on how to programatically connect Stamps.com using the ShipEngine API.

For instructions on connecting a Stamps.com via the ShipEngine dashboard, go to our Stamps.com help article.

Stamps.com Account Information Model

Property	Description
`username`	string, required
`password`	string, required

Example POST Call

POST /v1/connections/carriers/stamps_com

1
2
3
4
5
6
7
8
9
POST /v1/connections/carriers/stamps_com HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "username": "myusername",
  "password": "123456789",
}

Example Response

1
2
3
{
  "carrier-id": "se-1234567"
}

Stamps.com Service Details

Stamps.com includes both USPS domestic and international services. Additionally, you can also access GlobalPost international services with a Stamps.com account.

USPS Domestic Services

Service	Transit Time	Maximum Dimensions (LxWxH)	Max Weight	Service Code
USPS Ground Advantage*	2-5 days	22" x 18" x 15"	70 lbs	`usps_ground_advantage`
USPS Priority Mail	1-3 days	varies by package type	70 lbs	`usps_priority_mail`
USPS Priority Mail Express	1-2 days	L x 2xW x H cannot exceed 108"	70 lbs	`usps_priority_mail_express`
Media Mail	2-9 days	L x 2xW x H cannot exceed 108"	70 lbs	`usps_media_mail`

*In 2023, USPS Ground Advantage replaced both USPS First Class Package and Parcel Select Ground services.

USPS International Services

Service	Transit Time	Maximum Dimensions	Max Weight	Service Code
USPS First Class Mail Intl	7-21 days	L x 2xW x H cannot exceed 136"	64 oz	`usps_first_class_mail_international`
USPS Priority Mail Intl	6-10 days	L x 2xW x H cannot exceed 108"	70 lbs	`usps_priority_mail_international`
USPS Priority Mail Express Intl	3-5 days	L x 2xW x H cannot exceed 108"	70 lbs	`usps_priority_mail_express_international`

GlobalPost Services

For all GlobalPost services, transit time will vary depending on the destination country.

Service	Max Weight	Service Code
GlobalPost Economy Intl	4.4 lbs	`globalpost_economy`
GlobalPost Standard Intl	70 lbs	`globalpost_priority`
GlobalPost Plus	66 lbs	`gp_plus`
GlobalPost SmartSaver Economy Intl	4.4 lbs	`globalpost_economy_smart_saver`
GlobalPost SmartSaver Standard Intl	70 lbs	`globalpost_priority_smart_saver`
GlobalPost Plus SmartSaver	66 lbs	`globalpost_plus`

USPS Package Types

Package Name	API Code	Package Details
Medium Flat Rate Box	medium_flat_rate_box	Domestic and international
Flat Rate Envelope	flat_rate_envelope	Domestic and international
Small Flat Rate Box	small_flat_rate_box	Domestic and international
Large Flat Rate Box	large_flat_rate_box	Domestic and international
Flat Rate Padded Envelope	flat_rate_padded_envelope	Domestic and international
Flat Rate Legal Envelope	flat_rate_legal_envelope	Domestic and international

Example Label

Return Services

Return services are supported for USPS domestic shipments.

Adding Shipment Insurance

Stamps.com supports adding insurance to your shipments. Review the Parcel Insurance page for details on adding shipment insurance with ShipEngine.

USPS Advanced Options

Advanced Options are a shipment property used to communicate carrier add-ons used, such as "Saturday Delivery" or "Dangerouse Goods". Carrier Options are available dynamically at the List Carriers endpoint.

Option	Name	Default Value	Description
Non Machinable	`non_machinable`	`false`	Indicates that the package cannot be processed through USPS sorting machines.
Dangerous Goods	`dangerous_goods`	`false`	Indicates this shipment contains dangerous goods

Additional Carrier Details

Signature and Adult Signature confirmation types not supported for international shipments.
Label messages are supported for domestic shipments only.
Voiding labels is supported, but must be done within 28 days of label creation.
USPS pickups can only be scheduled for one day in advance. For example, if you schedule a pickup on the 5th for the 7th, the pickup date scheduled by Stamps.com will be the 6th.
If you plan to create a USPS SCAN form, you must manifest your day's shipments by 9pm local time.
All international shipments using USPS First-Class Mail Int'l, Priority Mail Int'l, or Priority Express Int'l services will use Global Advantage Program labels by default.

Paperless Services

USPS supports paperless labels with their services. This means you can generate a QR code for your customer and they can take that QR code to be scanned at participating USPS locations, who will then print the label for them.

Review our paperless labels page for details on how to generate a QR code instead of a printable label. Please note that while USPS does support the older qr_code value for the display_scheme property, we recommend using the newer paperless_label value, as the qr_code value will eventually be deprecated.

Example QR Code

Customer Communications

Using paperless labels might be a new experience for your customers. The USPS suggests sending out an email with the QR code label to help educate your customer on what they need to do to ship their package.

The email containing the QR Code should also include instructions on how to find participating USPS Post Offices by visiting https://tools.usps.com/find-location.htm?locationType=po&serviceType=lbroretail&address=18702, where the value of the address parameter is customer's ZIP Code (such as 18702 in this example). The USPS Retail Associate at that location's Retail Counter will scan the QR Code and print the shipping label, affix it to the package, and provide a receipt.

If the customer has access to a printer, they may choose instead to print the label directly at https://tools.usps.com/label-broker.htm?LabelID=XYZZYPJK&zip=18702, where XYZZYPJK is the Label ID returned by ShipEngine, and 18702 is the ship_from postal_code.

You are now ready to create shipments using Stamps.com via ShipEngine!