Total Rates Query

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-total-rates-query-schema.json",
  "title": "Total Rates Query",
  "description": "Search parameters for base rate and extra service rate.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-international-prices-openapi.yml#/components/schemas/TotalRatesQuery",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/$defs/InternationalRateListQuery"
    },
    {
      "type": "object",
      "properties": {
        "requestDutiesTaxesFees": {
          "type": "boolean",
          "description": "When `true` the returned `rateOption` elements will include the duties and taxes cost for each item and package fees.",
          "default": false
        },
        "destinationCity": {
          "type": "string",
          "maxLength": 28,
          "minLength": 1,
          "description": "When `requestDutiesTaxesFees` is `true` then `destinationCity` may be required based on the country of import."
        },
        "destinationState": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^\\w{2}$",
          "description": "When `requestDutiesTaxesFees` is `true` then `destinationState` may be required based on the country of import."
        },
        "items": {
          "type": "array",
          "maxItems": 30,
          "description": "A list of items utilized for pricing when `requestDutiesTaxesFees` is `true`.",
          "items": {
            "$ref": "#/$defs/TotalRatesRequestLandedCostItem"
          }
        },
        "itemValue": {
          "type": "number",
          "description": "The value of the all items in the package. Required for Insurance and Registered Mail.",
          "format": "double",
          "minimum": 0
        },
        "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": "integer",
            "description": "Extra Service Code requested\n * `370` - USPS Delivery Duties Paid Fee\n * `813` - HAZMAT Class 7 - Radioactive Materials Package\n * `820` - HAZMAT Class 9 - Lithium batteries, unmarked package\n * `826` - HAZMAT Division 6.2 – Infectious Substances Package\n * `857` - Hazardous Material\n * `930` - Insurance <= $500\n * `931` - Insurance > $500\n * `955` - Return Receipt (Unsupported as of 01/19/2025)",
            "enum": [
              370,
              813,
              820,
              826,
              857,
              930,
              931,
              955
            ]
          }
        }
      }
    }
  ],
  "$defs": {
    "DestinationCountryCode": {
      "title": "Destination Country Code",
      "pattern": "^[A-Z]{2}$",
      "type": "string",
      "description": "The ISO 3166-1 alpha-2 code representing the shipping destination."
    },
    "ForeignPostalCode": {
      "type": "string",
      "description": "The foreign postal code for the package.\n\nNote:\n- Different shipping destinations may require a postal code for shipping.  For more details, review the [Individual Country Listing](https://pe.usps.com/text/imm/immctry.htm) for your shipping destination\n"
    },
    "Height": {
      "type": "number",
      "description": "The package height in inches.",
      "format": "double"
    },
    "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"
      ]
    },
    "InternationalRateListQuery": {
      "title": "International Rate List Query",
      "required": [
        "destinationCountryCode",
        "height",
        "length",
        "originZIPCode",
        "weight",
        "width"
      ],
      "type": "object",
      "properties": {
        "originZIPCode": {
          "$ref": "#/$defs/originZIPCode"
        },
        "foreignPostalCode": {
          "$ref": "#/$defs/ForeignPostalCode"
        },
        "destinationCountryCode": {
          "$ref": "#/$defs/DestinationCountryCode"
        },
        "weight": {
          "$ref": "#/$defs/WeightPounds"
        },
        "mailingDate": {
          "$ref": "#/$defs/MailingDate"
        },
        "length": {
          "$ref": "#/$defs/Length"
        },
        "width": {
          "$ref": "#/$defs/Width"
        },
        "height": {
          "$ref": "#/$defs/Height"
        },
        "priceType": {
          "$ref": "#/$defs/InternationalPriceType"
        },
        "mailClass": {
          "type": "string",
          "description": "The mail service requested.\n * 'FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE'\n * 'PRIORITY_MAIL_INTERNATIONAL'\n * 'PRIORITY_MAIL_EXPRESS_INTERNATIONAL'\n * 'GLOBAL_EXPRESS_GUARANTEED' - Global Express Guaranteed Service is suspended as of September 29, 2024.\n * 'ALL'",
          "enum": [
            "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE",
            "PRIORITY_MAIL_INTERNATIONAL",
            "PRIORITY_MAIL_EXPRESS_INTERNATIONAL",
            "GLOBAL_EXPRESS_GUARANTEED",
            "ALL"
          ]
        },
        "accountType": {
          "type": "string",
          "description": "The type of payment account linked to a contract rate.\n\nNote:\n- `METER` pricing is only available to PC Postage providers.\n",
          "enum": [
            "EPS",
            "PERMIT",
            "METER"
          ]
        },
        "accountNumber": {
          "pattern": "^\\d+$",
          "type": "string",
          "description": "The Enterprise Payment Account, Permit number or PC Postage meter number associated with a contract."
        }
      },
      "additionalProperties": false,
      "description": "Informative details about all possible rate based on the ingredients."
    },
    "Length": {
      "type": "number",
      "description": "The package length in inches.  The maximum dimension is always length.",
      "format": "double"
    },
    "MailingDate": {
      "type": "string",
      "description": "The date the package or letter/flat will be mailed. The mailing date may be today plus 0 to 7 days in advance.        ",
      "format": "date"
    },
    "TotalRatesRequestLandedCostItem": {
      "title": "Delivery Duties, Taxes, and Fees Item",
      "description": "When `requestDutiesTaxesFees` is true at least one item is required.",
      "type": "object",
      "required": [
        "itemId",
        "itemValue",
        "itemQuantity"
      ],
      "properties": {
        "itemId": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1,
          "description": "A user-provided item identifier. The itemId is echoed in the response to correlate duties and taxes to this item.",
          "pattern": "^\\w{1,20}$"
        },
        "itemValue": {
          "maximum": 999999.99,
          "minimum": 0.01,
          "type": "number",
          "format": "float",
          "description": "The value of the item."
        },
        "itemQuantity": {
          "minimum": 1,
          "type": "number",
          "description": "The quantity of the item."
        },
        "weight": {
          "minimum": 0.001,
          "type": "number",
          "description": "The calculated weight for each individual item within a quantity based on user input.",
          "format": "double"
        },
        "countryOfOrigin": {
          "pattern": "[A-Z]{2}",
          "type": "string",
          "description": "A two digit Alpha Country Code defined by ISO representing where the item is from."
        },
        "HSTariffNumber": {
          "maxLength": 14,
          "minLength": 6,
          "type": "string",
          "description": "The HS tariff number is based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization.  The value should follow the regular expression pattern: `^\\.*(?:[A-Za-z\\d]\\.*){6,14}$`.  For more information, see: [https://hts.usitc.gov/current](https://hts.usitc.gov/current)."
        }
      }
    },
    "WeightPounds": {
      "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. Weight unit of measurement is in pounds.",
      "format": "double"
    },
    "Width": {
      "type": "number",
      "description": "The package width in inches.  The second longest dimension is always width.",
      "format": "double"
    },
    "originZIPCode": {
      "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
      "type": "string",
      "description": "The originating ZIP Code for the package."
    }
  }
}