Rate a Parcel

HTTP Request

POST /v1/rates

Summary

Use this operation to rate a parcel before you print and purchase a shipment label. You can rate a parcel for multiple services and multiple parcel types with a single API request.

Things to Consider

  1. You can rate parcels for USPS, CBDS, FedEx, and UPS.
  2. To rate a parcel for a single service, include the serviceId in the request body. The response will return a single Rates Object.
  3. To rate a parcel for multiple services for a given parcel type, omit the serviceId field from the request body. The response will contain a separate Rates Object for each service rated.
  4. At minimum, the following address fields are required in the fromAddress and toAddress objects. Depending on the carrier, additional fields might also be required:
    • addressLines
    • postalCode
    • countryCode
  5. The SHIPPER_ID should be included in the shipmentOptions array to ensure the request returns the correct rates.
  6. USPS only: To rate a parcel for multiple services and parcel types at once, omit both the serviceId and parcelType fields in the request body. The response will contain a separate Rates Object for each combination of service and parcel type rated.
  7. When issuing the API call, you can pass only one Rates Object in the request body, as shown in the Sample Requests below. The response, however, might contain multiple Rates Objects (as described above).
  8. For the available services and parcel types, see the carrier’s reference page.
  9. USPS only: The PB Shipping APIs require that all parcels be trackable. If you are rating a service that is not trackable, such as Priority Mail (PM), add at least one trackable special service, such as Delivery Confirmation (DelCon). DelCon is a no-charge service that triggers tracking but does not increase the cost of the shipment. Before adding a special service, check its compatibility with the service.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/rates
Production: https://api.pitneybowes.com/shippingservices/v1/rates

Query Parameter

The query parameter is optional.

Name Description
includeDeliveryCommitment

When set to true, returns estimated transit time. Transit time is returned as number of days.

Valid values:

  • true
  • false
carrier CBDS only. Required for PB Cross-Border Delivery Service (CBDS). Set this to PBI.

Request Headers

Name
Description
Authorization Required. OAuth Token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.
X-PB-Shipper-Rate-Plan USPS Only. Shipper rate plan, if applicable. For more information, see this FAQ.
X-PB-Integrator-CarrierId USPS Only. Negotiated services rate, if applicable.
X-PB-Shipper-Carrier-AccountId

Conditional. The unique identifier for the carrier account. To retrieve the identifier, see this FAQ.

This header is required if the merchant has registered multiple accounts for the same carrier. For more information, see Carrier Account Registration.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

The Rates API sends and receives a Shipment Object. The table below describes all possible fields in a Shipment Object. Some do not apply to this operation and are marked as such.

Important

Some fields in the Shipment Object do not apply to the Rates API.

Name Data Type Description
fromAddress Address Object

Required. Origin address.

If you want a different address to appear on the label from the one listed here, see How do I print a return address that is different from the origin address?

toAddress Address Object

Required. Destination address.

FedEx, UPS: If you are shipping with FedEx or UPS to Puerto Rico or an international destination, and if the importer is different from the final recipient, this is the address of the importer. Enter the recipient’s address in the soldToAddress object. If importer’s address is the same as the final recipient, the toAddress and soldToAddress must match.

altReturnAddress Address Object

Applies only to the following:

  • USPS: If you are sending an international shipment through USPS and if you have set the NON_DELIVERY_OPTION shipment option to redirect, then enter the address that a returned parcel should go to.
  • CBDS: For a Create Shipment request, this is the address used to return a parcel from the CBDS Consolidation Center. If omitted, the fromAddress is used. The altReturnAddress is not returned in the response.
parcel Parcel Object Required. Contains physical characteristics of the parcel.
rates Array[Rates Object]

Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges.

Important: In a request, the rates array can contain only one rates object.

documents Array[Documents Object]

Conditional. Defines the label, manifest, or other shipping document created by the API call.

This field is required except in the following cases:

  • This field does not apply to Rate Parcel requests.
  • This field does not apply to the Create CBDS Shipment request if the merchant prints the first-label prior to invoking the API.
shipmentOptions Array[Object]

Required. Each object in this array defines a shipment option. Specify each option as a name-value pair in the array.

The SHIPPER_ID option is required. For any additional requirements for a carrier or service, please see the Things to Consider section on the carrier’s Create Shipment page.

        name String The name of the shipment option.
        value String The value of the shipment option.
