Rate a Parcel¶
HTTP Request¶
POST /v1/rates
Summary¶
Use this operation to rate a parcel before you print and purchase a shipment label.
Note
This API does not validate addresses.
Things to Consider¶
You can rate parcels for PB Expedited (USPS®), PB Standard Delivery, CBDS, FedEx, and UPS.
To rate a parcel for a single service, include the
serviceId
in the request body. The response will return a single Rates Object.PB Standard Delivery only: The
serviceId
field is required.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.PB Standard Delivery only: You can rate a parcel for only one service at a time. The
serviceId
field is required.PB Expedited (USPS) only: To rate a parcel for multiple services and parcel types at once, omit both the
serviceId
andparcelType
fields in the request body. The response will contain a separate Rates Object for each combination of service and parcel type rated.In the
fromAddress
andtoAddress
objects, the following address fields are required. Depending on the carrier, additional fields might also be required:addressLines
postalCode
countryCode
The Rate a Parcel API does not validate addresses.
You must include the SHIPPER_ID option in the
shipmentOptions
array. This ensures the request returns the correct rates.You can pass only one Rates Object in the request body, as shown in the Sample Requests below. The response might contain multiple Rates Objects, which can occur if you have omitted the
serviceId
field from the request.For the available services and parcel types, see the carrier’s reference page.
PB Expedited (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.PB Standard Delivery only: In addition to the above, the following fields are required in the request body:
parcel.weight
parcel.dimension
rates.carrier
: Set this toNEWGISTICS
rates.serviceId
: Rating is available only for Parcel Select and Parcel Select Lightweight. Set this to eitherPRCLSEL
(Parcel Select) orPSLW
(Parcel Select Lightweight).rates.parcelType
: Set this toPKG
.shipmentOptions
: In addition to the SHIPPER_ID option, you must include the following options:- CLIENT_FACILITY_ID. When testing on Sandbox, use
this value:
0093
- CARRIER_FACILITY_ID. When testing on
Sandbox, use this value:
2594
- CLIENT_ID. When testing on Sandbox, use this value:
NGST
- If you set an irregular parcel girth value in the
parcel.dimension
object, then you must include the IS_RECTANGULAR option and set it tofalse
.
- CLIENT_FACILITY_ID. When testing on Sandbox, use
this value:
PB Standard Delivery only: In the response body, the
totalCarrierCharge
equals thebaseCharge
plus all surcharges.The
surcharges
array will show only theFUEL
surcharge. If other surcharges apply, they are not shown in thesurcharges
array. They are, however, included in thetotalCarrierCharge
.Note that the Rates API returns rates for PB Standard Delivery only. The API does not return rates for PB Standard Returns.
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 Valid values:
Note: This parameter is not available for PB Standard Delivery. |
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 | Shipper rate plan, if applicable. For more information, see this FAQ. |
X-PB-Integrator-CarrierId | 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 the 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 |
altReturnAddress | Address Object | USPS, CBDS Only. Applies as follows:
|
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 |
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:
|
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 |
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:
|
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 | FedEx, UPS Only. The final recipient of a the shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional. This address must match the If the final recipient’s address is the same as the importer’s address, the
entries in the |
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:
|
hazmatDetails | Hazmat Details Object | PB Standard Only. If shipping hazardous materials with PB Standard, use this object. Use this object only with PB Standard. |
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:
|
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:
|
parcelType | String | Conditional. The parcel type. For supported parcel types, see the carrier’s reference page. Required for:
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 This field applies to USPS, PB Presort, FedEx, and UPS. |
currencyCode | String | Type of currency referenced in the piece price. For example: This field applies to USPS, CBDS, FedEx, and UPS. |
dimensionalWeight | Object | RESPONSE ONLY. USPS Only. If the Note: A parcel might alternatively be subject to oversize
pricing, as explained in the |
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:
|
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
|
surcharges | Array[Object] | RESPONSE ONLY. Additional fees or surcharges for the shipment. Each object in the array defines a surcharge and fee. 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 If the shipper has an NSA, do not use this field. Use the response’s
|
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 If the shipper has an NSA, do not use this field. Use the response’s
|
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:
|
additionalDetails | String | These are carrier specific details that may be provided. |
destinationZone | String | RESPONSE ONLY. The destination zone used to determine the rate. The zone is based on the shipment’s origin address or consolidation center and the shipment’s destination address. Note: For CBDS shipments, |
rateTypeId | String | RESPONSE ONLY. The type of rate, such as COMMERCIAL_BASE (USPS) or
COMMERCIAL (FedEx, UPS). |
linePrice | BigDecimal | RESPONSE ONLY. The unit price multiplied by quantity. This field applies to CBDS. |
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:
PB Expedited (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"
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
} ]
}'
{
"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"
} ]
}
PB Standard Delivery Sample Request¶
curl -X POST .../v1/rates \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
"fromAddress": { ... },
"toAddress": { ... },
"parcel": {
"weight": {
"unitOfMeasurement": "OZ",
"weight": 90
},
"dimension": {
"unitOfMeasurement": "IN",
"length": 8,
"width": 4,
"height": 6
}
},
"rates": [ {
"carrier": "NEWGISTICS",
"serviceId": "PRCLSEL",
"parcelType": "PKG",
"specialServices": [ {
"specialServiceId": "DelCon"
} ]
} ],
"shipmentOptions": [ {
"name": "CLIENT_FACILITY_ID",
"value": "0093"
},{
"name": "CARRIER_FACILITY_ID",
"value": "2594"
},{
"name": "CLIENT_ID",
"value": "NGST"
},{
"name": "SHIPPER_ID",
"value": "9024324564"
} ]
}'
{
"fromAddress": { ... },
"toAddress": { ... },
"parcel": {
"weight": {
"unitOfMeasurement": "OZ",
"weight": 90.0
},
"dimension": {
"length": 8.0,
"width": 4.0,
"height": 6.0,
"unitOfMeasurement": "IN"
}
},
"rates": [ {
"carrier": "NEWGISTICS",
"parcelType": "PKG",
"specialServices": [ {
"specialServiceId": "DelCon"
} ],
"deliveryCommitment": {},
"serviceId": "PRCLSEL",
"baseCharge": 5.62,
"surcharges": [ {
"fee": 0.28,
"name": "FUEL"
} ],
"totalCarrierCharge": 5.9
} ],
"shipmentOptions": [ {
"name": "CLIENT_FACILITY_ID",
"value": "0093"
},{
"name": "CARRIER_FACILITY_ID",
"value": "2594"
},{
"name": "CLIENT_ID",
"value": "NGST"
},{
"name": "SHIPPER_ID",
"value": "9024324564"
} ]
}
CBDS 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": {
"unitOfMeasurement": "IN",
"length": "12",
"width": "5",
"height": "10"
},
"weight": {
"unitOfMeasurement": "OZ",
"weight": 80
}
},
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXPS",
"parcelType": "PKG"
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
} ],
"customs": {
"customsInfo": {
"currencyCode": "USD"
},
"customsItems": [ {
"description": "dress",
"itemId": "B004LB5FB9",
"quantity": 2,
"unitPrice": 25,
"url": "www.example.com/dress/a"
},{
"description": "dress",
"itemId": "B004LB5FB4",
"quantity": 2,
"unitPrice": 35,
"url": "www.example.com/dress/b"
} ]
}
}'
{
"fromAddress": { ... },
"toAddress": { ... },
"parcel": {
"dimension": {
"length": 12,
"height": 10,
"width": 5,
"unitOfMeasurement": "IN"
},
"weight": {
"weight": 80,
"unitOfMeasurement": "OZ"
},
"valueOfGoods": 120.00
},
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXPS",
"parcelType": "PKG",
"baseCharge": 52.25,
"totalCarrierCharge": 69.05,
"deliveryCommitment": {
"minEstimatedNumberOfDays": "6",
"maxEstimatedNumberOfDays": "9"
},
"currencyCode": "USD",
"totalTaxAmount": 16.80
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
} ],
"customs": {
"customsInfo": {
"currencyCode": "USD"
},
"customsItems": [ {
"itemId": "B004LB5FB9",
"description": "dress",
"quantity": 2,
"unitPrice": 25.00,
"url": "www.example.com/dress/a"
}, {
"itemId": "B004LB5FB4",
"description": "dress",
"quantity": 2,
"unitPrice": 35.00,
"url": "www.example.com/dress/b"
} ]
}
}
FedEx 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_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"
} ]
}'
{
"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.
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"
} ]
}'
{
"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####.