USPS Logo USPS Module

Offer real-time rates to customers, generate bulk order labels in one click, allow customers to track their orders, and more.

Developed by Zack Hussain @ zhmedia.ca

  1. USPS & EasyPost Overview
  2. Requirements
  3. Installation & Configuration
  4. Notice for PrestaShop 1.6.0.0 to 1.7.0.5
  5. Rates
  6. Boxes & Box Packing
  7. USPS Flat Rate Boxes
  8. Rate Discount Rules & Free Shipping
  9. Delivery Time Estimates
  10. Shipping Estimator
  11. Addresses
  12. Labels
  13. Return Labels
  14. Bulk Labels
  15. Scan Forms / Manifests
  16. Groups
  17. Tracking
  18. Auto-Update Order Status on Delivery
  19. Smart Caching
  20. Troubleshooting
  21. Common Error Messages
  22. Hook Related Installation Errors
  23. Changelog

USPS & EasyPost Overview

This module uses the USPS Web Tools API to fetch front-office rates, and the EasyPost service to purchase and print USPS labels.

Why use both services instead of one or the other? The USPS Web Tools API does not provide permissions for creating labels to low-volume businesses. Services like EasyPost have a partnership with USPS that allows them to generate a USPS account for you with label permissions and a high-volume discount (commercial plus pricing).

The module uses USPS Web Tools API instead of EasyPost to fetch front-office rates. This is because—at the time of this writing—each rate fetched from EasyPost counts towards your 50,000 free packages per year limit. These rate fetches can add up quickly, and using USPS Web Tools ensures you are less likely to reach your EasyPost quota.

This module is not affiliated in any way with EasyPost, the EasyPost service was chosen due to its pricing and ease of integration.

Requirements

Before installing the module, you will need:

  1. A “USPS Web Tools API” account: https://www.usps.com/business/web-tools-apis/welcome.htm
  2. An EasyPost account with a payment method on file: https://www.easypost.com/signup
  3. Your website’s PHP version must be at least 5.4.0

Installation & Configuration

Installation

  1. Go to the Modules page.
  2. Find the “USPS” module and click Install
  3. If you don’t see the module, click Upload a Module and upload the module .zip file that you were provided with.

The module must then be configured with your USPS Web Tools API username, your EasyPost Production and Test API keys, and your US origin address.

