> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitestorepro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-Time Shipping Rate Plugins: FedEx, UPS, and USPS

> Set up real-time shipping rates in Site Store Pro using built-in FedEx, UPS, and USPS plugins. Covers credentials, service toggles, and graceful degradation.

## How Real-Time Rates Work

On the `/checkout/review` page, Site Store Pro performs the following steps to present shipping options:

<Steps>
  <Step title="Calculate cart weight">
    Sums `item_qty × item_weight` for all shippable items in the cart.
  </Step>

  <Step title="Fetch shipping options">
    Calls `buildShippingOptions()`, which queries all active shipping plugins in parallel for flat-rate and real-time API rates.
  </Step>

  <Step title="Merge and sort">
    Combines all returned rates and sorts them low-to-high by price.
  </Step>

  <Step title="Display as radio buttons">
    The merged rate list is rendered as selectable radio buttons at checkout review.
  </Step>

  <Step title="Write to order record">
    The selected option's amount and name are written to the order record when the order is placed.
  </Step>
</Steps>

<Info>
  **Graceful degradation:** If a carrier API is unreachable, the plugin silently returns an empty array and logs the error to `storage/logs/laravel.log`. Checkout is never blocked by a carrier API failure.
</Info>

***

## FedEx Plugin

**Slug:** `fedex-api` | **API:** FedEx REST API v1 (OAuth2 client credentials)

