Laravel USPS v13.3 20 APIs

Complete USPS API v3 (OAuth2) for Laravel 10–13 — 20 API domains, 80+ endpoints, REST routes, input validation

The legacy USPS Web Tools XML API was retired January 2026. This package uses the new OAuth2-based REST/JSON API at apis.usps.com with automatic token management and per-scope caching.

Addresses Tracking Labels Intl Labels Prices Intl Prices Standards Standards Dir Standards Files Intl Standards Locations Carrier Pickup Containers Payments Campaigns Pkg Campaigns Adjustments Disputes Appointments

Installation

composer require johnpaulmedina/laravel-usps

Configuration

php artisan vendor:publish --tag=usps-config

USPS_CLIENT_ID=your-client-id
USPS_CLIENT_SECRET=your-client-secret

Artisan Commands

# Validate an address
php artisan usps:validate "1600 Pennsylvania Ave NW" --state=DC --zip=20500

# Track packages
php artisan usps:track 9400111899223456789012

# ZIP code lookup
php artisan usps:zip 33101

# Calculate shipping rates
php artisan usps:price 20500 33101 16 --mail-class=PRIORITY_MAIL

# Delivery estimates
php artisan usps:standards 20500 33101

# Find USPS locations
php artisan usps:locations 33101 --type=post-office --radius=5

All commands output formatted tables to the console.

REST API Routes

Publish routes to your app:

php artisan vendor:publish --tag=usps-routes

27 routes under /api/usps/ with Form Request validation. 13 controllers, 26 request classes.

Input Validation

All inputs are automatically normalized and validated:

States — Full names auto-converted to 2-letter codes (Florida → FL)
ZIP codes — Dashes stripped, ZIP+4 auto-split (20500-0005 → 20500 + 0005)
Countries — Full names to ISO alpha-2 (Canada → CA)
Dates — Auto-normalized to ISO 8601 (YYYY-MM-DD)
Weight — Validated as positive numeric
Address corrections — DPV confirmation + correction codes returned (e.g., apartment missing)

API Domains

Addresses

Validate, standardize, ZIP/city lookup

3 endpoints

Tracking

Track packages, notifications, proof of delivery

3 endpoints

Domestic Labels

Create, cancel, reprint, branding, indicia, IMB

12 endpoints

International Labels

Create, reprint, cancel international labels

4 endpoints

Domestic Prices

Base rates, extra services, total rates, letters

5 endpoints

International Prices

International postage rate calculations

5 endpoints

Service Standards

Delivery estimates and standards by ZIP

2 endpoints

Standards Directory

Bulk service standard data with pagination

2 endpoints

Standards Files

Download service standard data files

2 endpoints

Intl Standards

International delivery standard messages

1 endpoint

Locations

Post offices, dropoff locations, parcel lockers

3 endpoints

Carrier Pickup

Schedule, get, update, cancel pickups

5 endpoints

Containers

Container labels, package management, manifests

5 endpoints

Payments

Payment authorization tokens, account inquiry

2 endpoints

Mail Campaigns

Informed Delivery mail campaigns, IMBs

9 endpoints

Pkg Campaigns

Informed Delivery package campaigns

6 endpoints

Adjustments

Shipping charge adjustments by tracking number

1 endpoint

Disputes

Create disputes for pricing adjustments

1 endpoint

Appointments

FAST facility appointments, availability

4 endpoints

Endpoint Reference

Addresses Usps::validate()

GET /addresses/v3/address Validate and standardize an address
GET /addresses/v3/city-state City/State by ZIP code
GET /addresses/v3/zipcode ZIP code by address

Validate Response

{
  "address": {
    "Address2": "1600 PENNSYLVANIA AVE NW",
    "Address1": "",
    "City": "WASHINGTON",
    "State": "DC",
    "Zip5": "20500",
    "Zip4": "0005"
  },
  "additionalInfo": {
    "DPVConfirmation": "Y",
    "business": "Y",
    "vacant": "N"
  }
}

When Apartment is Missing

{
  "address": { "Address2": "100 S BISCAYNE BLVD", ... },
  "corrections": [{
    "code": "32",
    "text": "...more information is needed (apartment, suite, or box number)..."
  }],
  "additionalInfo": { "DPVConfirmation": "D" }
}

DPV (Delivery Point Validation)

Confirms whether the address is a real USPS deliverable location — down to the apartment/suite level.

Code	Meaning
Y	Full match — street and unit confirmed
D	Primary confirmed, apartment/suite missing
S	Primary confirmed, apartment/suite doesn't match
N	Not a valid delivery point

Correction codes: 32 = apartment needed, 22 = multiple addresses found

City/State Lookup Response

{ "city": "WASHINGTON", "state": "DC", "ZIPCode": "20500" }

ZIP Code Lookup Response

{
  "address": {
    "streetAddress": "1600 PENNSYLVANIA AVE NW",
    "city": "WASHINGTON",
    "state": "DC",
    "ZIPCode": "20500",
    "ZIPPlus4": "0005"
  }
}

State names auto-convert (Florida → FL). ZIP+4 auto-splits (20500-0005 → 20500 + 0005).
Full USPS Address API docs →

Tracking Usps::tracking()

POST /tracking/v3r2/tracking Get package tracking status
POST /tracking/v3r2/tracking/{id}/notifications Register notifications
POST /tracking/v3r2/tracking/{id}/proof-of-delivery Request proof of delivery

