How to Create RateGroup

A Rate Group is a predefined collection of carriers and their services that you configure either via the User Interface or the Rate Group Management API. By creating a Rate Group, you select in advance which carriers and services should be included for dynamic rate shopping. A Rate Group allows the system to automatically select the best option, such as the cheapest rate or the fastest delivery based on your defined rule. This eliminates the need to manually compare rates across carriers every time you ship. For example, if you regularly ship with three carriers, you can create a Rate Group that includes all three. Then, when you create a shipment, the system can automatically pick the cheapest or fastest service among them. Once a Rate Group is created, it can be directly referenced in the Rate and Shipment APIs using the rateShopBy: rategroup option. This way, the API dynamically returns rate quote according to the carriers and services included in the group.

Without Rate Group: API requests must specify the specific carrier and service each time in the Rate or Shipment request. Alternatively, when rate shopping all carriers and services would be returned.
With Rate Group: Only pass the Rate Group ID → system auto-selects best service.

Copy

Copied

"rateShopBy": "rategroup",
"byRateGroup":{
  "ruleType": "Cheapest",
  "rateGroupId": "9bzUUq2w70h7"
}

Create Rate group through User Interface

Navigate to Carriers

Log in to the Pitney Bowes Developer Portal.
From the top navigation menu, click the Settings icon in the top right corner.
In the dropdown menu under the My Settings column, select Carriers.

Access Rate Groups Tab

On the Carriers page, click the Rate Groups tab at the top.
Click on + Add Rate Group. This opens the Add Rate Group dialog box.
Provide the display name for the rate group in the Display Nickname field.
Choose whether the rate group should be Active (available for use) or Inactive (not available for use).
Select the Custom Rate Group ID checkbox and enter a custom ID. If not selected, a system-generated ID will be assigned to the Rate Group.
Set Audience for the Rate Group
Define who can access and use this Rate Group. If you do not select the entity, Enterprise is taken as the default audience. You can choose from three audience types:
- Enterprise: Share with everyone in your organization. (Default option)
- Locations: Share with users at selected locations.
  - The first location is selected by default.
  - You can add other locations linked to the subscription by toggling the Other Locations button and selecting from the dropdown.
  - Ensure that all selected locations belong to the country you wish to create the Rate Group for.
- User Roles: Share with users who have specific roles. (Currently, Admin is the default role.)
Choose the Country of Origin for the Rate Group.
From the list of available carriers, select the carrier to associate with this Rate Group. Carriers and services selected here will define which options are available later when using this Rate Group in the API
After selecting a carrier, choose the specific services you want to include in the Rate Group.
Add Services to the Rate Group
- To add a single service, select it and click the single arrow.
- To add all the services of the carrier, click the double arrow.
Add Multiple Carriers (Optional)
If you want to include additional carriers in the same Rate Group, return to the Carrier Account section and repeat the process of selecting the carrier and its associated services.
Once all details are filled in, click Done.
The new Rate Group is now created and available under Carriers > Rate Group Inventory.
You can edit the Rate Group later, if required. For example, you may update the name, audience, status, carriers, or services.

Create Rate Group through Rate Group Management API

To create a Rate Group, use the Create Rate Group API. This API allows you to define a group of carriers and their services so that shipments can be automatically rate-shopped for the fastest or cheapest delivery option; without manual comparison.

Create Rate Group Request Example

Copy

Copied

{
    "name": "RATE GROUP USERS1 ",
    "countryCode": "US",
    "status": "active",
    "permissionEntityBy": "R",
    "permissions": [
        {
            "permissionEntityId": "ADMIN"
        },
        {
            "permissionEntityId": "User"
        }
    ],
  "items": [
   {
    "carrierCode": "USPS",
    "serviceId": "PM"
   },
   {
    "carrierCode": "FedEx",
    "serviceId": "FEDEX_GROUND"
   },
   {
    "carrierCode": "UPS",
    "serviceId": "2ND_DAY_AIR"
   }
 ]
}

Requirements for Creating a Rate Group

When creating a Rate Group, the following information is required:

