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

  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. The returned rules are organized by service type (serviceId).

  3. Within a service type, each set of rules applies to a given combination of parcel type (parcelType) and rate type (rateTypeId).

  4. 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.

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