{
"openapi": "3.0.1",
"info": {
"title": "RateGroup APIs",
"description": "A RateGroup is used to automate carrier and service selection during shipment processing. Instead of explicitly passing a carrier and service in every request, you can pass a rateGroupId, and get the desired rate (for example, lowest cost or fastest delivery).
\nRateGroups helps with:\n- Atomatic rate shopping across multiple carriers\n- Shipping decision depends on price, speed, or available services at runtime\n\n**How it works**
\n- Create a RateGroup with a list of\n - carrierCode (e.g., USPS, UPS, FedEx)\n - serviceId (e.g., PM, FEDEX_GROUND, NDA)
\n\n- Use the returned rateGroupId in\n - Rate API: to fetch the best available rate\n - Create Shipment API: to generate a shipment using the selected service\n\n- When a rateGroupId is provided in a request, carrier and service selection is handled internally based on the configured items.\n- Evaluation of carrier-service combinations is dynamic and may vary per request depending on shipment attributes such as origin, destination, and parcel details.\n- Only RateGroups with status active are considered for processing.\n- RateGroups are country-specific, and only applicable shipments are evaluated.\n\n> Read [How to Create RateGroup](/docs/rategroup-management/rategroup-guide).\n",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api-sandbox.sendpro360.pitneybowes.com/shipping",
"description": "Sandbox Server"
},
{
"url": "https://api.sendpro360.pitneybowes.com/shipping",
"description": "Production Server (uses live data)"
},
{
"url": "https://api-ppd.shipping360.pitneybowes.com/ca/shipping",
"description": "Sandbox Server for Canada"
},
{
"url": "https://api.shipping360.pitneybowes.com/ca/shipping",
"description": "Production Server for Canada"
}
],
"tags": [
{
"name": "RateGroup",
"description": "APIs for creating, retrieving, updating, and deleting RateGroups. These APIs help manage carrier-service groupings and enable automated rate selection during shipment and rate request workflows."
}
],
"paths": {
"/api/v1/rategroups": {
"post": {
"tags": [
"RateGroup"
],
"summary": "Create RateGroup",
"description": "Use this API to create a RateGroup that groups carriers and their services for automated rate shopping. A RateGroup allows the system to dynamically select the cheapest or fastest delivery option across the defined carriers and services—without manual comparison.Read [How to Create RateGroup](/docs/rategroup-management/rategroup-guide).",
"operationId": "createRateGroup",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Rategrouprequest"
},
"example": {
"name": "RATEGROUP USERS2",
"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"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successfully created a RateGroup.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"rateGroupId": {
"type": "string",
"description": "Unique identifier of the rategroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"example": "wZJvKEBg0gPVbZ5"
}
}
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
},
"get": {
"tags": [
"RateGroup"
],
"summary": "Get All RateGroups",
"description": " This operation retrieves a list of all RateGroups with metadata such as the RateGroup ID, display name, origin country, status (active/inactive), audience type, included carriers and services, archival status available in the system.",
"operationId": "getAllRateGroups",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Retrived a list of all rete groups available.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AllRateGroups"
},
"example": [
{
"rateGroupId": "Eew5PY45A9KWakb",
"uid": "A8wZK4J2YdzqZym",
"name": "FEDEX-NDA",
"countryCode": "US",
"permissionEntityBy": "E",
"status": "active",
"items": [
{
"carrierCode": "FEDEX",
"serviceId": "NDA"
}
],
"archived": false,
"updateTimestamp": "2025-08-18T11:48:46.128Z"
},
{
"rateGroupId": "Q6Wp3onr3JNlDXx",
"uid": "Ae6vn3VD5voQ46R",
"name": "FEDEX-UPS-NDA",
"countryCode": "US",
"permissionEntityBy": "E",
"status": "active",
"items": [
{
"carrierCode": "FEDEX",
"serviceId": "NDA"
},
{
"carrierCode": "FEDEX",
"serviceId": "2DA"
},
{
"carrierCode": "UPS",
"serviceId": "NDA"
}
],
"archived": false,
"updateTimestamp": "2025-08-14T10:03:47.063Z"
}
]
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
}
},
"/api/v1/rategroups/{rateGroupId}": {
"get": {
"tags": [
"RateGroup"
],
"summary": "Get RateGroup by ID",
"description": "This operation retrieves a RateGroups using the provided RateGroup ID with metadata such as the RateGroup ID, display name, origin country, status (active/inactive), audience type, included carriers and services, archival status available in the system.",
"operationId": "getRateGroup",
"parameters": [
{
"name": "rateGroupId",
"description": "Unique identifier of the rategroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"required": true,
"in": "path",
"schema": {
"type": "string",
"example": "Q6Wp3onr3JNlDXx"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Retrieved the specified rategroup.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleRateGroups"
},
"example": {
"rateGroupId": "Q6Wp3onr3JNlDXx",
"uid": "Ae6vn3VD5voQ46R",
"name": "FEDEX-UPS-NDA",
"countryCode": "US",
"permissionEntityBy": "E",
"status": "active",
"items": [
{
"carrierCode": "FEDEX",
"serviceId": "NDA"
},
{
"carrierCode": "FEDEX",
"serviceId": "2DA"
},
{
"carrierCode": "UPS",
"serviceId": "NDA"
}
],
"archived": false,
"updateTimestamp": "2025-08-14T10:03:47.063Z",
"permissions": [
{
"permissionEntityId": "1eBNadyLLYp"
}
]
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
},
"put": {
"tags": [
"RateGroup"
],
"summary": "Update RateGroup",
"description": "This operation updates the details of an existing RateGroup identified by its RateGroup ID. You can modify attributes such as the display name, status (active/inactive), audience type (Enterprise, Location, or Users and Roles), and the list of carriers and services associated with the RateGroup. Once updated, the revised RateGroup will be available for use in dynamic rate shopping through the Rate and Create Shipment APIs.",
"operationId": "updateRateGroup",
"parameters": [
{
"name": "rateGroupId",
"description": "Unique identifier of the RateGroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"required": true,
"in": "path",
"schema": {
"type": "string",
"example": "Q6Wp3onr3JNlDXx"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Rategrouprequest"
},
"example": {
"name": "RATEGROUP USERS2",
"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"
}
]
}
}
}
},
"responses": {
"200": {
"description": "RateGroup metadata has been updated successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"rateGroupId": {
"type": "string",
"description": "Unique identifier of the RateGroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"example": "wZJvKEBg0gPVbZ5"
}
}
}
}
}
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
},
"delete": {
"tags": [
"RateGroup"
],
"summary": "Delete RateGroup",
"description": "This operations deletes the specified RateGroup.",
"operationId": "deleteRateGroup",
"parameters": [
{
"name": "rateGroupId",
"description": "Unique identifier of the RateGroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"required": true,
"in": "path",
"schema": {
"type": "string",
"example": "Q6Wp3onr3JNlDXx"
}
}
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "The RateGroup has been archived successfully."
},
"400": {
"description": "Invalid or Bad Request",
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"description": "Unauthorized Error",
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"description": "Internal Server Error",
"$ref": "#/components/responses/InternalServerError"
}
}
}
}
},
"components": {
"schemas": {
"Rategrouprequest": {
"type": "object",
"required": [
"name",
"countryCode",
"items"
],
"properties": {
"name": {
"type": "string",
"description": "Display name of the RateGroup. This will be used as the rategroup's nickname or label.",
"example": "RATEGROUP-2"
},
"countryCode": {
"type": "string",
"description": "Two-letter ISO country code representing the shipment origin for which the RateGroup is created.",
"example": "US"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive"
],
"description": "Defines whether the RateGroup is available for use (`active`) or not (`inactive`).",
"example": "active"
},
"permissionEntityBy": {
"type": "string",
"enum": [
"E",
"L",
"R",
"U"
],
"description": "Defines the audience who can access and use this RateGroup.\n- `E`: Enterprise (all users in the organization). If `permissionEntityBy` is not explicitly provided, Enterprise is set as the default entity.\n- `L`: Locations (restricted to specific locations)\n- `R`: User Roles (restricted to specific roles, e.g., Admin or USER)\n- `U`: Users \n> \n - RateGroups created at the enterprise level are supported in downstream API operations such as Create Shipment and Rate Shipment.\n - API requests fail if they use RateGroups created at user, division, or location levels.\n",
"example": "R"
},
"permissions": {
"type": "array",
"description": "List of audience identifiers who can access the RateGroup as set in `permissionEntityBy`.",
"items": {
"type": "object",
"properties": {
"permissionEntityId": {
"type": "string",
"description": "Identifier of the audience (e.g., `ADMIN`, `User`, location ID).",
"example": "ADMIN"
}
}
}
},
"items": {
"type": "array",
"description": "Array of carriers and their services to be included in the RateGroup for rate shopping.",
"items": {
"type": "object",
"required": [
"carrierCode",
"serviceId"
],
"properties": {
"carrierCode": {
"type": "string",
"description": "U\"nique identifier of the carrier (e.g., USPS, FedEx, UPS).\"",
"example": "USPS"
},
"serviceId": {
"type": "string",
"description": "Identifier of the service offered by the carrier (e.g., PM for Priority Mail, FEDEX_GROUND).",
"example": "PM"
}
}
}
}
}
},
"AllRateGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rateGroupId": {
"type": "string",
"description": "Unique identifier of the rategroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"example": "Eew5PY45A9KWakb"
},
"uid": {
"type": "string",
"description": "Unique user identifier who created the RateGroup.",
"example": "A8wZK4J2YdzqZym"
},
"name": {
"type": "string",
"description": "Display name of the RateGroup.",
"example": "FEDEX-NDA"
},
"countryCode": {
"type": "string",
"description": "ISO country code of the origin country for the RateGroup.",
"example": "US"
},
"permissionEntityBy": {
"type": "string",
"description": "Audience type who can access this RateGroup.",
"enum": [
"E",
"L",
"R"
],
"example": "E"
},
"status": {
"type": "string",
"description": "Status of the RateGroup.",
"enum": [
"active",
"inactive"
],
"example": "active"
},
"items": {
"type": "array",
"description": "List of carriers and their services included in the RateGroup.",
"items": {
"type": "object",
"properties": {
"carrierCode": {
"type": "string",
"description": "Unique identifier of the carrier.",
"example": "FEDEX"
},
"serviceId": {
"type": "string",
"description": "Identifier of the carrier's service.",
"example": "NDA"
}
}
}
},
"archived": {
"type": "boolean",
"description": "Indicates whether the RateGroup is archived",
"example": false
},
"updateTimestamp": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp of the RateGroup",
"example": "2025-08-18T11:48:46.128Z"
}
}
}
},
"SingleRateGroups": {
"type": "object",
"properties": {
"rateGroupId": {
"type": "string",
"description": "Unique identifier of the rategroup created. This Id is used in rate shipment and create shipment requests for automatic rate shopping.",
"example": "Eew5PY45A9KWakb"
},
"uid": {
"type": "string",
"description": "Unique user identifier who created the RateGroup.",
"example": "A8wZK4J2YdzqZym"
},
"name": {
"type": "string",
"description": "Display name of the RateGroup.",
"example": "FEDEX-NDA"
},
"countryCode": {
"type": "string",
"description": "ISO country code of the origin country for the RateGroup.",
"example": "US"
},
"permissionEntityBy": {
"type": "string",
"description": "Audience type who can access this RateGroup.",
"enum": [
"E",
"L",
"R"
],
"example": "E"
},
"status": {
"type": "string",
"description": "Status of the RateGroup.",
"enum": [
"active",
"inactive"
],
"example": "active"
},
"items": {
"type": "array",
"description": "List of carriers and their services included in the RateGroup.",
"items": {
"type": "object",
"properties": {
"carrierCode": {
"type": "string",
"description": "Unique identifier of the carrier.",
"example": "FEDEX"
},
"serviceId": {
"type": "string",
"description": "Identifier of the carrier's service.",
"example": "NDA"
}
}
}
},
"archived": {
"type": "boolean",
"description": "Indicates whether the RateGroup is archived",
"example": false
},
"updateTimestamp": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp of the RateGroup",
"example": "2025-08-18T11:48:46.128Z"
}
}
},
"error": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource."
}
},
"required": [
"message"
]
},
"Errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g. validation-error.",
"example": "validation_error"
},
"errorDescription": {
"type": "string",
"description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).",
"example": "Rategrop cannot created."
},
"additionalCode": {
"type": "string",
"description": "A unique identifier for the error, for example 01000806."
},
"additionalInfo": {
"type": "string",
"description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
},
"additionalParameters": {
"type": "array",
"items": {
"type": "string",
"description": "The field(s) that might be incorrect in the request."
}
}
}
}
},
"NotFoundErrors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"example": "not_found",
"description": "Error code(s) that appear due HTTP 404 Page or File not found."
},
"errorDescription": {
"type": "string",
"example": "resource not found",
"description": "The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource."
},
"additionalCode": {
"type": "string",
"description": "A unique identifier for the error, for example 0100025, 1110017, or 1090001."
},
"additionalInfo": {
"type": "string",
"description": "Additional information about the error. This error 'Not Found' might appear due to `RateGroup Not Found`, `No Shipments to close`, or `Original Transaction not found`."
},
"additionalParameters": {
"type": "array",
"items": {
"type": "string",
"description": "The field(s) that might be incorrect in the request."
}
}
}
}
}
},
"responses": {
"UnauthorizedError": {
"description": "The request could not be authorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"InternalServerError": {
"description": "The request could not be completed due to an internal error.",
"content": {}
},
"BadRequestError": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
}
}
}
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic"
},
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}