Total Rate Details

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-total-rates-query-result-schema.json",
  "title": "Total Rate Details",
  "description": "A list of rate options including applicable extra services.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-international-prices-openapi.yml#/components/schemas/TotalRatesQueryResult",
  "type": "object",
  "properties": {
    "rateOptions": {
      "type": "array",
      "description": "List of rate options including total base price and rates",
      "items": {
        "allOf": [
          {
            "$ref": "#/$defs/RateOption"
          },
          {
            "type": "object",
            "properties": {
              "dutiesTaxesFeesQuote": {
                "type": "object",
                "description": "The duties, taxes, and fees details. Included if `requestDutiesTaxesFees` is `true` and the shipping destination has applicable duties, taxes, and fees.",
                "properties": {
                  "packageFee": {
                    "type": "number",
                    "format": "float",
                    "description": "The value of the total landed cost fee associated with the package."
                  },
                  "itemQuotes": {
                    "type": "array",
                    "description": "The total landed cost prices for taxes and duties on each item.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dutyPrice": {
                          "type": "number",
                          "format": "float",
                          "description": "The value of the duties associated with the item."
                        },
                        "taxPrice": {
                          "type": "number",
                          "format": "float",
                          "description": "The value of the taxes associated with the item."
                        },
                        "itemId": {
                          "type": "string",
                          "description": "The corresponding `itemId` provided in the request."
                        }
                      }
                    }
                  }
                }
              },
              "extraServices": {
                "type": "array",
                "description": "A list of Extra Services to be included in the total rates search. If no extra services are specified all applicable extra services for the mail class will be returned.",
                "items": {
                  "type": "object",
                  "properties": {
                    "SKU": {
                      "$ref": "#/$defs/SKU"
                    },
                    "price": {
                      "$ref": "#/$defs/Price"
                    },
                    "priceType": {
                      "$ref": "#/$defs/InternationalPriceType"
                    },
                    "extraService": {
                      "type": "string",
                      "description": "Extra Service Code"
                    },
                    "name": {
                      "$ref": "#/$defs/ExtraServiceName"
                    },
                    "warnings": {
                      "$ref": "#/$defs/WarningsList"
                    }
                  }
                }
              },
              "totalPrice": {
                "type": "number",
                "description": "The total price, including the `totalBasePrice` and all extra service prices.\n\nNote: This field is only returned when `extraServices` are passed in the request.\n"
              }
            }
          }
        ]
      }
    }
  },
  "$defs": {
    "ExtraServiceName": {
      "type": "string",
      "description": "Description of the Extra Service"
    },
    "InternationalPriceType": {
      "type": "string",
      "description": "The type of price applied.\n\nNotes:\n * If an `accountNumber` is provided, it overrides the requested `priceType` and the response will return `CONTRACT` rates (if they exist for that account).\n * When priceType is `CONTRACT`, `accountType` and `accountNumber` are required to return the correct pricing.  If `accountType` and `accountNumber` are not provided, published `COMMERCIAL` rates may be returned instead.\n",
      "enum": [
        "RETAIL",
        "COMMERCIAL",
        "COMMERCIAL_BASE",
        "COMMERCIAL_PLUS",
        "CONTRACT"
      ]
    },
    "Price": {
      "type": "number",
      "description": "The postage rate.",
      "format": "double"
    },
    "RateDetails": {
      "title": "Rate Details",
      "type": "object",
      "properties": {
        "SKU": {
          "type": "string",
          "description": "The stock keeping unit for the designated rate."
        },
        "description": {
          "type": "string",
          "description": "The description of the price."
        },
        "priceType": {
          "type": "string",
          "description": "The type of price applied.\n * Valid Options for Domestic Prices include: 'RETAIL','COMMERCIAL' & 'CONTRACT'\n * Valid Options for International Prices include: 'RETAIL', 'COMMERCIAL', 'COMMERCIAL_BASE', 'COMMERCIAL_PLUS' & 'CONTRACT'",
          "enum": [
            "RETAIL",
            "COMMERCIAL",
            "COMMERCIAL_BASE",
            "COMMERCIAL_PLUS",
            "CONTRACT"
          ]
        },
        "price": {
          "type": "number",
          "description": "The postage price.",
          "format": "double"
        },
        "weight": {
          "type": "number",
          "description": "The calculated weight for the package based on user input.  The greater of dimWeight and weight will be used to calculated the rate.",
          "format": "double"
        },
        "dimWeight": {
          "type": "number",
          "description": "The calculated dimensional weight for the package based on user provided dimensions. The greater of dimWeight and weight will be used to calculated the rate.",
          "format": "double"
        },
        "fees": {
          "type": "array",
          "description": "The fees associated with the package.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The name of the fee."
              },
              "SKU": {
                "type": "string",
                "description": "The pricing SKU for the fee."
              },
              "price": {
                "type": "number",
                "description": "The price for the fee.",
                "format": "double"
              }
            }
          }
        },
        "startDate": {
          "type": "string",
          "description": "Effective start date of the rate.",
          "format": "date"
        },
        "endDate": {
          "type": "string",
          "description": "Effective end date of the rate.  If blank the rate doesn't have an end date as of yet.",
          "pattern": "^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
        },
        "mailClass": {
          "type": "string",
          "description": "The mail class of the price."
        },
        "zone": {
          "type": "string",
          "description": "Indicates the price group for a given `destinationCountryCode`, `mailClass`, `mailingDate`, and `rateIndicator`."
        },
        "processingCategory": {
          "type": "string",
          "description": "Processing category for the provided rate, this value can be used in the international labels API to ensure the provided rate is applied.\n\n* `CARDS` - Cards, translates to PTR code `0`\n* `LETTERS` - Letters, translates to PTR code `1`\n* `FLATS` - Flats, translates to PTR code `2`\n* `MACHINABLE` - Machinable Parcel, translates to PTR code `3`\n* `IRREGULAR` - Irregular Parcel, translates to PTR code `4` - This option is deprecated in favor of `NONSTANDARD` and will no longer be returned as of 01/19/2025.\n* `NON_MACHINABLE` - Non-machinable parcel, translates to PTR code `5` - This option is deprecated in favor of `NONSTANDARD` and will no longer be returned as of 01/19/2025.\n* `NONSTANDARD` - Nonstandard Parcel, translates to PTR code `5`\n* `CATALOGS` - Catalogs, translates to PTR code `C`\n* `OPEN_AND_DISTRIBUTE` - Open and Distribute, translates to PTR code `O`\n* `RETURNS` - Returns, translates to PTR code `R`\n* `SOFT_PACK_MACHINABLE` - Soft Pack Machinable, translates to PTR code `S`\n* `SOFT_PACK_NON_MACHINABLE` - Soft Package Non-machinable, translates to PTR code `T`\n",
          "enum": [
            "CARDS",
            "LETTERS",
            "FLATS",
            "MACHINABLE",
            "IRREGULAR",
            "NON_MACHINABLE",
            "NONSTANDARD",
            "CATALOGS",
            "OPEN_AND_DISTRIBUTE",
            "RETURNS",
            "SOFT_PACK_MACHINABLE",
            "SOFT_PACK_NON_MACHINABLE"
          ]
        },
        "rateIndicator": {
          "type": "string",
          "description": "Two-digit rate indicator code for the provided rate, this value can be used in the international labels API to ensure the provided rate is applied."
        },
        "destinationEntryFacilityType": {
          "type": "string",
          "description": "Destination Entry Facility type for the provided rate, this value can be used in the international labels API to ensure the provided rate is applied.\n\n* `NONE` - None, translates to PTR code `N`\n* `INTERNATIONAL_SERVICE_CENTER` - International Service Center, translates to PTR code `I`\n",
          "enum": [
            "NONE",
            "INTERNATIONAL_SERVICE_CENTER"
          ]
        },
        "warnings": {
          "$ref": "#/$defs/WarningsList"
        },
        "productName": {
          "type": "string",
          "description": "A business friendly name for a product that can be displayed to a customer on a shipping portal"
        },
        "productDefinition": {
          "type": "string",
          "description": "A business friendly description for a product that can be displayed to a customer on a shipping portal"
        }
      },
      "additionalProperties": false,
      "description": "Informative details about the price."
    },
    "RateOption": {
      "title": "Base Rates Query Result",
      "type": "object",
      "properties": {
        "totalBasePrice": {
          "type": "number",
          "description": "The total price, including the rate, fees and pound postage."
        },
        "rates": {
          "type": "array",
          "description": "List of rate details, including SKU, description and rate ingredients",
          "items": {
            "$ref": "#/$defs/RateDetails"
          }
        }
      },
      "additionalProperties": true,
      "description": "The prices that match the search criteria."
    },
    "SKU": {
      "type": "string",
      "description": "The stock keeping unit for the designated rate."
    },
    "WarningsList": {
      "title": "Warnings",
      "type": "array",
      "description": "A list of warnings associated with the rate calculation.",
      "items": {
        "type": "object",
        "properties": {
          "warningCode": {
            "type": "string",
            "description": "Code representing the type of warning."
          },
          "warningDescription": {
            "type": "string",
            "description": "Description of the warning."
          }
        }
      }
    }
  }
}