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¶

You can rate parcels for USPS, UPS, and PB Cross-Border.
To rate a parcel for a single service, include the serviceId in the request body. The response will return a single Rates Object.
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.

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.
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).
For available services and parcel types, see the carrier’s reference page.
USPS & UPS only: To ensure the selected parcel type is compatible with the selected service, see the “Parcel Types” table on the carrier’s reference page.
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.
Cross-Border only: The returned rate is the cost of shipping the parcel from the PB Cross-Border consolidation center to the parcel’s international destination.

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 in days.

Valid values:

true
false

carrier Cross-Border only. Required for PB Cross-Border. 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	UPS (United Parcel Service) Only. The unique identifier returned in the `shipperCarrierAccountId` field by the Register an Existing Carrier Account API.
X-PB-UnifiedErrorStructure	Recommended. Set this to `true` to use the standard error object if an error occurs.

Request / Response Elements¶

Important

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

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. If you are shipping with United Parcel Service (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. PB Cross-Border: For a Create Shipment request, this is the address used to return a parcel from the Pitney Bowes consolidation center. If omitted, the `fromAddress` is used.
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 shipment document. Applies as follows: Required for Create Shipment requests except as noted in the next bullet. Does not apply to a Cross-Border Create Shipment request. Does not apply to Rate Parcel requests.
shipmentOptions	Array[Object]	Conditional. Each object in this array defines a shipment option. Required for Create Shipment requests. Does not apply to Rate Parcel requests. All Create Shipment requests require the `SHIPPER_ID` option. Please see the Things to Consider section on the carrier’s Create Shipment page for any additional requirements.
name	String	The name of the shipment option. The `shipmentOptions` array requires this field.
value	String	The value of the shipment option. The `shipmentOptions` array requires this field.
customs	Object	Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for: USPS shipments to international destinations and to APO/FPO/DPO, Territories/Possessions, and FAS PB Cross-Border UPS 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	PB Cross-Border Only. Required in Create Shipment requests; does not apply to Rate Parcel requests. Contains information about the domestic leg of the PB Cross-Border shipment.
soldToAddress	Address Object	UPS Only. 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	USPS Return Labels Only. Required for USPS Return Labels. If you are creating a Pure Post Return label or Scan-Based Return label, include this field and set the value to `RETURN`.
references	Array[Object]	Applies only to the following: PB Cross-Border: Required in a Create Shipment request; does not apply to a Rate Parcel request. Contains the buyer order ID. The array takes an object with two String elements. Set `name` to `ORDER_NUMBER`, and set `value` to the order ID: { "name": "ORDER_NUMBER", "value": "<order_ID>" } Newgistics: Optional. This array maps client-generated identifiers to fields in the Newgistics package record. The information in this array does not appear on the shipping label. The array takes up to three objects, and each object maps an identifier to a specific Newgistics field. An object’s sequence in the array determines which Newgistics field the object maps to. The first object in the array maps to the Newgistics “ReferenceNumber” field; the second to the “AddlRef1” field; and the third to the “AddlRef2” field. Use the syntax shown below. Enter the names in the order shown. If you enter different names, the system will change them to the names below. In the `value` fields, enter the client-generated identifiers. The values must be strings of no more than 50 characters each. For additional information on using references, merchants can contact their Newgistics representatives. { "name": "ReferenceNumber", "value": "<client identifier 1>" }, { "name": "AddlRef1", "value": "<client identifier 2>" }, { "name": "AddlRef2", "value": "<client identifier 3>" }
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 a request and can return multiple Rates Objects in a response. Each Rates Object in a response shows a different rating option.

Name	Data Type	Description
carrier	String	Required. Carrier name. Valid values are: `USPS` - U.S. Postal Service `NEWGISTICS` - Newgistics. Create Shipment request only. `PBPRESORT` - PB Presort. Create Shipment request only. `PBI` - Cross-Border `UPS` - United Parcel Service
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. USPS: 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 UPS parcel Not applicable to Cross-Border Quotes.
specialServices	Array[Object]	The abbreviated names of the special services to be applied. For abbreviations, 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. Not applicable to Cross-Border Quotes.
specialServiceId	String	The abbreviated name of the special service to be applied. For abbreviations, see the Special Services table on the carrier’s reference page. Important Do not include a special service unless you intend to apply it.
inputParameters	Array[Object]	The parameters, if any, to set for the special service, such as minimum and maximum values. For the available parameters for a carrier’s special services, see the following: USPS: Issue the Carrier Rules API; locate the combination of service and parcel type; locate the special service; and then locate the `inputParameterRules` array. For details on how the the array maps to this field, see this FAQ. PMOD: If `specialServiceId` is set to `PMOD_OPTIONS`, the `inputParameters` array must contain each option listed in PMOD Options. Newgistics: See Newgistics Special Services. PB Presort: See PB Presort Special Services. UPS: See UPS Special Services.
name	String	The name of the input parameter. For USPS, this maps to the `inputParameterRules.name` field in the Carrier Rules API.
value	String	The value of the parameter. For USPS, the possible values are listed in the `inputParameterRules` array in the Carrier Rules API.
fee	Double	Response Only. The amount of fee expressed in the currency of the origin country.
inductionPostalCode	String	USPS and PB Presort Only. 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.
currencyCode	String	USPS, PB Cross-Border, and UPS Only. Type of currency referenced in the piece price. For example: `USD`, `CAD`, `EUR`
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. USPS, PB Cross-Border, and UPS Only. The base service charge payable to the carrier, excluding special service charges. If your request includes a shipper rate plan, please see this FAQ for information on whether the shipper rate affects this field.
totalCarrierCharge	Double	Response Only. USPS, PB Cross-Border, and UPS Only. The total amount payable to the carrier, including special service charges. If your request includes a shipper rate plan, please see this FAQ for information on whether the shipper rate affects this field.
surcharges	Array[Object]	Response Only. USPS and UPS 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 }
name	String	The type of surcharge. If this is set to `oversize`, then USPS oversize pricing was used to calculate the surcharge. Oversized pricing applies if the parcel’s combined length plus girth falls between 108 and 130 inches.
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. USPS and UPS Only. Time in transit for the shipment. For USPS, see also: Pitney Bowes Delivery Guarantee
minEstimatedNumberOfDays	String	The minimum number of delivery days.
maxEstimatedNumberOfDays	String	The maximum number of delivery days.
estimatedDeliveryDateTime	String	The estimated delivery date and time.
guarantee	String	States whether carrier delivery is guaranteed. Possible values: `FULL` `NONE`
additionalDetails	String	These are carrier specific details that may be provided.
destinationZone	Number	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` (UPS). This field is returned in the Retry Shipment and Reprint Shipment API calls.
totalTaxAmount	BigDecimal	Response Only. PB Cross-Border and UPS only. The total tax amount payable to the carrier. Applies only to the PB Cross-Border Carrier Service.
totalDutyAmount	BigDecimal	Response Only. PB Cross-Border only. The total duty amount payable to the carrier. Applies only to the PB Cross-Border Carrier Service.

Sample Requests and Responses¶

See the following examples:

USPS
Cross-Border
UPS

USPS Sample 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"
    } ]
}'

USPS Sample 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"
    } ]
}

Cross-Border Sample 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": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
      }, {
        "name": "CLIENT_FACILITY_ID",
        "value": "CVG"
      }
    ],
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}'

Cross-Border Sample 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": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
      }, {
        "name": "CLIENT_FACILITY_ID",
        "value": "CVG"
      }
    ],
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}

UPS Sample Request¶

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

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_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"
    } ]
}

UPS Sample Response¶

The following response is for a requested that omitted the serviceId field in order to rate the parcel for multiple services.

{
    "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"
    },{
        "carrier": "ups",
        "parcelType": "PKG",
        "specialServices": [],
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "3",
            "estimatedDeliveryDateTime": "2019-04-11 23:00:00",
            "guarantee": "FULL"
        },
        "serviceId": "3DA",
        "rateTypeId": "COMMERCIAL",
        "totalCarrierCharge": 36.35,
        "baseCharge": 31.21,
        "surcharges": [ {
            "name": "DELIVERY_AREA",
            "fee": 2.95
        },{
            "name": "FUEL",
            "fee": 2.56
        } ],
        "currencyCode": "USD"
    },{ ... } ]
}

Error Codes¶

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

For error codes specific to the Cross-Border carrier service (PBI), please see 13#####.