Rating a Package

Compare real-time shipping rates across multiple carriers.

Overview

Use the rate query to get shipping costs for a package.
You can submit multiple rate requests in a single call and receive detailed pricing, estimated delivery, carrier-specific fees, and any errors that occurred during the request.

This is ideal for:

Showing customers multiple shipping options at checkout
Pre-calculating shipping costs before label generation
Testing carrier pricing across accounts and services

Query Format

query getRate($request: [RateInput!]!, $services: [CarrierServiceRateInput!]!) {
    rate(request: $request, services: $services) {
        request_id
        rates {
            __typename
            account_number
            carrier
            requested_rate_class
            service_code

            ... on Rate {
                actual_rate_class
                base_price
                total_price
                labelgenius_charge
                estimated_delivery
                guaranteed_delivery
                billing_weight
                disclaimers
                rate_id
                itemized_charges {
                    code
                    charge_amount
                }
                warnings {
                    code
                    message
                }
                carrier_specific
            }

            ... on RateError {
                code
                message
            }
        }
    }
}

Successful Rate Response

When the request is valid, the API returns a list of one or more rate objects under data.rate.rates.

BulkRateResponse

{
    "data": {
        "rate": [
            {
                "request_id": "abc123",
                "rates": [
                    {
                        "__typename": "Rate",
                        "carrier": "UPS",
                        "service_code": "GND",
                        "requested_rate_class": "NEGOTIATED",
                        "actual_rate_class": "NEGOTIATED",
                        "total_price": 8.73,
                        "base_price": 7.91,
                        "labelgenius_charge": 0.1,
                        "estimated_delivery": "2025-06-26",
                        "guaranteed_delivery": null,
                        "account_number": "123456",
                        "rate_id": "5c9e0d72-3f81-4a65-b0d9-7e24c1839af5",
                        "billing_weight": 1.5,
                        "disclaimers": ["Delivery dates are estimates only."],
                        "carrier_specific": {},
                        "itemized_charges": [
                            {
                                "code": "BASE_CHARGE",
                                "charge_amount": 7.91
                            },
                            {
                                "code": "FUEL_SURCHARGE",
                                "charge_amount": 0.82
                            }
                        ],
                        "warnings": [
                            {
                                "code": "RESIDENTIAL_SURCHARGE",
                                "message": "Delivery address is residential."
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Required Input

A rate request must contain:

`services` CarrierServiceRateInput

Use this to specify which carrier and service(s) you'd like to receive rates for.

Fields:

carrier: Required – one of the supported carrier codes (e.g. UPS, USPS, FedEx, DHL)
service_code: Required – the specific service you'd like to rate
Examples include:
- GND (UPS Ground)
- USPS_PRIORITY_MAIL (USPS Priority Mail)
account_number: Optional – your shipper account to use for rating.
If omitted, the default platform account will be used (if allowed).
rate_class: Required – defines which type of rate to return (e.g. STANDARD, COMMERCIAL, NEGOTIATED)

Supported `service_code` Values

TIP

use EntitySearches to help find a list of up to date available carrier service codes.

`request` RateInput

request_id: String Echoed ID in response to help match client-side requests.
override_services: CarrierServiceRateInput

NOTE

This list overrides the services provided to Query.rate Use it to narrow or customize the rating request for this specific shipment.
carrier_specific: ShipmentCarrierInput Carrier specific config
additional: AdditionalInfoInput Additional shipment metadata
package: PackageRateInput
- ship_from: AddressInput Origin address
- ship_to: AddressInput Destination address
- packaging: Packaging One of:
  - custom_box (requires length, width, height)
  - custom_bag (requires girth, length, width, height)
  - carrier_specific (carrier-provided packaging such as a USPS Flat Rate Box or FedEx Envelope — see Carrier-Provided Packaging)
- weight: WeightInput The total shipment weight in imperial or metric
Optional fields:
- return_address: AddressInput If different from ship_from
- extra_services: ExtraService Insurance, signature, Saturday delivery, etc.
- hazmat: HazmatInfo Lithium batteries, dry ice, etc.
- customs: CustomsInput Required for international shipments

Carrier-Provided Packaging

Instead of giving custom dimensions, a package can be declared as packaging the carrier itself provides by setting packaging.carrier_specific with the carrier code and that carrier's package code:

{
    "packaging": {
        "carrier_specific": {
            "carrier": "FedEx",
            "package_code": "FEDEX_ENVELOPE"
        }
    }
}

No dimensions are required — the carrier already knows the size of its own packaging. The same packaging input is used when purchasing a label, so a shipment can be rated and shipped in this packaging end to end.

TIP

Use the shipping.carrier_packaging query to list the up-to-date packaging options, including each option's name, code, dimensions, and restrictions.

FedEx

`package_code`	Packaging	Restrictions
`FEDEX_ENVELOPE`	FedEx Envelope	Maximum weight 1 lb (0.5 kg)
`FEDEX_PAK`	FedEx Pak	Maximum weight 20 lb (9 kg)
`FEDEX_TUBE`	FedEx Tube	Maximum weight 20 lb (9 kg)
`FEDEX_BOX`	FedEx Box	Maximum weight 20 lb (9 kg)
`FEDEX_EXTRA_SMALL_BOX`	FedEx Extra Small Box	Maximum weight 20 lb (9 kg)
`FEDEX_SMALL_BOX`	FedEx Small Box	Maximum weight 20 lb (9 kg)
`FEDEX_MEDIUM_BOX`	FedEx Medium Box	Maximum weight 20 lb (9 kg)
`FEDEX_LARGE_BOX`	FedEx Large Box	Maximum weight 20 lb (9 kg)
`FEDEX_EXTRA_LARGE_BOX`	FedEx Extra Large Box	Maximum weight 20 lb (9 kg)
`FEDEX_10KG_BOX`	FedEx 10kg Box	Maximum weight 22 lb (10 kg)
`FEDEX_25KG_BOX`	FedEx 25kg Box	Maximum weight 55 lb (25 kg)

USPS

`package_code`	Packaging
`ENVELOPE`	Priority Mail Flat Rate Envelope
`LEGAL_ENVELOPE`	Priority Mail Flat Rate Legal Envelope
`PADDED_ENVELOPE`	Priority Mail Flat Rate Padded Envelope
`WINDOW_ENVELOPE`	Priority Mail Flat Rate Small Window Envelope
`SMALL_BOX`	Priority Mail Small Flat Rate Box
`MEDIUM_BOX`	Priority Mail Medium Flat Rate Box
`SIDE_LOAD_MEDIUM_BOX`	Priority Mail Flat Rate Side-Loading Medium Box
`LARGE_BOX`	Priority Mail Large Flat Rate Box
`LARGE_BOX_MILITARY`	Priority Mail APO/FPO/DPO
`EXPRESS_ENVELOPE`	Priority Mail Express Flat Rate Envelope
`EXPRESS_LEGAL_ENVELOPE`	Priority Mail Express Legal Flat Rate Envelope
`EXPRESS_PADDED_ENVELOPE`	Priority Mail Express Flat Rate Padded Envelope

Shipping →