The USPS add-on for X-Cart 5 allows you to use online shipping rate calculation via USPS Web Tools Ecommerce API.


This article assumes that the USPS add-on has already been installed and activated at your store.


To start using the add-on, you need to configure it. The add-on configuration settings can be accessed using one of the following methods:

Method 1:

  1. In the Shipping section of your X-Cart store's Admin area (Store Setup > Shipping), click the Add shipping method button:

  2. In the popup that appears, choose the USPS shipping method:

Method 2:

  1. In the My Apps section of your X-Cart store's Admin area, find the USPS add-on and click on its name to access the add-on detailed information.

  2. On the add-on information page, click on the Settings link:

The add-on settings page allows you to select one of the available data providers for the USPS shipping services.


Pitney Bowes Data Provider


Configuring USPS via Pitney Bowes allows using integrated shipping labels.


To configure Pitney Bowes as your USPS data provider, do as follows:

  1. Select Pitney Bowes in the Data provider dropdown.

  2. Specify your Pitney Bowes account registration email in the "Pitney Bowes merchant emailId" field.


    If you have not yet got an account with Pitney Bowes, you can sign up for one using the link provided on the add-on settings page:


    Once you have an account, you can access your account info at https://www.pbshippingmerchant.pitneybowes.com/accountInfo.


  3. Specify parameters applied to both domestic and international shipments from your store. Use the fields of the Common options section for this purpose.

    • Package dimensions (inches) (Length, Width, Height): Use these fields to define the default package size for USPS shipments in inches.

    • Girth: Required for large size and if the container is non-rectangular or variable.

    • Maximum package weight: Specify the top limit of the package's weight in pounds (lbs).

    • Currency conversion rate: Use this field to provide a currency conversion rate if your currency is other than the US dollar. If your currency is the US dollar, leave this field set to 1.

  4. Adjust the settings in the Domestic USPS section. These settings will apply to all your domestic shipments.

    • Parcel type: Use this field to choose the parcel type used for your domestic shipments.

    • Request rates for: Select whether your online store should request the delivery rates from Pitney Bowes for all available methods or online methods only.

  5. Select the preferred parcel type in the International USPS section that will apply to your international shipments.

  6. Enable the Cash on Delivery toggle for both international and domestic shipments.


    The "Cash on Delivery" toggle may be inactive in case you haven't enabled the respective payment on the Payment methods page of your store's Admin area (Store Setup > Payment Methods). However, you can quickly access that page using the link at the bottom of the Cash on delivery section:


    There will be the Cash on Delivery toggle for USPS on the Payment Methods page in the Offline methods section. Turn on the toggle to enable the Cash on Delivery (USPS) payment.


    There will be no Cash on Delivery (USPS) payment on the Payment Methods page before you finish configuring the USPS add-on. Therefore, if you need to enable Cash on Delivery (USPS), you will have to save the USPS add-on settings leaving its "Cash on delivery" toggle as is (inactive). Then, visit the Payment Methods page to activate the Cash on Delivery (USPS) payment separately.


  7. You can also adjust some Additional options for the USPS add-on:

    • Log all communication between shopping cart and USPS server: This option enables logging incoming and outcoming USPS server requests. The logs are saved to USPS.log files in the <X-Cart>/var/log/ folder.

    • Auto enable new USPS shipping methods: This option will automatically add all new USPS shipping methods to your system. They will not be enabled for customers automatically, though.

  8. Be sure to save the changes when your USPS shipping configuration is complete.

USPS Data Provider

To configure plain USPS as your USPS data provider, do as follows:

  1. Select USPS in the Data provider dropdown.

  2. Specify the User ID provided to you by USPS in the User ID field.

  3. In the "USPS API server URL" field, specify the URL USPS provided in the notification of successful registration for the U.S. Postal Service's Web Tools Application Program Interfaces.
    For example:
    https://stg-secure.shippingapis.com/ShippingApi.dll https://secure.shippingapis.com/ShippingAPI.dll


    If USPS fails to work correctly in the live mode, while there was no such problem in the test mode (usually you receive the "API Authorization failure. RateV4 is not a valid API name for this protocol" error message), contact USPS support staff and ask them to transfer your account to the production server.


  4. Specify parameters applied to both domestic and international shipments from your store. Use the fields of the Common Options section for this purpose.

    • Package Size (length + girth, inches): Choose either Regular or Large.

    • Package dimensions (inches) (Length, Width, Height): Use these fields to define the default package size for USPS shipments in inches.

    • Girth: Required for large size and if the container is non-rectangular or variable.

    • Maximum package weight: Specify the top limit of the package's weight in pounds (lbs).

    • Machinable: Specify whether it is OK to handle your shipments by machines. Enabling this option reduces the shipping costs.

    • Currency conversion rate: Use this field to provide a currency conversion rate if your currency is other than the US dollar. If your currency is the US dollar, leave this field set to 1.

  5. Adjust the settings in the Domestic USPS section. These settings will apply to all your domestic shipments.

    • Container: Use this field to specify the container type for your domestic shipments.

    • Pricing type to be used: Use this dropdown to specify the pricing type for your domestic shipments.

  6. Adjust the International USPS section settings that will apply to your international shipments.

    • Mail type: Select the type of goods for international delivery.

    • Container: Select the package type for international shipments.

    • Get commercial base postage and Global Express Guarantee (GXG): These are advanced options for international shipments.

    • Parcel type: Select the type of packaging for international delivery.

  7. Enable the Cash on Delivery toggle for both international and domestic shipments.


    The "Cash on Delivery" toggle may be inactive in case you haven't enabled the respective payment on the Payment methods page of your store's Admin area (Store Setup > Payment Methods). However, you can quickly access that page using the link at the bottom of the Cash on delivery section:


    There will be the Cash on Delivery toggle for USPS on the Payment Methods page in the Offline methods section. Turn on the toggle to enable the Cash on Delivery (USPS) payment.


    There will be no Cash on Delivery (USPS) payment on the Payment Methods page before you finish configuring the USPS add-on. Therefore, if you need to enable Cash on Delivery (USPS), you will have to save the USPS add-on settings leaving its "Cash on delivery" toggle as is (inactive). Then, visit the Payment Methods page to activate the Cash on Delivery (USPS) payment separately.


  8. Adjust additional options for the USPS add-on:

    • Log all communication between shopping cart and USPS server: This option enables logging incoming and outcoming USPS server requests. The logs are saved to USPS.log files in the <X-Cart>/var/log/ folder.

    • Auto enable new USPS shipping methods: This option will automatically add all new USPS shipping methods to your system. They will not be enabled for customers automatically though.

  9. Be sure to save the changes when your USPS shipping configuration is complete.

Related pages:

Did this answer your question?