customs Object

Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for the following carriers in the following situations:

  • USPS: Required for shipments to international destinations and to APO/FPO/DPO, Territories/Possessions, and FAS
  • CBDS: Required for all shipments
  • FedEx: Required for shipments to international destinations and Puerto Rico
  • UPS: Required for shipments to international destinations and Puerto Rico
        customsInfo Customs Info Object Customs clearance information used to fill out a commercial invoice.
        customsItems Array[Customs Items Object]

Information about each commodity in the shipment, used for customs clearance.

The maximum number of objects in this array is 30.

domesticShipmentDetails Domestic Shipment Details Object CBDS Only. Required if the merchant prints the first-mile label prior to invoking the Create CBDS Shipment API. This object contains information about the first-mile leg of the shipment.
soldToAddress Address Object

Applies only to FedEx and UPS. This contains the final recipient of a United Parcel Service shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional.

This address must match the toAddress.countryCode, with the exception of shipments to Canada and to U.S. satellite countries.

If the final recipient’s address is the same as the importer’s address, the entries in the soldToAddress object must match the entries in the toAddress object.

shipmentType String Return Labels Only. Set this to RETURN. Required for Expedited Returns and Standard Returns.
references Array[Object]

Merchant-defined values. Applies to the following:

shipmentId String RESPONSE ONLY. Unique identifier for the shipment, generated by the system in response to shipment purchase.
parcelTrackingNumber String RESPONSE ONLY. Tracking number assigned to the shipment by the system.

Request / Response Elements: Rates Object

The rates array takes one Rates Object in the request and returns one or more Rates Objects in the response. In the response, each object shows a different rating option.

Important

The following table describes all fields and values in the Rates Object. Some might not apply to this operation.

Name
Data Type Description
carrier String

Required. Carrier name. Valid values are:

  • USPS
  • NEWGISTICS: PB Standard. This value is available only for Create Shipment requests.
  • PBPRESORT: This value is available only for Create Shipment requests.
  • PBI: PB Cross-Border Delivery Service (CBDS)
  • FEDEX
  • UPS
serviceId String

Conditional. The abbreviated name of the carrier-specific service. For abbreviations, see the Services table on the carrier’s reference page.

Required for creating a shipment. Optional for rating a parcel.

If you use USPS as the carrier:

  • To determine any additional restrictions on a USPS service, use the Carrier Rules API. See also the USPS Domestic Mail Manual.
  • The PB Shipping APIs require that all USPS parcels be trackable. If the parcel uses a service that is not trackable, such as Priority Mail, you must add at least one trackable special service, such as Delivery Confirmation (DelCon). DelCon is a no-charge special service that triggers tracking but does not increase the cost of the shipment. Before adding a special service, check its compatibility with the service.
parcelType String

Conditional. The parcel type. For supported parcel types, see the carrier’s reference page.

Required for:

  • Creating a shipment
  • Rating a FedEx or UPS parcel

Not applicable to the CBDS Checkout Quotes API.

specialServices Array[Special Services Object]

Conditional. The special services to be applied. For available special services and requirements, see the Special Services table on the carrier’s reference page.

Important

In a Create Shipment request, including a special service in this array means you intend to apply the special service.

This array is not applicable to the CBDS Checkout Quotes API.

inductionPostalCode String

The postal code where the shipment is tendered to the carrier. If this field is present, the postal code specified here is used instead of the postal code in the fromAddress when calculating rates and when determining if a shipment can be added to a manifest. If this field is absent, the postal code listed in the fromAddress is used instead.

This field applies to USPS, PB Presort, FedEx, and UPS.

currencyCode String

Type of currency referenced in the piece price. For example: USD, CAD, EUR

This field applies to USPS, CBDS, FedEx, and UPS.

dimensionalWeight Object

RESPONSE ONLY. USPS Only. If the dimensionalWeight.weight field has a value other than 0, dimensional-weight pricing applies to the shipment. In general, if a parcel is large and relatively light for its size, it might be subject to dimensional-weight pricing. Dimensional weight, or DIM weight, is calculated based on volume and a volumetric divisor. For information on how USPS calculates DIM weight, see https://www.usps.com/dimensionalweight/.

Note: A parcel might alternatively be subject to oversize pricing, as explained in the surcharges field below.

    weight Double The calculated DIM weight. For information on how USPS calculates DIM weight, see https://www.usps.com/dimensionalweight/.
    unitOfMeasurement String

