Rate Shop API

Try Now

POST https://api.piyovi.io/v1/shipment/rate

Overview

The Rate Shop API allows you to retrieve and compare shipping rates from multiple carriers based on shipment details. This helps identify the most cost-effective or time-efficient shipping options for your needs.

Authentication

This API requires authentication using one of the following methods:

Bearer Token: Include JWT with Bearer prefix in the Authorization header
API Key: Include X-API-KEY header with your API key

For more details, see Authentication Guide.

Request Format

POST /v1/shipment/rate
Content-Type: application/json
Authorization: Bearer {token}

Request Body

{
  "client": "MyClient",
  "shipDate": "2025-03-20T14:00:00Z",
  "shipFrom": {
    "companyName": "Your Company",
    "contactName": "Jane Smith",
    "address1": "456 Warehouse Blvd",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "shipTo": {
    "companyName": "Client Corp",
    "contactName": "Bob Johnson",
    "address1": "789 Client St",
    "city": "Los Angeles",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "90001"
  },
  "packages": [
    {
      "weight": 10.5,
      "length": 15,
      "width": 12,
      "height": 8,
      "type": "Box"
    }
  ],
  "shipmentInfo": {
    "shipMethod": "Ground",
    "paymentType": "Prepaid"
  },
  "unitOfWeight": "LB",
  "unitOfLength": "IN"
}

Response Format

Success Response (200 OK)

{
  "success": true,
  "responses": [
    {
      "carrierDisplayName": "FedEx",
      "carrierName": "FEDEX",
      "rates": [
        {
          "serviceDisplayName": "FedEx Ground",
          "serviceName": "GROUND",
          "serviceDescription": "1-5 business days",
          "shipMethod": "Ground",
          "freight": 45.67,
          "discountFrieght": 41.10,
          "baseCharge": 39.99,
          "totalSurcharges": 5.68,
          "totalTaxes": 0.00,
          "currencycode": "USD",
          "transitDays": "3",
          "estimatedDelivery": "2025-03-23T17:00:00Z",
          "surcharges": [
            {
              "name": "Fuel Surcharge",
              "code": "FUEL",
              "amount": 3.45,
              "currencyCode": "USD"
            }
          ]
        },
        {
          "serviceDisplayName": "FedEx Express Saver",
          "serviceName": "EXPRESS_SAVER",
          "serviceDescription": "3 business days",
          "shipMethod": "Express",
          "freight": 65.43,
          "discountFrieght": 58.89,
          "baseCharge": 55.65,
          "totalSurcharges": 9.78,
          "transitDays": "3",
          "estimatedDelivery": "2025-03-23T12:00:00Z"
        }
      ]
    },
    {
      "carrierDisplayName": "UPS",
      "carrierName": "UPS",
      "rates": [
        {
          "serviceDisplayName": "UPS Ground",
          "serviceName": "GROUND",
          "serviceDescription": "1-5 business days",
          "shipMethod": "Ground",
          "freight": 48.32,
          "discountFrieght": 43.49,
          "baseCharge": 41.22,
          "totalSurcharges": 7.10,
          "transitDays": "3",
          "estimatedDelivery": "2025-03-23T17:00:00Z"
        }
      ]
    }
  ]
}

Error Response (400 Bad Request)

{
  "success": false,
  "errors": [
    {
      "code": "InvalidShipment",
      "message": "Unable to retrieve rates for the provided shipment details",
      "type": "ValidationError"
    }
  ]
}

Field Reference

Request Fields

Field	Type	Required	Description
client	string	No	Client identifier
shipDate	datetime	Yes	Date when the shipment will be sent
shipTo	object	Yes	Destination address details
shipFrom	object	Yes	Origin address details
packages	array	Yes	Package details
shipmentInfo	object	No	Shipping method and carrier preferences
unitOfWeight	string	No	Unit of measurement for weight (e.g., KG, LB)
unitOfLength	string	No	Unit of measurement for dimensions (e.g., CM, IN)
internationalDetail	object	No	International shipping information (required for international shipments)
specialService	object	No	Special service requirements
notes	string	No	Special instructions

Address Object Fields (shipTo, shipFrom)

Field	Type	Required	Description
companyName	string	No	Company name
contactName	string	No	Contact person's name
emailAddress	string	No	Email address
phoneNumber1	string	No	Primary phone number
address1	string	Yes	Street address line 1
address2	string	No	Street address line 2
city	string	Yes	City name
stateProvince	string	Yes	State or province
country	string	Yes	Country code (2-letter ISO code recommended)
zipPostalCode	string	Yes	Postal or ZIP code

Package Object Fields

Field	Type	Required	Description
weight	number	Yes	Weight of the package
length	number	Yes	Length of the package
width	number	Yes	Width of the package
height	number	Yes	Height of the package
type	string	No	Type of package (e.g., Box, Pallet)
freightClass	string	No	Freight classification (for LTL shipments)
nmfcCode	string	No	NMFC code for freight
declaredValue	number	No	Declared value for insurance
count	integer	No	Count of packages

Shipment Info Object Fields

Field	Type	Required	Description
shipMethod	string	No	Method of shipment (e.g., Ground, Express)
carrier	string	No	Preferred carrier name
serviceLevel	string	No	Preferred service level
paymentType	string	No	Payment method (e.g., Prepaid, Collect)

Response Fields

Field	Type	Description
success	boolean	Indicates if rate retrieval was successful
responses	array	Array of carrier rate responses

Carrier Response Object Fields

Field	Type	Description
carrierDisplayName	string	Display name of the carrier
carrierName	string	Internal name of the carrier
rates	array	Array of rate options

Rate Object Fields

Field	Type	Description
serviceDisplayName	string	Display name of the service level
serviceName	string	Internal name of the service level
serviceDescription	string	Description of the service
shipMethod	string	Shipping method
freight	number	Published freight cost
discountFrieght	number	Discounted freight cost
baseCharge	number	Base charge before surcharges
totalSurcharges	number	Total of all surcharges
totalTaxes	number	Total taxes
transitDays	string	Estimated transit time in days
currencycode	string	Currency code for monetary values
estimatedDelivery	datetime	Estimated delivery date and time
surcharges	array	Detailed breakdown of surcharges

Examples

Basic Domestic Rate Request

{
  "client": "ExampleClient",
  "shipDate": "2025-03-20T14:00:00Z",
  "shipFrom": {
    "companyName": "Sender Inc",
    "address1": "123 Shipping Ave",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  },
  "shipTo": {
    "companyName": "Recipient Corp",
    "address1": "456 Delivery St",
    "city": "Los Angeles",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "90001"
  },
  "packages": [
    {
      "weight": 15.5,
      "length": 18,
      "width": 12,
      "height": 10,
      "type": "Box"
    }
  ],
  "unitOfWeight": "LB",
  "unitOfLength": "IN"
}

International Rate Request

{
  "client": "GlobalClient",
  "shipDate": "2025-03-25T10:00:00Z",
  "shipFrom": {
    "companyName": "Exporter Inc",
    "address1": "789 Export Road",
    "city": "New York",
    "stateProvince": "NY",
    "country": "US",
    "zipPostalCode": "10001"
  },
  "shipTo": {
    "companyName": "International Corp",
    "address1": "123 Global Street",
    "city": "Berlin",
    "stateProvince": "Berlin",
    "country": "DE",
    "zipPostalCode": "10115"
  },
  "packages": [
    {
      "weight": 5.2,
      "length": 15,
      "width": 10,
      "height": 8,
      "type": "Box"
    },
    {
      "weight": 7.8,
      "length": 20,
      "width": 12,
      "height": 10,
      "type": "Box"
    }
  ],
  "internationalDetail": {
    "dutiesPaidBy": "Sender",
    "totalCustomValue": 600,
    "reasonToExport": "Commercial Sample",
    "incoTerm1": "DAP",
    "currencyCode": "USD",
    "commodities": [
      {
        "description": "Product Samples",
        "numberOfBoxes": 2,
        "quantity": 10,
        "unitWeight": 1.3,
        "unitPrice": 60,
        "customValue": 600,
        "countryOfOrigin": "US"
      }
    ]
  },
  "unitOfWeight": "KG",
  "unitOfLength": "CM"
}

Rate Request with Carrier Preferences

{
  "client": "PreferredClient",
  "shipDate": "2025-03-22T09:00:00Z",
  "shipFrom": {
    "companyName": "Origin Corp",
    "address1": "100 Start St",
    "city": "Dallas",
    "stateProvince": "TX",
    "country": "US",
    "zipPostalCode": "75201"
  },
  "shipTo": {
    "companyName": "Destination LLC",
    "address1": "200 End Blvd",
    "city": "Miami",
    "stateProvince": "FL",
    "country": "US",
    "zipPostalCode": "33101"
  },
  "packages": [
    {
      "weight": 12.0,
      "length": 16,
      "width": 14,
      "height": 9,
      "type": "Box"
    }
  ],
  "shipmentInfo": {
    "shipMethod": "Express",
    "carrier": "FedEx",
    "serviceLevel": "PRIORITY"
  },
  "unitOfWeight": "LB",
  "unitOfLength": "IN"
}

Notes

Always provide accurate dimensions and weight to get precise rate quotes.
For international shipments, include complete customs information in the internationalDetail object.
The response includes rates from multiple carriers and service levels to allow for comparison.
Transit times and estimated delivery dates are approximations and may vary based on actual shipping conditions.
Currency codes in the response match the carrier's default currency or the currency specified in the request.

Try Now​

Overview​

Authentication​

Request Format​

Request Body​

Response Format​

Success Response (200 OK)​

Error Response (400 Bad Request)​

Field Reference​

Request Fields​

Address Object Fields (shipTo, shipFrom)​

Package Object Fields​

Shipment Info Object Fields​

Response Fields​

Carrier Response Object Fields​

Rate Object Fields​

Examples​

Basic Domestic Rate Request​

International Rate Request​

Rate Request with Carrier Preferences​

Notes​