Zonos logo
DOCS

Request a shipment rating

/

Request a shipment rating

Rating API 

Request international shipping rates for various shipping providers that are configured in your store’s settings within Zonos.

Click here to learn more about setting up your shipping carriers within Zonos.

POST | https://api.zonos.com/v1/shipment_rating

HEADER zonos-version: 2020-03-04

The header ⬆ Attribution for Twitter Emojis: ©️ Twitter, Inc. above is a required input for this rating request to complete successfully.

JSON KEY/VALUE PAIRS in the request body

currency REQUIREDThe base currency string, represented by a three-letter ISO code.
items_amount REQUIREDA decimal with an item amount.
packages REQUIREDA list of the number and dimensions for the packages being shipped. hash
packages.id REQUIREDThe unique package identifier for the merchant or exporter.
packages.dimensions REQUIREDThe dimensions for the package. hash
packages.dimensions.height REQUIREDA decimal for the height of the package.
packages.dimensions.length REQUIREDA decimal for the length of the package.
packages.dimensions.unit REQUIREDThe unit of measurement for the package dimensions.Possible values are inch centimeter millimeter null.When null, inch will be used.
packages.dimensions.width REQUIREDA decimal containing the width of the package.
packages.insured_amount OPTIONALA decimal with the insurance amount.
packages.type OPTIONALA string to specify a specific carrier box type to be used for the shipping calculation. Possible values include FEDEX_BOX
packages.weight REQUIREDA decimal containing the weight of the package.
packages.weight_unit REQUIREDA string with the unit of measurement for the weight.Possible values are pound ounce kilogram null.When null, pound will be used.
pickup_date REQUIREDThe requested pickup date for the package, in the ISO 8601 format YYYY-MM-DDTHH:mm:ss.sssZ. UTC is assumed when no time zone information is passed.
service_level OPTIONALThe service_level with the carrier, e.g. standard. hashCommon examples include: ups_express, ups_express_saver, ups_expedited, ups_economy, ups_standard, ups_mail_innovations_economy, ups_mail_innovations_priority, dhl_express, dhl_ecommerce_parcel_direct, fedex_priority, fedex_economy, usps_first_class_mail_international, usps_priority_mail_international, landmark_parcel, apc_parcel, point2point_standard, point2point_direct, point2point_packet, and fedex_international_groundSee the carrier docs for the full list of available service levels by carrier.
ship_from REQUIREDThe origin address. hash
ship_from.cityA string for the address city, town, district, suburb, or village of the origin address.
ship_from.country REQUIREDThe origin country string, represented by a two-letter ISO code.
ship_from.postal_code REQUIREDA string for the origin address postal code.
ship_from.state_code REQUIREDA string for the origin address when available. Only required in Canada and Brazil.
ship_to REQUIREDThe destination address. hash
ship_to.city REQUIREDA string for the address city, town, district, suburb, or village of the customer.
ship_to.country REQUIREDA string for the destination country, represented by a two-letter ISO code.
ship_to.postal_code REQUIREDA string for the destination postal code. Optional depending on the country of import.
ship_to.state_code REQUIREDA string for the destination state code when available. Only required in Canada and Brazil.
ship_to.type REQUIREDThe type of the destination address. Possible values include residential commercial.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "currency": "USD",
  "items_amount": 168.99,
  "packages": [
    {
      "id": "1",
      "dimensions": {
        "height": 19.0,
        "length": 15.0,
        "unit": "inch",
        "width": 15.0
      },
      "insured_amount": 33.22,
      "type": null,
      "weight": 32.0,
      "weight_unit": "pound"
    }
  ],
  "pickup_date": "2020-07-06T18:47:04.629+0000",
  "service_level": null,
  "ship_from": {
    "city": "St George",
    "country": "US",
    "postal_code": "84770",
    "state_code": "UT"
  },
  "ship_to": {
    "city": "Campinas",
    "country": "BR",
    "postal_code": "75828-000",
    "state_code": "SP",
    "type": "residential"
  }
}

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
{
  "id": "ship_5p67angIDnS91CyfpW55YZ",
  "currency": {
    "id": "curr_1Rp9lhXSRXvEWVs97k2PHE",
    "base": "USD",
    "date": "2020-02-04T18:47:04.629+0000",
    "rates": []
  },
  "errors": [
    {
      "details": {
        "id": "rtqt_7cz80Ny8dToSqoWlHTJJnP",
        "service_level": "FEDEX_EXPRESS_SAVER",
        "display_name": "FedEx Express Saver"
      },
      "message": "[868] Service is not allowed.  ",
      "type": "fedex_api"
    }
  ],
  "quotes": [
    {
      "id": "rtqt_4BUyxLEUeoU6zDdprCRoUV",
      "amount_subtotal": 943.18,
      "mode": {
        "delivery_date_estimate": null,
        "display_name": "UPS Expedited ",
        "rates": [
          {
            "amount": 848.31,
            "note": "UPS api: standard rate",
            "type": "retail_shipping"
          },
          {
            "amount": 64.4,
            "note": "UPS api: fuel surcharge",
            "type": "fuel_surcharge"
          },
          {
            "amount": 40.0,
            "note": "UPS api: extended area",
            "type": "carrier_fee"
          },
          {
            "amount": -9.53,
            "note": "UPS negotiated discount",
            "type": "negotiated_discount"
          }
        ],
        "service_level": "UPS_WORLDWIDE_EXPEDITED",
        "transit_business_days": null,
        "transit_days": null
      },
      "packages": [
        {
          "id": "1",
          "weight": {
            "billable": 32.0,
            "dimensional": 30.7554,
            "factor": 139,
            "weight_unit": "pound"
          }
        }
      ],
      "weight": {
        "billable": 32.0,
        "unit": "pound"
      }
    },
    {
      "id": "rtqt_1jyuPdiE5uIBcYzhO54DAb",
      "amount_subtotal": 1058.86,
      "weight": {
        "billable": 32.0,
        "unit": "pound"
      },
      "mode": {
        "delivery_date_estimate": null,
        "display_name": "UPS Saver ",
        "rates": [
          {
            "amount": 957.26,
            "note": "UPS api: standard rate",
            "type": "retail_shipping"
          },
          {
            "amount": 72.3,
            "note": "UPS api: fuel surcharge",
            "type": "fuel_surcharge"
          },
          {
            "amount": 40.0,
            "note": "UPS api: extended area",
            "type": "carrier_fee"
          },
          {
            "amount": -10.7,
            "note": "UPS negotiated discount",
            "type": "negotiated_discount"
          }
        ],
        "service_level": "UPS_SAVER",
        "transit_business_days": null,
        "transit_days": null
      },
      "packages": [
        {
          "id": "1",
          "weight": {
            "billable": 32.0,
            "dimensional": 30.7554,
            "factor": 139,
            "weight_unit": "pound"
          }
        }
      ]
    }
  ]
}