The unit of measure for the calculated DIM weight. Possible values:

  • GM: Grams
  • OZ: Ounces
baseCharge Double

RESPONSE ONLY. The base service charge payable to the carrier, excluding special service charges. This field applies to USPS, CBDS, FedEx, and UPS.

USPS: If your request includes a shipper rate plan, see this FAQ on how the shipper rate affects this field.

totalCarrierCharge Double

RESPONSE ONLY. The total amount payable to the carrier, including special service fees, surcharges, and any international taxes and duties, except as noted below. This field applies to USPS, CBDS, FedEx, and UPS.

USPS: If your request includes a shipper rate plan, see this FAQ on how the shipper rate affects this field.

CBDS: In certain cases, the totalCarrierCharge might not reflect additional surcharges.

UPS: In Sandbox, the data UPS supplies for totalCarrierCharge might be incorrect. Specifically it might be 1% too low or exclude special service fees, or both. In Production, UPS provides the correct data.

surcharges Array[Object]

RESPONSE ONLY. Additional fees or surcharges for the shipment. Each object in this array has two fields, name and fee. For example:

{
    "name": "oversize",
    "fee": 128.91
}

This field applies to USPS, FedEx, and UPS.

    name String The type of surcharge. For possible surcharges, see the carrier’s reference page.
    fee Double The amount of the surcharge.
alternateBaseCharge Double

RESPONSE ONLY. USPS Only. If your request includes a shipper rate plan and if the shipper does not have an NSA, this is the base service charge payable by the shipper, excluding special service charges. The rate is based on the plan specified in the X-PB-Shipper-Rate-Plan parameter.

If the shipper has an NSA, do not use this field. Use the response’s baseCharge field instead. For more information, see this FAQ.

alternateTotalCharge Double

RESPONSE ONLY. USPS Only. If your request includes a shipper rate plan and if the shipper does not have an NSA, this is the total charge payable by the shipper, including special service charges. The rate is based on the plan specified in the X-PB-Shipper-Rate-Plan parameter.

If the shipper has an NSA, do not use this field. Use the response’s totalCarrierCharge field instead. For more information, see this FAQ.

deliveryCommitment Object

RESPONSE ONLY. Time in transit for the shipment. For USPS, see also: Pitney Bowes Delivery Guarantee

This field applies to USPS, FedEx, and UPS.

    minEstimatedNumberOfDays String The minimum number of delivery days.
    maxEstimatedNumberOfDays String The maximum number of delivery days.
    estimatedDeliveryDateTime String The estimated delivery date and time in the local time of the destination.
    guarantee String

States whether carrier delivery is guaranteed. Possible values:

  • FULL
  • NONE
    additionalDetails String These are carrier specific details that may be provided.
destinationZone BigDecimal RESPONSE ONLY. USPS Only. Destination Zone based on the fromAddress and toAddress specified.
rateTypeId String RESPONSE ONLY. The type of rate, such as COMMERCIAL_BASE (USPS) or COMMERCIAL (FedEx, UPS).
totalTaxAmount BigDecimal RESPONSE ONLY. The total tax amount payable to the carrier. This field applies to CBDS, FedEx, and UPS.
totalDutyAmount BigDecimal RESPONSE ONLY. The total duty amount payable to the carrier. This field applies to CBDS.

Sample Requests

See the following examples:

USPS Sample Request

USPS Sample Rate Request
curl -X POST .../v1/rates?includeDeliveryCommitment=false \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "OZ"
        },
        "dimension": {
            "length": 5,
            "width": 0.25,
            "height": 4.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 1.0
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "PKG",
        "inductionPostalCode": "06484"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'
USPS Sample Rate Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "OZ"
        },
        "dimension": {
            "length": 5,
            "width": 0.25,
            "height": 4.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 1.0
        }
    },
    "rates": [ {
        "carrier": "usps",
        "parcelType": "PKG",
        "serviceId": "EM",
        "dimensionalWeight": {
            "weight": 0.0,
            "unitOfMeasurement": "OZ"
        },
        "totalCarrierCharge": 39.45,
        "baseCharge": 39.45,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "5",
            "estimatedDeliveryDateTime": "",
            "guarantee": "NONE",
            "additionalDetails": "3 - 5 business days to many major markets"
        },
        "currencyCode": "USD"
    }, {
        "carrier": "usps",
        "parcelType": "PKG",
        "serviceId": "PM",
        "dimensionalWeight": {
            "weight": 0.0,
            "unitOfMeasurement": "OZ"
        },
        "totalCarrierCharge": 39.45,
        "baseCharge": 39.45,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "5",
            "estimatedDeliveryDateTime": "",
            "guarantee": "NONE",
            "additionalDetails": "3 - 5 business days to many major markets"
        },
        "currencyCode": "USD"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}