Configuration

  1. Go to Modules page.
  2. Find the “USPS” module and click Configure.
  3. Enter your USPS Web Tools API username.
  4. Enter your EasyPost Production and API keys (found here: https://www.easypost.com/account/api-keys)
  5. Go to the “Addresses” tab of the module configuration and edit the default address to your own.

It’s strongly recommended to go through the configuration page and read what each setting does to ensure the module works exactly how you want it to.

It’s also recommended to configure default label values in the Default Label Values by Zone tab so that you don’t have to set them for every single label you create.

Notice for PrestaShop 1.6.0.0 to 1.7.0.5

If you are seeing “hook” or “override” related errors while installing, please see the “Hook Related Installation Errors” section below.

Possible front office Order Tracking bug

In PS 1.7.0.0 to 1.7.0.5, you may need to alter one line of your theme to get the front-office order tracking feature to display properly - add “nofilter” to the following hook:

  1. Open the file {your_theme}/templates/customer/order-detail.tpl
  2. Replace {$HOOK_DISPLAYORDERDETAIL} with {$HOOK_DISPLAYORDERDETAIL nofilter} if it is not already that way.

Rates

The checkout rates can be configured by selecting the carriers you wish to enable in the Rates preferences. Enabling carriers in the Rates preferences will install them in your back-office automatically (Shipping > Carriers).

The Rates preferences include various settings for Box Packing which are explained in the next section.

If you are not seeing the rates after enabling the carriers, please see the Troubleshooting section.

Boxes / Box Packing

The module uses your custom box dimensions to calculate shipping rates in the front-office.

You can add unlimited boxes into the module from the configuration page in the Boxes tab by clicking the “+” button. The more boxes you add, the more accurate the rates will be.

Box Packing Algorithm

The module uses a sophisticated box packing algorithm to determine the smallest box(es) that will fit all the products in the customer’s cart; it can split the products into multiple boxes when the cart has more products than your largest box can fit.

Technical Example:

Possible Issue: If the cart contains a product that does not fit in any of your boxes, the module will be unable to pack the products into your boxes and will revert to using (1) of the largest box you have. The module will display a warning on the configuration page if any of your products are too large for your largest box.

USPS Flat Rate Boxes

USPS Flat Rate Boxes (and envelopes) allow you to offer flat rate USPS prices to customers at checkout, as well as purchasing flat rate labels, for certain service methods. They can be found in the “USPS Flat Rate Boxes” tab of the module configuration page.

Flat Rates at Checkout

The module will use the USPS Flat Rate Boxes the same way as your regular custom Boxes (see Boxes & Box Packing), i.e. it will attempt to pack a cart’s products inside them.

If the module determines that the smallest box that can fit the cart’s products is a USPS Flat Rate Box, the module will fetch a flat rate for that cart if available.

Tip: If you intend on using flat rates, avoid adding any custom boxes that are marginally smaller than any particular USPS Flat Rate Box. This will prevent situations where the measurements between the two boxes are so close that the module might choose a custom box over a flat rate box.

Flat Rate Labels

You can create a flat rate Label by selecting one of the USPS Flat Rate Boxes in the “Box” field of the label form.

If no flat rate exists for the desired USPS service method and destination, a regular Label will be created instead.

Rate Discount Rules & Free Shipping

You can configure discounts for each USPS carrier in the Rate Discount Rules preferences.

Each carrier can have a percentage, dollar amount, or Free Shipping discount applied to it. e.g. Free Shipping when Order Total Is At Least USD$100.00 tax excl.

You can only create one discount rule per carrier for each Shop.

If you require more flexible ranges, consider using PrestaShop’s built-in carrier system using the following example as a starting point:

In this example we will offer free shipping for only US on orders above $100.

  1. Create a new zone called “United States” (International > Locations > Zones menu).
  2. Edit the country United States and change its zone from North America to United States (International > Locations > Countries menu). Zones are only used for Shipping, so update any other carriers with the new Zone if needed.
  3. Create a new carrier called “Free Shipping” (or any other name).
  4. Set its Billing to ‘According to total price’.
  5. Set its Out-of-range behavior to ‘Disable Carrier’.
  6. Set its range to ‘>= 100’ and ‘< 999999’.
  7. Deselect all zones except United States, and set United States to 0.00. This will display free shipping for US orders when the order total is above $100.00. To disable one or more carriers when free shipping is enabled, do the following for each carrier.
  8. Edit a USPS carrier.
  9. Set its Billing to ‘According to total price’.
  10. Set its Out-of-range behavior to ‘Disable Carrier’.
  11. Set its range to ‘>= 0’ and ‘< 100’. This will disable that particular carrier when the order total is above $100.00. Repeat for each carrier you wish to disable.

Delivery Time Estimates

To display delivery time estimates on the checkout page (e.g. 3 Business Days), enable Show Delivery Time Estimates in the Rates preferences.

Notice for PrestaShop 1.7+

In PrestaShop 1.7+, you must add one line of code on your theme for this feature to work. Use the following instructions to enable delivery times.

  1. Open the file at /themes/(your_theme_name)/templates/checkout/_partials/steps/shipping.tpl
  2. Near the top, locate the following line: {block name='step_content'}
  3. Immediately after that line, paste the following code: {if isset($delay_times)}{assign var=delivery_options value=$delay_times}{/if}

Shipping Estimator

The Shipping Estimator allows guests/customers to estimate shipping fees on the Product and Cart pages. To display the Shipping Estimator, enable the Enable Shipping Estimator setting in the Rates preferences.

Addresses

Configure your addresses in the Addresses tab of the module configuration page.

Select one address as your Origin address to be used as the origin for front-office rate calculation.

If you have more than 1 address, you can select an Origin address by editing an Address and setting “Set as Origin” to “Yes”, or by clicking the red “X” icon next to an address.

Your addresses will also be available to be selected for any of the following:

  1. The shipping label “From” address.
  2. The return label “Receiver” address.

Labels

You can create shipping labels on any Order page or in the “USPS > Create Label” page in the sidebar.

Shipments

Creating a label will also create a Shipment in the “USPS > View Shipments” page where you can re-print, cancel/refund, or track previously created labels.

You can view real-time rates for your selected label settings by clicking “Update Rate” in the label form.

Shipments created for an Order can also be viewed on the Order’s page under the “View Shipments” tab.

Documents/Forms

Some labels, such as international labels, will have an associated Document that will be created along with the label (commercial invoice, high value report, etc). These documents typically need to be affixed to the parcel.

You can choose to include any associated Documents along with the label in the same PDF in the Labels preferences.

Shipments with associated Documents will have a Document icon under the “Docs?” column of the “View Shipments” list.

You can re-print a Document for a shipment from the “USPS > View Shipments” page, or from an Order’s page under the “View Shipments” tab, by clicking the drop-down button for a Shipment that has associated documents and clicking “Print Documents”.

Default Label Values by Zone

You can set default values for most of the label fields for different shipping Zones in the Default Label Values by Zone preferences.

Default Label Values are used to pre-populate an Order’s label form based on the Zone of its shipping address.

Example: You want every label to require a Signature on delivery, so you set “Delivery Confirmation” to “Signature” in the Default Label Values for All Zones.

By default, the All Zones default label settings will be used for every order. Any other Zone settings that you configure, e.g. North America, will override the All Zones settings for orders with e.g. North American shipping addresses.

Example: You want to buy Insurance for every North American label, but you don’t want to buy Insurance for labels going anywhere else. You set “Insurance Amount” to “0.00” for “All Zones” and set “Insurance Amount” to your desired insurance amount, e.g. “100.00”, for “North America”.

You can create new Zones in the “International > Locations > Zones” menu.

If you want to set Default Label Values for only the US, you can create a new Zone called “United States” and edit the Country’s Zone from “North America” to “United States” in the “International > Locations > Countries” menu.

Refunds

You can cancel a Shipment and request a Refund from USPS for any label within 30 days of generation that is not yet in transit.

You can refund a Shipment by locating it in the “USPS > View Shipments” page, clicking the drop-down arrow next to it, and clicking “Cancel/Refund Label”.

Refunds can take up to 15 business days for USPS to process.

Preferences

You can choose to auto-update Orders to a custom order status and auto-update an Order’s tracking number on label creation in the Labels preferences.

You can choose to automatically Send Tracking Emails on label creation in the Labels preferences. This feature uses your store’s “In Transit” email template (the same template used when manually updating an order’s tracking number) and contains a tracking link based on the carrier’s “Tracking URL” found in the Shipping > Carriers settings. Only supported in PrestaShop versions 1.7.1.0 and up.

If shipping over $2500 of goods internationally, you will need to have an Automated Export System (AES) Internal Transaction Number (ITN) and enter it in the Labels preferences. ITN will look like “AES X20120502123456”. To get an ITN, go to the AESDirect website. An ITN is required for any international shipment valued over $2,500 and/or requires an export license unless exemptions apply. The module will automatically populate this value in the EEL/PFC customs field based on the cart value.

PDFs for created labels can be found in /modules/zh_uspslabels/pdf/shipping folder.

Return Labels

You can create a return label for any order that has a US shipping address.

PDFs for created return labels can be found in /modules/zh_uspslabels/pdf/returns folder.

Bulk Labels

The Bulk Labels feature allows you to create labels for multiple orders at once with powerful customization options to optimize your workflow.

Overview

You can create Bulk Labels in the “USPS > Create Bulk Order Labels” page in the sidebar.

If there are any Errors for one or more labels during the label creation process, those labels will be excluded from the Batch. You will be able to view the error message by clicking the red error link under the Error column. You can also view all the errors that occurred for a Batch on the USPS > View Batches page under the Errors column. Fix the errors for each order and try re-creating the labels.

PDF files for created batches of labels can be found in /modules/zh_uspslabels/pdf/batch folder.

Note: Creating large amounts of labels may take several minutes to complete, please allow the page to finish loading and do not refresh/cancel the page load.

Modifying Label Settings

You can modify each individual Order’s label settings by clicking the Edit Label Settings button for the Order or from each Order’s order page.

Any modifications made to an order’s label settings will be stored permanently and will be used instead of the default label values.

Orders with modified label settings will have a pencil icon under the Modified? column and will also be indicated as modified next to Saved Changes in the label form.

Be careful when trying to change an order’s shipping address after modifying an order’s label settings. When you modify an order’s label settings, the shipping address in the label form will be stored independently from the shipping address on the customer’s order. In which case, you will then have to change the shipping address in both the Order and the Label Form Settings.

Live Rates

Real-time rates can be fetched for each order by clicking on the blue refresh icon under the Live Rate column.

Label Carriers

The Label Carrier column indicates which USPS shipping method the label will use. By default, the module will automatically choose the Label Carrier based on the following in order of priority:

  1. The carrier that the customer chose during checkout (if it is USPS) or,
  2. The first active USPS carrier for the Order’s shipping country or,
  3. The first inactive USPS carrier for the Order’s shipping country.

You can override these defaults by using Carrier Mappings in the following section.

Carrier Mappings

You can map your PrestaShop carriers to USPS carriers in the Carrier Mappings preferences. Mapping your carriers will pre-select the Label Carrier for you.

Example: If you map “My Custom Carrier” to “USPS Priority Mail” - any orders that chose “My Custom Carrier” as their shipping method will have their Label Carrier defaulted to “USPS Priority Mail”.

Preferences

You can configure bulk label preferences in the Bulk Order Labels preferences.

You can exclude orders with certain order statuses from showing up in the Bulk Order Labels page by selecting one or more statuses in the Exclude Order Statuses setting. Select/Deselect statuses by holding Cmd/Ctrl+Click.

Example: If you choose to exclude “Shipped” orders, they will disappear from the page after you create labels for them (provided that you have Auto-Update Order Statuses enabled in the Labels preferences). This can also speed-up the page load time as the module can ignore all your previously shipped orders.

You can choose to sort your bulk label PDFs by Order ID, Shipping Date, or Order Date (ASC/DESC).

The Delay Between Labels setting is used to slow down the label creation process when more than 60 labels are requested. This adds a delay in between each label to make sure you aren’t hitting any EasyPost API throttle limit and timing out. Increase or decrease this value depending on whether you get timed out error messages from EasyPost when creating labels.

Scan Forms / Manifests

A Scan Form is a document/manifest that can be scanned to mark all included tracking codes as “Accepted for Shipment” by USPS instead of having to scan them one at a time.

Scan Forms are not mandatory and each shipping label can already be scanned individually without a Scan Form, they are purely for convenience, organization, and saving time.

You can submit a group of Shipments to create a Scan Form in the “USPS > End of Day / Scan Form” page. Select the Shipments you wish to add to a Scan Form and click the “Bulk actions > Create Scan Form for selected” button in at the bottom of the page.

You can view all previously created Scan Forms in the “USPS > View Scan Forms” page in the sidebar.

One Scan Form will be created for each origin address used in the selected Shipments:

Example: If you shipped your shipments from 2 different locations, you’ll receive 2 different Scan Forms, each with their respective address on them.

Note: Scan Forms can only be created for shipments created on the current date that are not yet in transit. Any shipments created before the current date that were not added to a Scan Form, or shipments already in transit, can no longer be added to a Scan Form and must be scanned individually. This means that you should create a Scan Form at least once per day after you are finished creating labels. This also means that those shipments will not appear in the “End of Day / Scan Form” page.

PDFs for created scan forms can be found in /modules/zh_uspslabels/pdf/manifests/ folder.

Groups

Groups are used to group several shipments together for organizational purposes.

For example, grouping is useful for when: You have multiple fulfillment locations; You want all shipments in a group to be shipped on the same day; You want to quickly create a Scan Form/Manifest for all shipments of a certain Group.

You can choose which group a shipment will belong to when creating a shipment label. If you don’t need to group shipments, you can simply use the “Default” group for all your shipments.

You can configure your groups in the Groups preferences.

Tracking

Allow customers to see their order’s tracking progress from their front-office Order Details page by enabling Enable Order Tracking in the Tracking preferences.

This will display a green progress bar in the order details page along with brief information about the last tracking event for their parcel (event description, current location, event time).

The tracking progress will only be displayed if a label was created for the order either via the Bulk Order Labels page or from the individual Order page. It will not be displayed if you created a custom label from the “Create Label & Return” page or if you entered a tracking number manually.

An order may have multiple labels associated with it, in which case the front-office order detail page will have multiple tracking progress bars (one for each label).

For PrestaShop versions 1.7.0.0 to 1.7.0.5: A theme modification may be required to make this feature work due to a bug in the default theme.

  1. Open the file {your_theme}/templates/customer/order-detail.tpl
  2. Replace {$HOOK_DISPLAYORDERDETAIL} with {$HOOK_DISPLAYORDERDETAIL nofilter}

Auto-Update on Delivered

You can choose to auto-update orders to a custom order status when the USPS tracking says it has been delivered. Enable Auto-Update Order Status When Delivered in the Tracking preferences.

You can choose multiple order statuses that you want the module to track and auto-update when delivered in the Order Statuses to Track setting. Select/Deselect statuses by holding Cmd/Ctrl+Click.

The module will only track orders with those selected statuses and will ignore any orders without those statuses.

Choose which status to update an order with once it has been tracked as delivered in the Delivered Order Status setting.

Smart Caching

The module stores rates for each cart in the database to speed up your website. It will only retrieve new rates if the customer changes their zip/postal code, the products in their cart, or the quantities for products already in their cart.

In some cases you may be trying to change the module configuration/carriers and refreshing your website to see updated rates. The rates will not update until one of the above conditions have been met, so try changing the products/quantities in your cart to see the new rates.

The module regularly cleans up old unused cache data once every 2 days to save space.
You can see the total amount of data the module is using up in the “Performance and Storage” tab of the module configuration page.

Troubleshooting

Q: Why are the rates not showing up?

Enable Error Logging in the module configuration page to help troubleshoot rates. If there are any errors while retrieving rates, the errors will get logged in the Advanced Parameters > Logs menu. Search for "USPS" in the log page to filter your logs.

Q: I modified the module Rates settings and the rates in the cart are not updating when I refresh the page.

See the Smart Caching section above.

The module will only fetch new rates if the customer changes their zip/postal code, the products in their cart, or the quantities for products already in their cart. The rates will not update until one of the above conditions have been met, so try changing the products/quantities in your cart to see the new rates.

Q: I don’t see the USPS tabs in the sidebar menu.

Q: My order statuses are not automatically updating to “Delivered”.

The Auto-Update Order Status When Delivered feature makes use of EasyPost “webhooks”. A webhook is a way for a service such as EasyPost to automatically notify the module as soon as a tracking event occurs - the module can then in turn update the order status.

Verify the following to confirm that EasyPost is sending webhooks to your website:

Common Error Messages

“There are no rates for the selected service method. The parcel may be too large or the configured options may be unsupported, try a different service method or try altering the settings.”
This error message means that the service method you chose (e.g. First Class), is not available with the label options you chose. This could mean either: you tried to enable an unsupported option (e.g. Signature Delivery Confirmation); your parcel dimensions/weight are too large for this service method, try Priority or Priority Express or try lowering your dimensions/weight; your destination address may be incorrect, check that there are no typos.
“This api key is no longer active. Please use a different api key or reactivate this key.”
Your EasyPost API key might have a typo in the module configuration page, check that your API keys exactly match the ones in your EasyPost account: https://www.easypost.com/account/api-keys
“Service ______ is not supported for the destination country __, please choose another service method.”
You’re trying to use a international service method on a US destination address (e.g. Priority Mail International), or a US service method on an international destination address (e.g. Priority Mail). Try changing the service method to the appropriate type.

PS versions 1.6.x and early versions of PS 1.7 contain bugs that this module must work around.

For versions 1.6.0.0 to 1.7.0.5, this module automatically installs an Override file at {your_prestashop}/override/classes/Hook.php to solve a particular bug. An Override file is a file that a module can install that can override core PrestaShop functionality. If you’re having issues installing the module, it may be because another module has already added that file and has created a conflict.

Here are some “hook” related errors you may encounter and how to fix them:

  1. Rename the file {your_prestashop}/modules/zh_uspslabels/override/classes/Hook.php from Hook.php to Hook.php.backup (this effectively disables it)
  2. Open the file {your_prestashop}/classes/Hook.php
  3. Find the following code near line #421 (may or may not be all one line):

public static function exec( $hook_name, $hook_args = array(), $id_module = null, $array_return = false, $check_exceptions = true, $use_push = false, $id_shop = null ) {

Immediately after the first curly brace (" { "), make a new line, enter the following code, and save your file:

$hook_name = str_replace('\\', '', $hook_name);

It should look like the following image:
Hook Override Image

Clear your cache in “Advanced Parameters > Performance” and click “Clear Cache” in the top right. Now you shouldn’t receive any hook related errors when you reinstall the module.

If you still see the same error, add the same line of code in the file: {your_prestashop}/override/classes/Hook.php

Changelog

Previous rates-only version (“zh_uspsshipping” module):