Shipping (FedEx, UPS)

Real-time shipping rates at checkout from FedEx and UPS. USPS support is planned.

Setup

FedEx

1. Register a developer account at developer.fedex.com (opens in a new tab)
2. Create a production (or sandbox) API key
3. In admin → Settings → Shipping:
   • Enter FedEx account number
   • Enter FedEx API key (encrypted at rest)
   • Toggle sandbox

UPS

1. Register at developer.ups.com (opens in a new tab)
2. Create an API app with OAuth credentials
3. In admin → Settings → Shipping:
   • Enter UPS account number
   • Enter UPS API key (encrypted)
   • Toggle sandbox

Ship-from address

Set your origin address — fields ship_from_name, ship_from_address1, ship_from_city, ship_from_state, ship_from_zip, ship_from_country.

How rates are fetched

1. Customer enters shipping address at checkout
2. POST /checkout/shipping-rates sent with cart ID + address
3. Backend calculates cart weight (sum of variant.weight_oz × quantity)
4. Calls FedEx + UPS APIs in parallel
5. Merges rates, sorts by price, returns to customer
6. Customer picks rate — stored on the order

Supported services

FedEx: Ground, Home Delivery, Express Saver, 2-Day, Standard Overnight, Priority Overnight

UPS: Ground, 3-Day Select, 2nd Day Air, Next Day Air Saver, Next Day Air, Next Day Air Early

Free shipping

Set free_shipping_threshold in tenant settings. Orders above this amount show "Free shipping applied" and cost $0 for shipping.

Credentials security

API keys are encrypted at rest via CredentialEncryption. They're only decrypted on the server when making a call.

Planned enhancements

• USPS rate lookup + Priority Mail labels
• Automated label generation + printing
• Real-time tracking updates via carrier webhooks
• Customer shipping notifications

See the shipping integration planning notes for details.

Related features

• Storefront Shipping
• Orders (Admin)