Get Carrier Rules

HTTP Request

GET /v1/information/rules/rating-services?carrier={carrier}&originCountryCode={XX}&destinationCountryCode={YY}

Summary

This operation retrieves the rules governing the carrier’s services, including the available parcel types and the limits on weights and dimensions.

Things to Consider

  1. Because of the size of the returned data, this operation is an expensive operation. It is recommended that you cache the returned data and make the API call only once a day.

  2. At the top level, the returned rules are organized by service type.

  3. Within a service type, each set of rules applies to a combination of parcel type and rate type.

  4. For a given combination of parcel type and rate type, the rules tell you:

    • Weight constraints.

    • Dimension constraints.

    • The list of compatible special services. For each special service listed, the rules tell you any prerequisite, incompatibilities, and input parameters.

    • The suggested trackable special service.

      Note: The PB Shipping APIs require that all parcels be trackable.

  5. The Sample Response displays the rules structure. You can also view the rules structure by copying your response into a JSON tree viewer, such as https://codebeautify.org/jsonviewer.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/information/rules/rating-services?carrier={carrier}&originCountryCode={XX}&destinationCountryCode={YY}
Production: https://api.pitneybowes.com/shippingservices/v1/information/rules/rating-services?carrier={carrier}&originCountryCode={XX}&destinationCountryCode={YY}

Query Parameters

Name Data Type Description
carrier String Required. The carrier name. Currently this must be set to: USPS
originCountryCode String Required. The two-character ISO country code for the country where the shipment originates.
destinationCountryCode String Required. The two-character ISO country code for the country of the shipment’s destination address.
rateTypeId String The type of rate requested, such as COMMERCIAL_BASE. If a rate type is not specified, all eligible rate types are returned.
futureShipmentDate String

If the shipment is for a future date, and if a rate change is expected before the shipment date, use this field to ensure you get the correct rates and correct rate rules. Note that a rate change can affect the structure of the rate rules as well as the actual rates.

Specify this value in GMT/UTC, using one of the following formats:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:mm:ss
  • YYYY-MM-DD HH:mm:ss.SSS
returnShipment Boolean If true, provides only services applicable for return shipment.
compactResponse Boolean If true, returns only summary, without special service details.

Request Header

Name Data Type Description
Authorization String Required. OAUTH Token generated using the Generate an OAuth Token API.

Response Elements

Name Data Type Description
serviceId String The abbreviated name of the carrier-specific service. For abbreviations, see Services.
brandedName String The full name of the service.
parcelTypeRules Array[Object] The available service options.
    parcelType String The abbreviated name of the parcel type. For abbreviations, see Parcel Types.
    brandedName String The full name of the parcel type.
    rateTypeId String The type of rate requested. If a type was not specified in the request, the API returns all the eligible rate types.
    rateTypeBrandedName String The full name of the rate type.
    trackable String

Whether this parcel type is trackable. Valid Values are:

  • TRACKABLE
  • NON_TRACKABLE
  • REQUIRES_TRACKABLE_SPECIAL_SERVICE
    specialServiceRules Array[Object] The special services applicable for this combination of service type, rate type, and parcel type. For special service abbreviations, see Special Services.
            specialServiceId String The abbreviated name of the special service. For abbreviations, see Special Services.
            brandedName String The full name of the special service.
            categoryId String The ID of the special service rate category.
            categoryName String The full name of the special service rate category.
            trackable Boolean If true, then applying the special service to the shipment allows the shipper to track the shipment.
            inputParameterRules Array[Object] If the carrier requires input for the special service, these are the parameters governing input. These rules define the allowed inputs.
                    name String The type of constraint. This is usually set to INPUT_VALUE.
                    brandedName String The full name of the special service.
                    required Boolean If true, this constraint must be followed.
                    minValue Number The minimum input value for this parcel type rule.
                    maxValue Number The maximum input value for this parcel type rule.
                    freeValue Number An amount that is automatically provided for this parcel type rule. The shipper does not need to include anything equal to or below this amount in the request, as it is already provided.
                    format String  
                    description String  
            prerequisiteRules Array[Object] If this array is present, the special service requires one of the listed prerequisite special services. Any one of the listed special services will meet the prerequisite requirement.
                    specialServiceId String The abbreviated name of the special service. For abbreviations, see Special Services.
                    minInputValue Number The minimum value required for the required special service.
            incompatibleSpecialServices Array[String] Special services that the shipper cannot use with this special service.
    weightRules Array[Object] Weight rules for this combination of service type, rate type, and parcel type.
            required Boolean If true, weight must be provided, constrained by the limits, in requests for rating and shipment.
            unitOfMeasurement String How weight is quantified.
            minWeight Number The minimum weight.
            maxWeight Number The maximum weight.
    dimensionRules Array[Object] Dimension rules for this combination of service type, rate type, and parcel type.
            required Boolean If true, dimensions must be provided, constrained by the limits, in requests for rating and shipment.
            unitOfMeasurement String How dimension is quantified.
            minParcelDimensions Object

