# USPS from ShipStation

USPS from ShipStation offers domestic and international shipping services to ShipStation API accounts based in the US.

This guide provides developers with the details needed to build USPS from ShipStation shipping capabilities into your ShipStation API workflows.

ShipStation API also allows you to connect your own existing Stamps.com account to use the USPS services and rates available through that account in ShipStation API. The connection process and some usage details are different than those for USPS from ShipStation. For details about connecting and using your own Stamps.com account with ShipStation API, see our [USPS (Stamps.com) Carrier Guide](/apis/docs/carriers/stamps-usps-guide).

## Requirements

`carrier_code`: `usps_walleted`

* A ShipStation API account based in the US.
* ShipStation Carriers must be activated for the account and have a positive account balance to create labels. See our [Using ShipStation Carriers page (ShipEngine guide)](/apis/shipengine/docs/carriers/setup) for details about activating it in your account.
* A weight value is required for all shipments.


## Connect Your USPS from ShipStation Account

You can connect a USPS from ShipStation account using the POST method to the `/v2/connections/carriers/` endpoint, or via the ShipStation dashboard.

For instructions on connecting USPS from ShipStation via the dashboard, go to our [USPS help article](https://help.shipstation.com/hc/en-us/articles/360025856252-USPS).

### Connect via Endpoint

`carrier_code`: `usps_walleted`

**POST /v2/connections/carriers/:carrier_code**

## Disconnecting Your USPS from ShipStation Account

You can disconnect a USPS from ShipStation carrier using the DELETE method with the `/v2/connections/carriers/` endpoint, or via the ShipStation dashboard.

For instructions on disconnecting USPS from ShipStation via the dashboard, go to our [USPS help article](https://help.shipstation.com/hc/en-us/articles/360025856252-USPS).

**DELETE /v2/connections/carriers/:carrier_code/:carrier_id**

## Rates

USPS from ShipStation supports [rate shopping](/apis/shipengine/docs/rates/rates) with ShipStation API.

## Service Details

The tables below provide the services available with USPS from ShipStation. Please note that carriers may update their available services at any time. To ensure you are always using valid services, you can use the dynamic carrier endpoint to retrieve services:

**GET /v2/carriers/:carrier_id/services**

### 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.*

> **IMPORTANT: USPS International Shipping Updates**
**International Mail Service Suspensions - Effective: March 3, 2026**
The Postal Service™ is [temporarily suspending acceptance of items destined to the following countries](https://about.usps.com/newsroom/service-alerts/international/), due to logistics impacts resulting from the conflict in the Middle East.
Please refrain from mailing items addressed to the countries listed here until further notice:
**Algeria, Armenia, Bahrain, Djibouti, Eritrea, Iran, Iraq, Israel, Kuwait, Libya, Madagascar, Oman, Pakistan, Qatar, Seychelles, Syria, Tanzania, United Arab Emirates**​​
**HS Codes Required**
As of **September 1, 2025**, the [U.S. Postal Service will require](https://about.usps.com/postal-bulletin/2025/pb22682/pb22682.pdf) **all international commercial shipments** to include a [six-digit Harmonized System (HS) code](https://www.trade.gov/harmonized-system-hs-codes) on customs declarations **for each item**, regardless of mail class.
The HS code system, created by the [World Customs Organization](https://www.wcoomd.org/en/topics/nomenclature/overview/what-is-the-harmonized-system.aspx), is used by customs authorities worldwide to classify goods and assess tariffs. This update aligns USPS mailing standards with new **Universal Postal Union (UPU) regulations**, also taking effect Sept 1, requiring all member countries to enforce six-digit HS codes for commercial goods.
For a full list of Harmonization Codes, use the [Harmonized Tariff Schedule search](https://hts.usitc.gov/).


### 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` |


> **NOTE:**
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](https://help.shipstation.com/hc/articles/4406871538459#UUID-06961ed6-bd35-7f22-eee2-06e0c5cfd8b8) labels by default.


### GlobalPost Services

GlobalPost international services are also available under the USPS from ShipStation carrier, as USPS is the official first-mile carrier for GlobalPost shipments originating in the US. 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` |


### Return Services

USPS from ShipStation supports return labels using any domestic services. Review the [Return Labels page (ShipEngine guide)](/apis/shipengine/docs/shipping/returns) for details on creating return labels with ShipStation API.

### Packages

The following [carrier package types (ShipEngine guide)](/apis/shipengine/docs/shipping/carrier-packaging) are available for USPS services. To retrieve the most current package types dynamically, use:

**GET /v2/carriers/:carrier_id/packages**

| 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 |


### Adding Shipment Insurance

USPS from ShipStation supports adding either carrier insurance or Parcelguard insurance (but not both) to shipments created with ShipStation API.

Review the [Parcel Insurance page (ShipEngine guide)](/apis/shipengine/docs/shipping/insurance) for details about adding shipment insurance with ShipStation API.

## Troubleshooting USPS Address Validation Errors

To comply with updated USPS API standards, all shipping label requests now require complete "From" and "Return To" address objects (including Street Address, City, State, and ZIP Code). Passing only a ZIP Code will result in a validation error.

### How to Fix This Issue

Identify your integration method below and follow the corresponding solution:

**Scenario A: Using the Web/UI Portal**

**Cause:** Your shipping origin or return address is incomplete or differs from your primary account settings.

**Solution:** Navigate to your Account Settings and update your primary shipping and return addresses to include complete, permanent street details.

**Scenario B: Using Direct API / SWSIM Integration**

**Cause:** Your current API payload passes only a ZIP code instead of full address objects.

**Solution:** Update your integration payload to include complete From and Return To address objects (including Street Address, City, State, and ZIP) when requesting a label.

## Label Support

* Label sizes: 4" x 6"
* Label formats: PDF, ZPL


### Label Reference Fields

USPS from ShipStation supports adding [custom label messages (ShipEngine guide)](/apis/shipengine/docs/labels/messages) to all three label reference fields when using domestic services. International services do not support label messages.

### Multi-Package Labels

USPS services do not support [multi-package shipping labels (ShipEngine guide)](/apis/shipengine/docs/shipping/multi-package) at this time.

### Label Branding

USPS from ShipStation supports adding a custom label image to your labels. See our [Create Custom Shipping Labels page (ShipEngine guide)](/apis/shipengine/docs/labels/branding) for details.

### Voiding Labels

USPS supports [voiding labels (ShipEngine guide)](/apis/shipengine/docs/labels/voiding) with ShipStation API, but it must be done within 28 days of label creation and the label cannot have been scanned by the USPS.

### Paperless Labels

USPS from ShipStation supports [paperless labels (ShipEngine guide)](/apis/shipengine/docs/labels/paperless). 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 (ShipEngine guide)](/apis/shipengine/docs/labels/paperless) page for details on how to generate a QR code instead of a printable label. Use the `paperless` value for the `display_scheme` property.

### Customs Declarations

Customs declarations for GlobalPost and GAP labels are submitted to the carrier electronically. See our [International Shipments page (ShipEngine guide)](/apis/shipengine/docs/shipping/international) for details about shipping internationally via ShipStation API.

## Delivery Confirmation

| Confirmation Type | API Code | Description |
|  --- | --- | --- |
| No confirmation | `none` | Default. When no delivery confirmation is requested. |
| Delivery | `delivery` | For general delivery confirmation. |
| Signature | `signature` | A signature is required to complete the delivery. Not supported for international shipments. |
| Adult Signature | `adult_signature` | An adult signature is required for the shipment to be delivered. |
| Restricted delivery | `restricted_delivery` |  |


Signature and Adult Signature [confirmation types (ShipEngine guide)](/apis/shipengine/docs/shipping/delivery-confirmation) are not supported for international shipments.

See our [Delivery Confirmation page (ShipEngine guide)](/apis/shipengine/docs/shipping/delivery-confirmation) for more details about using the `confirmation` property.

## Advanced Options

USPS from ShipStation supports certain [advanced options (ShipEngine guide)](/apis/shipengine/docs/carriers/advanced-options), which you can add to the `shipment` object when creating a shipment or label.

To ensure you always have the most up-to-date information about a carrier's advanced options, use:

**GET /v2/carriers/:carrier_id/options**

| Option | Name | Default Value | Description |
|  --- | --- | --- | --- |
| Non Machinable | `non_machinable` | `false` | Indicates that the package cannot be processed through USPS sorting machines. |


### Dangerous Goods

USPS from ShipStation does not support shipping dangerous goods.

## Manifests

USPS from ShipStation supports creating manifests (called SCAN forms) via ShipStation API. If you plan to create a USPS SCAN form, you must manifest your day's shipments by 9pm local time.

See our [Manifests page (ShipEngine guide)](/apis/shipengine/docs/shipping/manifests) for more details about creating manifests with ShipStation API.

## Scheduling Pickups

USPS from ShipStation supports scheduling pickups via ShipStation API. Pickups can only be scheduled 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.

See our [Schedule a Carrier Pickup page (ShipEngine guide)](/apis/shipengine/docs/shipping/pickups) for more details about scheduling pickups using ShipStation API.

## Service Points (PUDO)

USPS does not support shipping to [service points (ShipEngine guide)](/apis/shipengine/docs/pick-up-drop-off/pudo-intro).

## Tracking

USPS from ShipStation supports receiving tracking updates. Review our ​[Track a Package guides​ (ShipEngine guide)](/apis/shipengine/docs/tracking/tracking)​ for details on tracking with the ShipStation API.

## File a Claim

For damage, loss, or other issues with USPS from ShipStation shipments, you must file claims directly with USPS. Unlike some other ShipStation Carriers (such as UPS from ShipStation), ShipStation Support does not manage the claims process for USPS shipments.

To file a claim for a USPS shipment, visit the [USPS Help Center](https://www.usps.com/help/claims.htm) for information about:

- Claim types and eligibility
- Required documentation
- Filing deadlines
- Claims process


## Package Intercept

USPS from ShipStation shipments require direct interaction with USPS for package intercept or redirect requests. ShipStation Support does not assist with USPS package intercept requests.

To request a package intercept or redirect for a USPS shipment, submit your request directly to USPS using their [Package Intercept service](https://www.usps.com/manage/package-intercept.htm).

> **NOTE:**
USPS charges a fee for Package Intercept services. Review the USPS Package Intercept page for current fees, eligibility requirements, and service limitations.