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.

Note

This API currently returns rules only for PB Expedited (USPS).

Considerations¶

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.
The returned rules are organized by service type (serviceId).
Within a service type, each set of rules applies to a given combination of parcel type (parcelType) and rate type (rateTypeId).
For a given combination of parcel type and rate type, the rules tell you:
- Special services that can be used.
  
  For each special service, the rules tell you the input parameters, the prerequisite special services, and the incompatible special services.
- Weight constraints.
- Dimension constraints.
- Suggested trackable special service.
  
  Note: The APIs require that all parcels be trackable.
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 URLs¶

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

Query Parameters¶

Name	Description
carrier	Required. The carrier name. Currently this must be set to: `USPS`
originCountryCode	Required. The two-character ISO country code for the country where the shipment originates.
destinationCountryCode	Required. The two-character ISO country code for the country of the shipment’s destination address.
rateTypeId	The type of rate requested, such as `COMMERCIAL_BASE`. If a rate type is not specified, all eligible rate types are returned.
futureShipmentDate	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 UTC/GMT, not in local time. Use one of the following formats: `YYYY-MM-DD` `YYYY-MM-DD HH:mm:ss` `YYYY-MM-DD HH:mm:ss.SSS`
returnShipment	If set to `true`, provides only services applicable for return shipment. Valid values: `true` `false`
compactResponse	If set to `true`, returns only summary, without special service details. Valid values: `true` `false`

Request Header¶

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

X-PB-UnifiedErrorStructure

Recommended. Set this to true to use the standard error object if an error occurs.

Response Elements¶

Name	Data Type	Description
serviceId	String	The abbreviated name of the service. See your carrier’s reference page in the Carriers section of the documentation.
brandedName	String	The full name of the service.
parcelTypeRules	Array[Parcel Type Rules Object]	The available service options.

Parcel Type Rules Object¶

The parcelTypeRules array returns the following object:

Name	Data Type	Description
parcelType	String	The abbreviated name of the parcel type. See your carrier’s reference page in the Carriers section of the documentation.
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[specialServiceRules Object]	The special services applicable for this combination of service type, rate type, and parcel type. See your carrier’s reference page in the Carriers section of the documentation.
weightRules	Array[weightRules Object]	Weight rules for this combination of service type, rate type, and parcel type.
dimensionRules	Array[dimensionRules Object]	Dimension rules for this combination of service type, rate type, and parcel type.
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.

Special Service Rules Object¶

The parcelTypeRules.specialServiceRules array returns the following object:

Name	Data Type	Description
specialServiceId	String	The abbreviated name of the special service. See your carrier’s reference page in the Carriers section of the documentation.
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.
inputParameterRules.name	String	The type of constraint. This is usually set to `INPUT_VALUE`.
inputParameterRules.brandedName	String	The full name of the special service.
inputParameterRules.required	Boolean	If `true`, this constraint must be followed.
inputParameterRules.minValue	Number	The minimum input value for this parcel type rule.
inputParameterRules.maxValue	Number	The maximum input value for this parcel type rule.
inputParameterRules.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.
inputParameterRules.format	String
inputParameterRules.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.
prerequisiteRules.specialServiceId	String	The abbreviated name of the special service. See your carrier’s reference page in the Carriers section of the documentation.
prerequisiteRules.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.

Weight Rules Object¶

The parcelTypeRules.weightRules array returns the following object:

Name	Data Type	Description
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.

Dimension Rules Object¶

The parcelTypeRules.dimensionRules array returns the following object:

Name	Data Type	Description
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	Dimension Object	The minimum dimensions for the parcel type. For example: { "length": 0.001, "width": 0.001, "height": 0.001, "unitOfMeasurement": "IN" }
maxParcelDimensions	Dimension Object	The maximum dimensions for the parcel type. For example: { "length": 22, "width": 18, "height": 15, "unitOfMeasurement": "IN" }
minLengthPlusGirth	Number	Minimum size allowed for length (the longest dimension) + girth.
maxLengthPlusGirth	Number	Maximum size allowed for length (the longest dimension) + girth.

Sample Request¶

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

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 error codes returned by the Ecommerce APIs, please see Error Codes.