UPS Ground Freight

ShipEngine's integration with UPS allows you to take advantage of UPS Ground Freight pricing (GFP).

UPS Ground Freight is not listed as a UPS service. Instead, it is considered advanced option. However, GFP is not returned in the list of advanced options when you list carrier options.

The examples below will demonstrate how to get rates for a UPS Ground Freight shipment and create a label for a UPS Ground Freight shipment.

Understanding Freight Classifications (NMFC)

Freight classifications are derived from the National Motor Freight Traffic Association. Your freight package will fall into one of the 18 supported freight classifications (otherwise known as the NMFC, short for National Motor Freight Classification).

The classes range from 50 to 500 and there are many tools online to help determine which estimated freight class you'll fall into. For example, lighter but larger items are going to be the higher classes while heavier but smaller items are going to be the lower classes.

Supported Freight Classes

50
55
60
65
70
77.5
85
92.5
100
110
125
150
175
200
250
300
400
500

Rating a UPS Ground Freight Shipment

When getting rates, GFP rates will not be returned unless explicitly requested. This means, you need to make two separate rate calls for ups_ground and ups_ground_freight in order to compare them.

To use UPS Ground Freight rating, you will provide two properties in the advanced options object for the shipment: use_ups_ground_freight_pricing and freight_class.

1
2
3
4
5
6
{
  "advanced_options": {
    "use_ups_ground_freight_pricing": true,
    "freight_class": "50"
  }
}

Example Rate Request & Response

This example includes the necessary values in a request to the rates endpoint.

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
POST /v1/rates HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment": {
    "advanced_options": {
      "use_ups_ground_freight_pricing": true,
      "freight_class": "175"
    },
    "validate_address": "no_validation",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "weight": {
          "value": 20.0,
          "unit": "pound"
        },
        "dimensions": {
          "unit": "inch",
          "length": 20.0,
          "width": 20.0,
          "height": 20.0
        }
      }
    ]
  },
  "rate_options": {
    "carrier_ids": [
      "se-123890"
    ]
  }
}

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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
{
  "rate_response": {
    "rates": [
      {
        "rate_id": "se-10523",
        "rate_type": "shipment",
        "carrier_id": "se-3143",
        "shipping_amount": {
          "currency": "usd",
          "amount": 206.38
        },
        "insurance_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "confirmation_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "other_amount": {
          "currency": "usd",
          "amount": 0.00
        },
        "rate_details": [
          {
            "rate_detail_type": "shipping",
            "carrier_description": null,
            "carrier_billing_code": "Base Rate",
            "carrier_memo": null,
            "amount": {
              "currency": "usd",
              "amount": 206.38
            },
            "billing_source": "Carrier"
          }
        ],
        "zone": null,
        "package_type": null,
        "delivery_days": 5,
        "guaranteed_service": false,
        "estimated_delivery_date": "2019-07-25T05:00:00.000ZPlus3$",
        "carrier_delivery_days": "Tuesday 1/23 by 11:00 PM",
        "ship_date": "2019-07-25T05:00:00.000Z",
        "negotiated_rate": false,
        "service_type": "UPS® Ground",
        "service_code": "ups_ground_freight",
        "trackable": true,
        "carrier_code": "ups",
        "carrier_nickname": "UPS",
        "carrier_friendly_name": "UPS",
        "validation_status": "valid",
        "warning_messages": [],
        "error_messages": []
      }
    ],
    "invalid_rates": [],
    "rate_request_id": "se-10126",
    "shipment_id": "se-1001161",
    "created_at": "2019-07-25T15:24:46.657Z",
    "status": "completed",
    "errors": []
  },
  "shipment_id": "se-1001161",
  "carrier_id": null,
  "service_code": null,
  "external_shipment_id": null,
  "ship_date": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "modified_at": "2019-07-25T15:24:46.657Z",
  "shipment_status": "pending",
  "ship_to": {
    "name": "Amanda Miller",
    "phone": "555-555-5555",
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US",
    "address_residential_indicator": "yes"
  },
  "ship_from": {
    "company_name": "Example Corp.",
    "name": "John Doe",
    "phone": "111-111-1111",
    "address_line1": "4009 Marathon Blvd",
    "address_line2": "Suite 300",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78756",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "warehouse_id": null,
  "return_to": {
    "company_name": "Example Corp.",
    "name": "John Doe",
    "phone": "111-111-1111",
    "address_line1": "4009 Marathon Blvd",
    "address_line2": "Suite 300",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78756",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "confirmation": "none",
  "customs": null,
  "advanced_options": {
    "bill_to_account": null,
    "bill_to_country_code": null,
    "bill_to_party": null,
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "non_machinable": false,
    "saturday_delivery": false,
    "delivered_duty_paid": false,
    "use_ups_ground_freight_pricing": true,
    "freight_class": "175"
  },
  "insurance_provider": "none",
  "tags": [],
  "packages": [
    {
      "package_code": "package",
      "weight": {
        "value": 20.00,
        "unit": "pound"
      },
      "dimensions": {
        "unit": "inch",
        "length": 20.00,
        "width": 20.00,
        "height": 20.00
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.00
      },
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null
      }
    }
  ],
  "total_weight": {
    "value": 20.00,
    "unit": "pound"
  }
}

Create a Label for UPS Ground Freight

Similar to rating a UPS Ground Freight shipment, a label requires the service_code property and then the advanced_options object with the freight_class property.

1
2
3
4
5
6
{
  "service_code": "ups_ground_freight",
  "advanced_options": {
    "freight_class": "50"
  }
}

Example Label Request & Response

This example includes the necessary values in a request to the labels endpoint.

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment": {
    "service_code": "ups_ground_freight",
    "advanced_options": {
      "freight_class": "150"
    },
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "weight": {
          "value": 20.0,
          "unit": "pound"
        },
        "dimensions": {
          "unit": "inch",
          "length": 20.0,
          "width": 20.0,
          "height": 20.0
        }
      }
    ]
  }
}

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
{
  "label_id": "se-1021",
  "status": "completed",
  "shipment_id": "se-1001165",
  "ship_date": "2019-07-29T05:00:00.000Z",
  "created_at": "2019-07-29T13:33:10.169Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 176.86
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "rate_details": [
    {
      "rate_detail_type": "shipping",
      "carrier_description": null,
      "carrier_billing_code": "Base Rate",
      "carrier_memo": null,
      "amount": {
        "currency": "usd",
        "amount": 176.86
      },
      "billing_source": "Carrier"
    }
  ],
  "tracking_number": "1ZR3890Y0395642846",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-3143",
  "service_code": "ups_ground_freight",
  "package_code": "package",
  "voided": false,
  "voided_at": null,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": true,
  "carrier_code": "ups",
  "tracking_status": "in_transit",
  "label_download": {
    "href": "https://api.shipengine.com/v1/downloads/1/xG1ydsrzJkuRsG3VL_Talg/label-1021.pdf"
  },
  "form_download": null,
  "insurance_claim": null,
  "packages": [
    {
      "package_code": "package",
      "weight": {
        "value": 20.00,
        "unit": "pound"
      },
      "dimensions": {
        "unit": "inch",
        "length": 20.00,
        "width": 20.00,
        "height": 20.00
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.00
      },
      "tracking_number": "1ZR3890Y0395642846",
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null
      }
    }
  ]
}