# Installation

First of all you need an USPS account and create API credentials. After that you can install and configure the extension and the shipping methods in your shop.

### USPS account

To communicate with USPS APIs in both production and test environments, developer registration is required. Follow these steps to proceed:

1. Register for a free account at [**USPS.com**](https://www.usps.com).
2. Access the [**Business Customer Gateway**](https://gateway.usps.com/eAdmin/view/signin) and complete the setup process for a USPS business account.
3. Log in to the [**USPS Developer Portal**](https://developers.usps.com/) using your USPS credentials via the **Sign Up / Login** interface.
4. Register your application within the Developer Portal to obtain your **consumer key** and **consumer secret**, available under the **Credentials** section of your account dashboard.

### Get API credentials

1. Using your USPS credentials to log in to the [**USPS Developer Portal**](https://developers.usps.com/) 
2. Click on link "Apps" on header of the page.
3. Enter button "Add app".
4. Fill in your "App name", enable "Public access 1" and save the form.
5. Copy the "Consumer Key" and the "Consumer Secret". You need them in the extension.

<figure><img src="https://747417571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYYTKTU6awfIFbvBGavuX%2Fuploads%2Foe5AboDFl8rMmKl3FXlt%2Fimage.png?alt=media&#x26;token=f03aaeb3-7a3d-4d96-9151-8c8393028f1b" alt=""><figcaption></figcaption></figure>

### Install & configure extension

Install the extension via **Extensions** > **My Extensions**.

<figure><img src="https://747417571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYYTKTU6awfIFbvBGavuX%2Fuploads%2Fym15qLoRbDdJqoWF7rnl%2Fimage.png?alt=media&#x26;token=3e876ba1-5160-44ad-bce4-416852defb04" alt=""><figcaption></figcaption></figure>

Before you enable the extension, check the settings in this section and ensure they meet your requirements. Make any changes to individual fields as described below by selecting **My extensions** > **USPS Shipping Rates** > **Configure**.

#### General properties

In this area you can choose your zipcode and the unit of weight of the products.

| Field                                               | Type      | Description                                                                                                                                                             |
| --------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sender zip                                          | Textfield | Please enter you zipcode. It must be a zip of United States, Puerto Rico or US Virgin Islands.                                                                          |
| Unit of weight                                      | Dropdown  | Please select which unit of weights you use for your products in shop                                                                                                   |
| Show message why a shipping method is not available | Toggle    | Display a hint why USPS shipping methods are not available. It only shows a message on an error. For instance: Missing weight of products or invalid format of address. |
| Log Level                                           | Dropdown  | Select whether only errors should be recorded in a log file or also debug information.                                                                                  |

#### USPS api access

Enter you API credentials and check if they are working.

| Field             | Type           | Description                                                                                         |
| ----------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| Consumer Key      | Password field | Enter your USPS **Consumer Key** here.                                                              |
| Consumer Secret   | Password field | Enter your USPS **Consumer Secret** here.                                                           |
| Mode              | Dropdown       | Choose if you want to test the credentials in **Test** or **Live** mode                             |
| Check credentials | Button         | After entering **Consumer Key** and **Consumer Secret** click this button to check the credentials. |

### Configure shipping methods

During installation of the extension the USPS shipping methods were created automatically with common settings. Of course you can edit and modify the shipping methods to your needs. Follow the Shopware 6 [documentation ](https://docs.shopware.com/en/shopware-6-en/settings/shipping)for more information.

{% hint style="info" %}
Don't forgett to add the shipping methods to your sales channels where you want to use them.\
Take care: If you disable/ uninstall the USPS plugin don't forgett to remove the shipping method from the sales channels.
{% endhint %}

### Available Shipping Methods

The following USPS mailings are supported:

* Parcel Select
* Priority Mail Express
* Priority Mail
* Library Mail
* Media Mail
* Bound Printed Matter
* USPS connect local
* USPS Connect Mail
* USPS Connect Regional
* USPS Ground Advantage
* First Class Package International Service
* Priority Mail International
* Priority Mail Express International

### Add an additional shipping fee

Additionally to the shipping rates you got from USPS, you can also define an additional fee for your shipping methods. Just use the **Add price matrix** at a shipping method in Shopware administration. If you define a price here, it will be added to the USPS price of the shipping method.

<figure><img src="https://747417571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYYTKTU6awfIFbvBGavuX%2Fuploads%2FwCmvebcqhbmaqyNOtpJ5%2Fimage.png?alt=media&#x26;token=850c3d1b-8ee0-421b-aca5-5d008dca3079" alt=""><figcaption></figcaption></figure>

### Availability shipping rules

By extension default USPS shipping methods are hidden if a customer is not logged in or no valid USPS mailings were found for the current cart. Additionally you can define further shipping rules. For instance to enable shipping only for specific customer groups.

{% hint style="info" %}
If your USPS shipping method is not shown after register/ login please check the following points:

* Have you checked the API crendentials in extension configuration?
* Have you defined a zipcode of United States, Puerto Rico or US Virgin Islands in extension configuration?
* Do the products in cart have a weight?
* Are your shipping rules matching the current customer?
* Did you assign your new shipping methods to your shops sales channel?
  {% endhint %}

### Error and Debug Logfile

If an error with API connection occured it is logged into a file located at folder **var/log** of Shopware base dir. In extension configuration you can also define, that debug information will be logged.