Domestic Labels Usps::labels()

POST /labels/v3/label Create shipping label
POST /labels/v3/return-label Create return label
DELETE /labels/v3/label/{id} Cancel/refund label
PATCH /labels/v3/label/{id} Edit label attributes
POST /labels/v3/indicia Create First-Class indicia
POST /labels/v3/indicia/imb Create IMB label
DELETE /labels/v3/indicia/imb/{imb} Cancel IMB
POST /labels/v3/branding Upload branding image
GET /labels/v3/branding List branding images
GET /labels/v3/branding/{uuid} Get branding image
DELETE /labels/v3/branding/{uuid} Delete branding image
POST /labels/v3/label-reprint/{id} Reprint label

International Labels Usps::internationalLabels()

POST /international-labels/v3/international-label Create international label
POST /international-labels/v3/international-label-reprint/{id} Reprint
DELETE /international-labels/v3/international-label/{id} Cancel
POST /international-labels/v3/indicia Create international indicia

Domestic Prices Usps::domesticPrices()

POST /prices/v3/base-rates/search Base rate search
POST /prices/v3/extra-service-rates/search Extra service rates
POST /prices/v3/base-rates-list/search Eligible products list
POST /prices/v3/total-rates/search Total rates with fees
POST /prices/v3/letter-rates/search First-Class letter rates

International Prices Usps::internationalPrices()

POST /international-prices/v3/base-rates/search Base rate search
POST /international-prices/v3/extra-service-rates/search Extra service rates
POST /international-prices/v3/base-rates-list/search Eligible products
POST /international-prices/v3/total-rates/search Total rates
POST /international-prices/v3/letter-rates/search Letter rates

Service Standards Usps::serviceStandards()

GET /service-standards/v3/estimates Delivery estimates
GET /service-standards/v3/standards Service standards

Service Standards Directory Usps::serviceStandardsDirectory()

GET /service-standards-directory/v3/zip5Codes Valid ZIP codes
POST /service-standards-directory/v3/reporter Standards directory report

Service Standards Files Usps::serviceStandardsFiles()

GET /service-standards-files/v3/files List available files
GET /service-standards-files/v3/files/{id}/generate-signed-url Signed download URL

International Service Standards Usps::internationalServiceStandards()

GET /international-service-standard/v3/international-service-standard Delivery standard message

Locations Usps::locations()

GET /locations/v3/dropoff-locations Destination entry dropoff locations
GET /locations/v3/post-office-locations Post office locations
GET /locations/v3/parcel-locker-locations Parcel locker locations

Carrier Pickup Usps::carrierPickup()

GET /pickup/v3/carrier-pickup/eligibility Check address eligibility
POST /pickup/v3/carrier-pickup Schedule a pickup
GET /pickup/v3/carrier-pickup/{id} Get pickup details
PUT /pickup/v3/carrier-pickup/{id} Update pickup
DELETE /pickup/v3/carrier-pickup/{id} Cancel pickup

Containers Usps::containers()

POST /containers/v3/containers Create container label
POST /containers/v3/containers/{id}/packages Add packages
DELETE /containers/v3/containers/{id}/packages Remove all packages
DELETE /containers/v3/containers/{id}/packages/{tn} Remove single package
POST /containers/v3/containers/manifest Close and manifest

Payments Usps::payments()

POST /payments/v3/payment-authorization Create payment auth token
GET /payments/v3/payment-account/{id} Account inquiry

Informed Delivery Campaigns Usps::campaigns()

POST /campaigns Create campaign
GET /campaigns Search campaigns
GET /campaigns/{id} Get single campaign
PUT /campaigns/{id} Edit campaign
DELETE /campaigns/{id} Cancel campaign
POST /campaigns/{id}/imbs Add IMBs to NON-SEQ campaign
GET /campaigns/{crid}/callbacks List callback keys
GET /campaigns/{crid}/{key}/summary Callback summary
GET /campaigns/{crid}/{key}/details Callback error details

Package Campaigns Usps::packageCampaigns()

POST /package-campaigns Create package campaign
GET /package-campaigns Search package campaigns
GET /package-campaigns/{id} Get single campaign
PUT /package-campaigns/{id} Edit package campaign
DELETE /package-campaigns/{id} Cancel package campaign
POST /package-campaigns/{id}/tracking-numbers Add tracking numbers

Adjustments Usps::adjustments()

GET /adjustments/v3/adjustments/{crid}/{tn}/{eventType} Get adjustments

Disputes Usps::disputes()

POST /disputes/v3/dispute Create dispute

Appointments Usps::appointments()

POST /fast-appointments/appointment Create appointment
PUT /fast-appointments/appointment Update appointment
DELETE /fast-appointments/appointment Cancel appointment
GET /appointment-availability Check availability

Shipping Options Usps::shippingOptions()

POST /shipments/v3/options/search Combined pricing, standards, and available options

SCAN Forms Usps::scanForms()

POST /scan-forms/v3/scan-form Label Shipment — link tracking numbers to EFN
POST /scan-forms/v3/scan-form MID Shipment — link by Mailer ID
POST /scan-forms/v3/scan-form Manifest MID Shipment — multi-manifest

Requirements

PHP	8.1+
Laravel	10, 11, 12, 13
USPS Credentials	developer.usps.com