Skip to main content

USPS

Calculate USPS domestic shipping rates​

Where to find it: Admin → Shipping → Add Carrier → USPS Domestic

When you'd use this: When you need to offer USPS shipping options to customers within the United States and want real-time rate calculations based on package dimensions, weight, and destination.

What you need first:

  • A USPS account with API access
  • Client ID and Client Secret from the USPS Developer Portal
  • USPS account number
  • Decision on whether to show retail or commercial pricing
  • Account type (EPS or other USPS account classification)

Set it up:

  1. Navigate to Admin → Shipping and add USPS Domestic as a carrier
  2. Enter your USPS Client ID and Client Secret
  3. Enter your USPS account number
  4. Select your price type (RETAIL or COMMERCIAL)
  5. Enter your account type (typically EPS)
  6. Choose which mail classes to offer:
    • Select "ALL" to show all available USPS services, or
    • Specify individual mail classes separated by commas (e.g., PRIORITY_MAIL, GROUND_ADVANTAGE, PRIORITY_MAIL_EXPRESS)
  7. If packages in your catalog don't have dimensions stored, enter fallback dimensions (length, width, height in inches) that will be used for rate calculation
  8. Save the configuration

How it works:

  • CommerceBuild calculates rates by aggregating all items in the cart into a single shipment
  • Package weight is summed across all boxes
  • The system uses the largest dimension from all packages (or your fallback dimensions if package dimensions aren't specified)
  • Rates are requested for next-day mailing
  • The platform filters results to show only the lowest price for each mail class when multiple rate options are returned
  • Rates appear as shipping options during checkout

Troubleshooting:

  • No rates returned — Verify your Client ID and Client Secret are correct and that your USPS API account is active. Ensure you're using credentials from the USPS Developer Portal.
  • Incorrect pricing — Check that your price type (RETAIL vs COMMERCIAL) matches your USPS account type, and that your account number is entered correctly.
  • Missing mail classes — If specific services aren't appearing, verify those mail classes are available for the origin/destination ZIP code combination and package specifications. Check that your mail class filter includes the services you want to offer.
  • Dimension errors — USPS requires length to be the longest dimension. The system automatically sorts dimensions, but if rates fail, verify your fallback dimensions are realistic for your products.