GuidesAPI DocsLatest NewsStatusCreate Support RequestReturn to zoey.com
Guides

USPS (United States Postal Service)

Suggest Edits

❗️

USPS WebTools API is being retired on 1/25/2026!

You must change over to the new USPS API by that date or risk service interruption! Follow the instructions below to set up your App and get connected to USPS API.

🚧

Follow the updated instructions below to get connected through the USPS API.

As published in the February 6, 2025 Industry Alert, the Web Tools API platform will be retired on January 25, 2026. To avoid any service disruptions, we encourage you to migrate to the new USPS APIs as soon as possible.The functional equivalents of the Web Tools API are available in the USPS API Catalogue: USPS APIs Developer Portal.

How to set up the USPS Shipping Method

  1. In your Control Panel, go to Setting > Shipping Methods.

  2. If USPS is not already added, click on Add Shipping Method, choose the United States Postal Service box, and click Add.


  3. Set Enabled for Checkout to Yes. And then hit Save.

Connecting Zoey to USPS API

📘

To get started, you must first have a USPS Business Account.

We'll be walking through the steps detailed here to set up an App in the USPS Developer Portal.

This app lets Zoey connect to your USPS Account!

  1. Log into the USPS Developer Portal with your business account credentials.

  2. Click on Apps and then hit Add app


  3. Give the app a Name.

  4. Callback URL and Description are not required.

  5. Select the APIs.


  6. Click ADD APP at the bottom to save!

  7. Now on your Apps page, click on the App name of the app you've just created.


  8. Click on the copy icons next to your Consumer Key and Consumer Secret.


  9. Paste those credentials into the Zoey USPS Shipping Method!


  10. Save, and then hit Test Connection!

👍

Your store should now be connected to USPS.

Size and Weight

  1. Set Package Request Type to either:
  • Divide to equal weight (one request) (Recommended)
  • Use origin weight (few requests)
  1. Set Container to the type of packaging usually used to ship products ordered for your store.
  • We recommend using Variable.

  1. Set the Length, Width and Height that best describes the typical package shipped from your store.

  2. Set Machinable to one of the following:

  • Yes: If your typical package can be processed by a machine
  • No: if your typical package must be processed manually
  1. Enter the Maximum Package Weight that you will ship by USPS. By default, this field is set to 70.

🚧

Please consult USPS if you have orders heavier than the default maximum weight. This may require freight shipping.

Handling Fees and Free Shipping

  1. In the Calculate Handling Fee list, select on of the following methods:
  • Fixed: Certain amount per order regardless of size
  • Percent: Percentage of the order total price

  1. In the Handling Fee field, enter either a fixed amount or percentage, depending on which you selected in the Calculate Handling Fee field. These values should be a number, no currency ($) or percentage (%) symbols.

  2. In the Allowed Methods list, select each USPS offered to your customers. The methods you choose will appear during checkout.

  3. Set the Free Method list to the method you want to use for free shipping. You may also select “None.”

  4. Set the Free Shipping with Minimum Order Amount (at the bottom) to one of the following:

  • Enable: To provide free shipping for orders that meet the minimum monetary amount specified. If you enable this, be sure to enter the Minimum Order Amount for Free Shipping.
  • Disable: Free shipping via USPS will not be offered.

Where Shipping is Available

1.The Displayed Error Message text box is preset with a default message. You can either leave this message or you can type the message you want your customers to see if USPS shipping becomes unavailable. This is useful for customers who are trying to checkout with USPS but are not shipping to one of the countries you have available in the following step.

  1. Set Ship to Applicable Countries to one of the following:
  • All Allowed Countries
  • Specific Countries (For this option, you will need to select the Ship to Specific Countries to each country where your customers are allowed to ship by USPS.)
  1. Set Show Method if Not Applicable to one of the following:
  • Yes: To list all USPS shipping methods to customers, regardless of their availability. If they are not permitted to use USPS such as being outside the specified Countries, the Display Error Message text will appear.
  • No (recommended): To list only the methods which are currently available to the customer.

Set Debug to Yes while testing to create a log file with the details of all USPS activity related to your store. You can change this to No at any time.

In the Sort Order field, enter a numeric value to determine the order in which USPS shipping methods appears in the list with other shipping methods at checkout. The highest value is 0, which will be put at the top of the list.

When complete, click the Save button to save your settings.

The most common issues our customers have is not having the correct credentials in place. Make sure you are using your User ID and Password for your USPS Web Tools.

🚧

Products must have weights to calculate USPS rates.

📘

Test Order

We highly recommend placing a test order once complete to assure everything is in place.

Updated 16 days ago