CBDS Sample Request

CBDS Sample Rate Request
curl -X POST .../v1/rates?includeDeliveryCommitment=false&carrier=PBI \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 20,
            "height": 5,
            "width": 10,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": "0.0"
        },
        "weight": {
            "weight": 170,
            "unitOfMeasurement": "OZ"
        }
    },
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "categories": [ {
                "categoryCode": "CAT",
                "descriptions": [ {
                    "locale": "en_US",
                    "name": "dress"
                } ]
            } ],
            "description": "dress",
            "itemId": "B004LB5FB9",
            "quantity": 2,
            "unitPrice": 10,
            "url": "www.example.com/dress"
        } ]
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "CBDS_0001"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ]
}'
CBDS Sample Rate Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 20,
            "height": 5,
            "width": 10,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": "0.0"
        },
        "weight": {
            "weight": 170,
            "unitOfMeasurement": "OZ"
        },
        "valueOfGoods": 20
    },
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "categories": [ {
                "categoryCode": "CAT",
                "descriptions": [ {
                    "locale": "en_US",
                    "name": "dress"
                } ]
            } ],
            "description": "dress",
            "itemId": "B004LB5FB9",
            "quantity": 2,
            "unitPrice": 10,
            "url": "www.example.com/dress"
        } ]
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "baseCharge": 38.21,
        "totalCarrierCharge": 43.73,
        "currencyCode": "USD",
        "totalTaxAmount": 5.52
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "CBDS_0001"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ]
}

FedEx Sample Request

The following request omits the serviceId field in order to rate the parcel for multiple services.

FedEx Sample Rate Request
curl -X POST .../v1/rates?includeDeliveryCommitment=true \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US"
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_account_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8.0
        }
    },
    "rates": [ {
        "carrier": "FEDEX",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'
FedEx Sample Rate Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 8.0
        }
    },
    "rates": [ {
        "carrier": "fedex",
        "parcelType": "PKG",
        "specialServices": [],
        "deliveryCommitment": {
            "additionalDetails": "By 12:00 of THU",
            "estimatedDeliveryDateTime": "2019-12-19 12:00:00",
            "guarantee": "FULL"
        },
        "serviceId": "2DA_AM",
        "baseCharge": 34.48,
        "currencyCode": "USD",
        "rateTypeId": "COMMERCIAL",
        "surcharges": [ {
            "fee": 2.85,
            "name": "DELIVERY_AREA"
        },{
            "fee": 2.8,
            "name": "FUEL"
        } ],
        "totalCarrierCharge": 40.13,
        "totalTaxAmount": 0.0
    }, ...
    { ... } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}

UPS Sample Request

The following request omits the serviceId field in order to rate the parcel for multiple services.

UPS Sample Rate Request
curl -X POST .../v1/rates?includeDeliveryCommitment=true \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US"
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_account_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 38
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 6,
            "width": 4,
            "height": 4
        }
    },
    "rates": [ {
        "carrier": "UPS",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'
UPS Sample Rate Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 38
        },
        "dimension": {
            "length": 6,
            "width": 4,
            "height": 4,
            "unitOfMeasurement": "IN"
        }
    },
    "rates": [ {
        "carrier": "ups",
        "parcelType": "PKG",
        "specialServices": [],
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "5",
            "maxEstimatedNumberOfDays": "5",
            "estimatedDeliveryDateTime": "2019-04-15 23:00:00",
            "guarantee": "FULL"
        },
        "serviceId": "GRD",
        "rateTypeId": "COMMERCIAL",
        "totalCarrierCharge": 16.32,
        "baseCharge": 12.57,
        "surcharges": [ {
            "name": "DELIVERY_AREA",
            "fee": 2.8
        },{
            "name": "FUEL",
            "fee": 1.11
        } ],
        "currencyCode": "USD"
    }, ...
    { ... } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.

For error codes specific to the CBDS, please see 130####.