Shipping Rates API

Get real-time shipping rates from USPS, UPS, FedEx, and other carriers with a single API call.

Overview

Rates Endpoint:

POST https://api.atoship.com/v1/rates

Returns shipping options with prices, transit times, and service details.

Request Format

Basic Request:

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "90210",
    "country": "US"
  },
  "package": {
    "weight": 16,
    "length": 10,
    "width": 8,
    "height": 4
  }
}

Address Fields

From/To Object:

Field	Type	Required	Description
name	string	No	Contact name
company	string	No	Company name
street1	string	No	Street address
street2	string	No	Apt/Suite
city	string	No*	City
state	string	No*	State code
zip	string	Yes	Postal code
country	string	Yes	Country code
phone	string	No	Phone number

*Required for some carriers

Package Fields

Package Object:

Field	Type	Required	Description
weight	number	Yes	Weight in oz
length	number	No	Length in inches
width	number	No	Width in inches
height	number	No	Height in inches
type	string	No	Package type

Package Types

Available Types:

package (default)
envelope
flat_rate_envelope
flat_rate_box_small
flat_rate_box_medium
flat_rate_box_large
regional_rate_box_a
regional_rate_box_b

Response Format

Success Response:

{
  "success": true,
  "rates": [
    {
      "id": "rate_abc123",
      "carrier": "USPS",
      "service": "Priority Mail",
      "price": 8.95,
      "currency": "USD",
      "delivery_days": 2,
      "delivery_date": "2024-01-17"
    },
    {
      "id": "rate_def456",
      "carrier": "UPS",
      "service": "Ground",
      "price": 12.50,
      "currency": "USD",
      "delivery_days": 5
    }
  ]
}

Filtering Carriers

Specific Carriers:

{
  "carriers": ["USPS", "UPS"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

Service Filters

Filter by Service:

{
  "services": ["Priority Mail", "Ground"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

Multiple Packages

Multi-Package Request:

{
  "from": { ... },
  "to": { ... },
  "packages": [
    { "weight": 16, "length": 10, "width": 8, "height": 4 },
    { "weight": 32, "length": 12, "width": 10, "height": 6 }
  ]
}

International Rates

Customs Information:

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "M5V 2H1",
    "country": "CA"
  },
  "package": { ... },
  "customs": {
    "contents_type": "merchandise",
    "value": 50.00,
    "currency": "USD"
  }
}

Residential vs Commercial

Address Type:

{
  "to": {
    "zip": "90210",
    "country": "US",
    "is_residential": true
  }
}

Signature Options

Delivery Confirmation:

{
  "options": {
    "signature": "adult",
    "saturday_delivery": false
  }
}

Signature Values:

none
standard
adult
indirect

Insurance

Adding Insurance:

{
  "options": {
    "insurance_amount": 100.00
  }
}

Code Example

Complete Request:

const response = await fetch('https://api.atoship.com/v1/rates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: { zip: '10001', country: 'US' },
    to: { zip: '90210', country: 'US' },
    package: { weight: 16 }
  })
});

const { rates } = await response.json();
const cheapest = rates.sort((a, b) => a.price - b.price)[0];

Error Handling

Error Response:

{
  "success": false,
  "error": {
    "code": "invalid_address",
    "message": "Destination zip code is invalid",
    "field": "to.zip"
  }
}

Rate Caching

Best Practices:

Rates valid ~15 minutes
Cache by origin/destination
Re-fetch before purchase
Handle price changes

Performance Tips

Optimize Requests:

Include dimensions for accuracy
Specify carriers to reduce calls
Use webhook for bulk quotes
Cache common routes