<Warning>
  SOAP credentials are **not compatible** with this plugin. You must register at [developer.fedex.com](https://developer.fedex.com) and create a REST API project to obtain the required Client ID and Client Secret.
</Warning>

### Setup

<Steps>
  <Step title="Create a FedEx REST API project">
    Go to **developer.fedex.com → My Projects → Create a Project → Shipping → Rate API**. Copy your **Client ID** and **Client Secret**.
  </Step>

  <Step title="Find your FedEx Account Number">
    Your 9-digit FedEx Account Number appears on any FedEx invoice or in your FedEx account profile.
  </Step>

  <Step title="Configure in Admin">
    Go to **Admin → Plugins → Shipping Rates - FedEx REST API → Settings**. Enter your Account Number, Client ID, Client Secret, Origin ZIP, and Rate Markup. Enable the service checkboxes for the services you want to offer. Click **Save Settings**.
  </Step>

  <Step title="Activate the plugin">
    Switch to the **Activation** tab and click **Activate Plugin**.
  </Step>

  <Step title="Test at checkout">
    Add a shippable product to the cart and proceed to `/checkout/review`. If no rates appear, check `storage/logs/laravel.log` for `FedEx Auth Error`.
  </Step>
</Steps>

### Settings Reference

| Setting Key           | Label                       | Required |
| --------------------- | --------------------------- | -------- |
| `FedEx_Account`       | FedEx Account Number        | Yes      |
| `FedEx_Access_ID`     | API Client ID               | Yes      |
| `FedEx_Password`      | API Client Secret           | Yes      |
| `FedEx_markup`        | Rate Markup / Markdown (\$) | No       |
| `FedEx_NorthAmerica`  | Enable N. America Rates     | No       |
| `FedEx_International` | Enable International Rates  | No       |

### Service Toggles

Enable individual services to control which options appear at checkout:

**Domestic:** `FedEx_Ground`, `FedEx_Ground_Home_Delivery`, `FedEx_Express_Saver`, `FedEx_2_Day_Air`, `FedEx_2_Day_Air_AM`, `FedEx_Priority_Overnight`, `FedEx_Standard_Overnight`, `FedEx_First_Overnight`

**International:** `FedEx_International_Priority`, `FedEx_International_Economy`, `FedEx_International_First`

**Freight:** `FedEx_1_Day_Freight`, `FedEx_2_Day_Freight`, `FedEx_3_Day_Freight`

***

## UPS Plugin

**Slug:** `ups-api` | **API:** UPS REST Rating API v2205 (OAuth2)

<Tip>
  The UPS `Shop` endpoint returns **all eligible services** in a single API request, making UPS rate lookups efficient regardless of how many services you enable.
</Tip>

### Setup

<Steps>
  <Step title="Create a UPS REST API app">
    Go to **developer.ups.com → My Apps → Add App** and select **Rating**. Copy your **Client ID** and **Client Secret**.
  </Step>

  <Step title="Configure in Admin">
    Go to **Admin → Plugins → UPS → Settings**. Enter your Client ID, Client Secret, Account Number (optional, for negotiated rates), Origin ZIP, Origin Country Code, and Rate Markup. Enable the services you want to offer.
  </Step>

  <Step title="Activate the plugin">
    Switch to the **Activation** tab and click **Activate Plugin**.
  </Step>

  <Step title="Test at checkout">
    Proceed to `/checkout/review`. If no rates appear, check `storage/logs/laravel.log` for `UPS Auth Error` or `UPS Rate API Error`.
  </Step>
</Steps>

### Settings Reference

| Setting Key          | Label                       | Required                           |
| -------------------- | --------------------------- | ---------------------------------- |
| `UPS_Client_ID`      | UPS Client ID               | Yes                                |
| `UPS_Client_Secret`  | UPS Client Secret           | Yes                                |
| `UPS_Account_Number` | Account Number              | No (required for negotiated rates) |
| `UPS_From_Zip`       | Origin ZIP Code             | Yes                                |
| `UPS_From_Country`   | Origin Country Code         | Yes                                |
| `UPS_Markup`         | Rate Markup / Markdown (\$) | No                                 |

### Service Toggles

**Domestic:** `UPS_Ground`, `UPS_Ground_Saver`, `UPS_3_Day_Select`, `UPS_2nd_Day_Air`, `UPS_2nd_Day_Air_AM`, `UPS_Next_Day_Air_Saver`, `UPS_Next_Day_Air`, `UPS_Next_Day_Air_Early`

**International:** `UPS_International_Economy`, `UPS_International_Expedited`, `UPS_Worldwide_Express`, `UPS_Worldwide_Express_Plus`, `UPS_Worldwide_Saver`

***

## USPS Plugin

**Slug:** `usps-api` | **API:** USPS REST API v3 (OAuth2)

<Warning>
  The legacy USPS Web Tools XML/SOAP API was **deprecated in January 2024**. Register at [developer.usps.com](https://developer.usps.com) for v3 credentials.
</Warning>

<Tip>
  Unlike UPS, USPS makes **one API call per enabled service**. Enable only the services you actually offer to keep checkout review page load times fast.
</Tip>

### Setup

<Steps>
  <Step title="Create a USPS REST API app">
    Go to **developer.usps.com → My Apps → Add App** and select **Prices** and **International Prices**. Copy your **Consumer Key** (Client ID) and **Consumer Secret**.
  </Step>

  <Step title="Configure in Admin">
    Go to **Admin → Plugins → USPS → Settings**. Enter your Client ID, Client Secret, Origin ZIP (US addresses only), and Rate Markup. Enable the services you want to offer.

    **Recommended starting set:** Priority Mail + Priority Mail Express + Ground Advantage.
  </Step>

  <Step title="Activate the plugin">
    Switch to the **Activation** tab and click **Activate Plugin**.
  </Step>

  <Step title="Test at checkout">
    Proceed to `/checkout/review`. If no rates appear, check `storage/logs/laravel.log` for `USPS Auth Error` or `USPS Plugin Exception`.
  </Step>
</Steps>

### Service Toggles

**Domestic:**

| Service Key                      | Service Name              | Transit Time               |
| -------------------------------- | ------------------------- | -------------------------- |
| `USPS_Priority_Mail`             | Priority Mail             | 1–3 days                   |
| `USPS_Priority_Mail_Express`     | Priority Mail Express     | Overnight–2 days           |
| `USPS_Ground_Advantage`          | Ground Advantage          | 2–5 days                   |
| `USPS_First_Class_Package`       | First-Class Package       | 2–3 days (≤ 15.99 oz only) |
| `USPS_Parcel_Select`             | Parcel Select             | 2–9 days (economy)         |
| `USPS_Parcel_Select_Lightweight` | Parcel Select Lightweight | Economy                    |
| `USPS_Priority_Mail_Cubic`       | Priority Mail Cubic       | 1–3 days                   |

**International:**

| Service Key                       | Service Name                        |
| --------------------------------- | ----------------------------------- |
| `USPS_Priority_Mail_Express_Intl` | Priority Mail Express International |
| `USPS_Priority_Mail_Intl`         | Priority Mail International         |
| `USPS_First_Class_Package_Intl`   | First-Class Package International   |

### Performance Note

<Warning>
  Each additional enabled USPS service adds approximately **200–400 ms** to the checkout review page load time. Enable only the services you plan to offer.
</Warning>

***

## Related

<CardGroup cols={2}>
  <Card title="Plugin System" icon="puzzle-piece" href="/plugins/plugin-system">
    Plugin discovery, the Admin Panel, and PluginManager API.
  </Card>

  <Card title="Custom Plugins" icon="code" href="/plugins/custom-plugins">
    Build your own shipping plugin using the drop-in plugin system.
  </Card>
</CardGroup>