An object with the minimum dimensions for the parcel. For example:

{
    "length": 0.001,
    "width": 0.001,
    "height": 0.001,
    "unitOfMeasurement": "IN"
}
            maxParcelDimensions Object

An object with the maximum dimensions for the parcel. For example:

{
    "length": 22,
    "width": 15,
    "height": 18,
    "unitOfMeasurement": "IN"
}
            minLengthPlusGirth Number Minimum size allowed for length (the longest dimension) + girth.
            maxLengthPlusGirth Number Maximum size allowed for length (the longest dimension) + girth.
    suggestedTrackableSpecialServiceId
String If parcelTypeRules.trackable is set to REQUIRES_TRACKABLE_SPECIAL_SERVICE, this is a free or low-cost special service that allows the shipper to track the shipment.

Sample Request

curl -X GET .../v1/information/rules/rating-services?carrier=USPS&originCountryCode=US&destinationCountryCode=US \
-H "Authorization: Bearer <oauth_token>"

Sample Response

[
    {
        "serviceId": "EM",
        "brandedName": "Priority Mail Express™",
        "parcelTypeRules": [ {
            "parcelType": "LGENV",
            "brandedName": "Large Envelope",
            "rateTypeId": "<rate_type>",
            "rateTypeBrandedName": "<rate_type_branded_name>",
            "trackable": "TRACKABLE",
            "specialServiceRules": [ ... , {
                "specialServiceId": "COD",
                "brandedName": "Collect on Delivery",
                "categoryId": "COD",
                "categoryName": "Collect on Delivery",
                "trackable": false,
                "inputParameterRules": [ {
                    "name": "INPUT_VALUE",
                    "brandedName": "COD Amount",
                    "required": true,
                    "minValue": 1,
                    "maxValue": 1000
                } ],
                "prerequisiteRules": [ {
                    "specialServiceId": "Sig",
                    "minInputValue": 0
                } ],
                "incompatibleSpecialServices": [
                    "Ins",
                    "InsRD",
                    "CODRD",
                    "ADSIG",
                    "ADSIGRD"
                ]
            }, ... ],
            "weightRules": [ {
                "required": true,
                "unitOfMeasurement": "OZ",
                "minWeight": 0.01,
                "maxWeight": 1120
            } ],
            "dimensionRules": [ {
                "required": false,
                "unitOfMeasurement": "IN",
                "minParcelDimensions": {
                    "length": 0.001,
                    "width": 0.001,
                    "height": 0.001,
                    "unitOfMeasurement": "IN"
                },
                "maxParcelDimensions": {
                    "length": 15,
                    "width": 0.75,
                    "height": 12,
                    "unitOfMeasurement": "IN"
                },
                "minLengthPlusGirth": 0,
                "maxLengthPlusGirth": 108
            } ],
            "suggestedTrackableSpecialServiceId": "Sig"
        } ... ]
    }, ...
]

Error Codes

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