Rate Group Name: The display name of the Rate Group. This name will be shown wherever the group is referenced.
Origin Country Code: The country code representing the shipment origin for which this Rate Group is created.
Status: Defines whether the Rate Group is Active (available for use) or Inactive (not available for use).
permissionEntityBy (Audience): Specifies who can access and use the Rate Group. Audience types include:
- Enterprise: Available to all users in the organization.
- Locations: Restricted to selected shipping locations.
- User Roles: Restricted to selected user roles (e.g., Admin).
permissionEntityId (Audience Identifier): Identifies the selected audience type;
- E: Enterprise (only one allowed).
- L: Locations (multiple locations can be selected, but all must match the Origin Country Code).
- R: User Roles (multiple roles can be selected).
Items: The items array defines the carriers and their associated services that will be included in the Rate Group. These are the carriers and services against which the system will perform rate shopping.
- carrierCode: Unique identifier of the carrier (e.g., USPS, FedEx, UPS).
- serviceId: Identifier of the specific service offered by the carrier (e.g., PM for Priority Mail, EM for Express Mail).

The Rate Group ID is generated based on the defined carriers and services.

Sample Response:

Copy

Copied

{
    "rateGroupID": "51kpg2RP3ORxnZW"
}

How to use Rate Group ID in Rate Shipment Calls

Once you've created a Rate Group, you can use its Rate Group ID to fetch rate quotes automatically without manually comparing carriers or services.

How it Works

In a Rate Shipment call, set rateShopBy to rateGroup.
Provide the Rate Group ID received in Create Rate Group API under the byRateGroup object, along with the ruleType (Cheapest or Fastest).
The system then compares all carriers and services defined in that Rate Group and returns the best matching rate quote.

Sample request of Rate Shipment Call using the rate group ID

Copy

Copied

{
    "fromAddress":{
        "addressLine1": "24182 Kathy Ave",
        "cityTown": "Lake Forest",
        "countryCode": "US",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "92630-1827",
        "stateProvince": "CA"
    },
    "toAddress": {
        "addressLine1": "55 Pharr Rd NW, Apt E104",
        "cityTown": "Atlanta",
        "countryCode": "US",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "30305-2151",
        "stateProvince": "GA"
    },
    "parcel": {
        "length": 2,
        "width": 1,
        "height": 1,
        "dimUnit": "IN",
        "weightUnit": "OZ",
        "weight": 2,
        "packageValue": 2
    },
    "parcelType": "PKG",
    "rateShopBy": "rateGroup",
    "byRateGroup": {
        "ruleType": "Cheapest",
        "rateGroupId": "51kpg2RP3ORxnZW"  
    },
    "labelSize": "DOC_4X6",
    "labelType": "SHIPPING_LABEL",
    "labelFormat": "ZPL2",
    "deliveryOption": {
        "deliverBy": "2025-08-22",
        "useBestNextDate": false
        }

}

Sample Response of the API

Copy

Copied

{
    "fromAddress": {
        "addressLine1": "24182 Kathy Ave",
        "cityTown": "Lake Forest",
        "countryCode": "US",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "92630-1827",
        "residential": false,
        "stateProvince": "CA"
    },
    "toAddress": {
        "addressLine1": "55 Pharr Rd NW, Apt E104",
        "cityTown": "Atlanta",
        "countryCode": "US",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "30305-2151",
        "residential": false,
        "stateProvince": "GA"
    },
    "rate": [
        {
            "baseCharge": 16.75,
            "carrier": "FEDEX",
            "currencyCode": "USD",
            "deliveryCommitment": {
                "additionalDetails": "BY 17:00 WED",
                "estimatedDeliveryDateTime": "2025-08-20 17:00:00",
                "guarantee": "FULL"
            },
            "inductionPostalCode": "92630-1827",
            "parcelType": "SMALL_EXP_BOX",
            "rateTypeId": "ONE_RATE",
            "serviceId": "2DA",
            "totalCarrierCharge": 16.75,
            "destinationZone": "08",
            "isHazmat": false,
            "publishedTotalCarrierCharge": 16.75
        }
    ],
    "shipmentOptions": {},
    "parcel": {
        "length": 2,
        "height": 1,
        "width": 1,
        "dimUnit": "IN",
        "weightUnit": "OZ",
        "weight": 2,
        "packageValue": 2
    }
}

In this example, the Rate Group included multiple carriers and services. The system compared them based on the Cheapest rule and determined that FedEx 2-Day Air (2DA) provided the lowest charge at $16.75.