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

# USPS

> Show live USPS rates at checkout using your own account

Connect your USPS account and ShipMagic will query real USPS rates at checkout and show them to the customer.

<Warning>
  **USPS authentication has changed.** USPS has moved from its older API to OAuth-based credentials. You need a **Client ID** and **Client Secret** from the USPS Developer Portal — an older USPS username and password will not work.
</Warning>

## Getting credentials

USPS issues API credentials through the [USPS Developer Portal](https://developer.usps.com/). Register your business, create an application, and copy the **Client ID** and **Client Secret** it generates.

## Setting up the rate

<Steps>
  <Step title="Add a rate to your zone">
    In your rule, click **Add rate** on the zone you want.
  </Step>

  <Step title="Set the calculation parameter to USPS">
    Choose **USPS** under the live carrier options.
  </Step>

  <Step title="Enter your credentials">
    Paste the **Client ID** and **Client Secret**.
  </Step>

  <Step title="Choose a rate schedule">
    Select which USPS price schedule your account is on. This must match your actual USPS contract, or quotes will be wrong.
  </Step>

  <Step title="Select which rates to show">
    Pick the USPS services to offer — Priority Mail, Ground Advantage, Priority Mail Express, and the various Flat Rate envelopes and boxes.

    You can also choose to show **All rates**, the **Highest rate only**, or the **Lowest rate only**.
  </Step>

  <Step title="Configure packaging">
    Set **Packaging box distribution** and define your boxes. See [the packing algorithm](/shipping-rates/types-of-rates/carrier-rates/3-d-boxing-algorithm).
  </Step>

  <Step title="Set a discount and default rate">
    **Discount (Optional)** reduces every returned rate by a percentage. **Default rate** is used if USPS doesn't respond.
  </Step>
</Steps>

## Flat Rate services

USPS Flat Rate envelopes and boxes price by container rather than by weight, which makes them attractive for dense items. ShipMagic lists them individually so you can offer only the ones you actually stock.

<Tip>
  Only enable Flat Rate options you keep in your packing area. Quoting a Priority Mail Medium Flat Rate Box you don't have leads to a repack at a different price.
</Tip>

## The Discount field

**Discount (Optional)** applies a flat percentage reduction to every rate USPS returns.

Use it to pass on a commercial-pricing advantage, or to absorb part of the shipping cost as a promotion. It does not reflect any actual USPS discount — it's applied by ShipMagic after the quote comes back.

## Always set a Default rate

<Warning>
  If USPS is slow or unavailable and no default rate is set, the customer sees **no shipping option at all** and cannot complete checkout.

  Set a default rate that is safe to charge when the live quote is unavailable.
</Warning>

## Testing

Live rates depend on a real origin and destination, so test with complete, realistic addresses.

1. Add products to the cart with accurate weights and dimensions
2. Check out to a real US address
3. Compare the quoted rate against what USPS charges you for the same parcel

<Tip>
  Use a fresh address each time — Shopify caches rates per address, and a cached quote will mask your changes.
</Tip>

## Related

<Columns cols={2}>
  <Card title="Packing algorithm" icon="box-taped" href="/shipping-rates/types-of-rates/carrier-rates/3-d-boxing-algorithm">
    How items are distributed into parcels before quoting.
  </Card>

  <Card title="Adding dimensions" icon="ruler-combined" href="/adding-dimensions-to-products">
    Dimension data that carrier quotes depend on.
  </Card>

  <Card title="Rate blending" icon="code-merge" href="/rate-blending">
    Combining carrier rates with your own.
  </Card>

  <Card title="Rates not showing" icon="circle-question" href="/shipping-rates-not-showing-on-checkout-page">
    When a carrier rate fails to appear.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.