Shipping Rates API

The Shipping Rates API returns available USPS, UPS, FedEx, and other valid services exposed by the eBay shipping calculator. Send the route and package once, then use the structured response in a checkout, repricer, inventory tool, or shipping comparison screen.

This is a quote-only endpoint. It does not purchase a label, change an order, or connect to a seller's eBay account.

Make a request

POST /v1/shipping/rates currently supports shipments from one US ZIP code to another US ZIP code. Use the same CompSniper API key as the sold-comps API. Shipping requires its own subscription and has an independent request allowance.

curl --fail-with-body --request POST \
  --header "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: quote-order-123" \
  --data '{
    "shipFrom": { "postalCode": "10001" },
    "shipTo": { "postalCode": "90210" },
    "package": {
      "type": "custom",
      "weight": { "value": 2, "unit": "lb" },
      "dimensions": { "length": 10, "width": 8, "height": 4, "unit": "in" }
    },
    "contents": { "mediaMailEligible": false }
  }' \
  "https://api.compsniper.com/v1/shipping/rates"

Request fields

Supported carrier-package values are usps_flat_rate_envelope, usps_padded_flat_rate_envelope, usps_legal_flat_rate_envelope, usps_small_flat_rate_box, usps_medium_flat_rate_box, usps_large_flat_rate_box, usps_express_flat_rate_envelope, fedex_one_rate_envelope, fedex_one_rate_pak, fedex_one_rate_extra_small_box, fedex_one_rate_small_box, fedex_one_rate_medium_box, fedex_one_rate_large_box, fedex_one_rate_extra_large_box, and fedex_one_rate_tube.

Response

{
  "source": "ebay_shipping_calculator",
  "rateType": "estimate",
  "currency": "USD",
  "totalRates": 14,
  "totalConditionalRates": 7,
  "fetchedAt": "2026-09-11T20:14:31.000Z",
  "validUntil": "2026-09-11T20:19:31.000Z",
  "requestId": "a480a68e-7e5b-49cf-9489-acde071007e6",
  "cache": "MISS",
  "rates": [
    {
      "carrierCode": "USPS",
      "serviceName": "USPS Ground Advantage",
      "serviceCode": "USPSParcel",
      "serviceGroup": "Standard services",
      "tracking": true,
      "estimatedDeliveryMinHours": 48,
      "estimatedDeliveryMaxHours": 120,
      "includedCoverage": "$100",
      "fastest": false,
      "discountedPrice": { "min": "10.05", "max": null, "currency": "USD" },
      "retailPrice": { "min": "19.05", "max": null, "currency": "USD" },
      "effectivePrice": { "min": "10.05", "max": null, "currency": "USD" },
      "priceSource": "ebay_discounted",
      "savingsPercent": 47,
      "eligibility": { "status": "eligible", "requirements": [] }
    }
  ],
  "conditionalRates": [
    {
      "carrierCode": "USPS",
      "serviceName": "USPS Media Mail",
      "serviceCode": "USPSMedia",
      "serviceGroup": null,
      "tracking": true,
      "estimatedDeliveryMinHours": 48,
      "estimatedDeliveryMaxHours": 192,
      "includedCoverage": "N/A",
      "fastest": false,
      "discountedPrice": { "min": "5.13", "max": null, "currency": "USD" },
      "retailPrice": { "min": "5.13", "max": null, "currency": "USD" },
      "effectivePrice": { "min": "5.13", "max": null, "currency": "USD" },
      "priceSource": "ebay_discounted",
      "savingsPercent": null,
      "eligibility": {
        "status": "conditional",
        "requirements": [
          {
            "type": "eligible_contents",
            "code": "usps_media_mail",
            "message": "Contents must qualify under USPS Media Mail standards."
          }
        ]
      }
    }
  ]
}

The response keeps the original discountedPrice and retailPrice separately. When eBay does not provide a discounted value, discountedPrice is null, effectivePrice uses the retail estimate, and priceSource is retail. A displayed discounted price is not guaranteed to be lower, so savingsPercent is only present when it represents an actual saving.

Treat all values as estimates. The rate available when a label is purchased can change because of the seller account, package details, address validation, carrier adjustments, and eBay eligibility.

Applicable and conditional rates

rates contains services applicable to the submitted package information. With the default package.type of custom, USPS Flat Rate and FedEx One Rate packaging options are placed in conditionalRates instead of being presented as ordinary custom-package services. Each conditional rate includes a machine-readable packaging requirement. Selecting that exact package.type moves the matching option into rates.

USPS Flat Rate pricing requires the corresponding USPS-produced packaging. FedEx One Rate likewise requires eligible FedEx packaging.

USPS Media Mail remains in conditionalRates unless contents.mediaMailEligible is explicitly true. The caller is responsible for confirming that the shipment contents satisfy USPS Media Mail standards.

fastest is calculated across the applicable rates array using the shortest maximum delivery window. All services tied for that shortest window receive fastest: true. Conditional services are never marked fastest unless their requirement is selected and they move into rates.

Idempotency and caching

Send a unique Idempotency-Key for each quote operation. Retrying the identical body with the same key replays the completed response without spending another shipping request. Reusing a key with a different body returns 409 idempotency_conflict.

Identical quote inputs can share a fresh five-minute cache. Cache hits still return usable quotes and spend one shipping request. Validation failures, upstream failures, local capacity errors, and empty quote results do not spend shipping quota.

Usage and limits

Use GET /v1/shipping/usage to read the separate Shipping Rates plan, monthly quota, used count, remaining count, rate limit, and reset time.

Successful responses include X-Shipping-Plan, X-Shipping-Usage-Limit, X-Shipping-Usage-Used, X-Shipping-Usage-Remaining, and X-Shipping-Usage-Reset headers.

Errors

Label purchasing

Buying an eBay label is a different operation. It requires the seller's eBay authorization and access to eBay's restricted Logistics API. /v1/shipping/rates only returns estimates and never purchases a label.