International Extra Service Rate Query

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-extra-service-rate-query-schema.json",
  "title": "International Extra Service Rate Query",
  "description": "Search parameters for extra services rates.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-international-prices-openapi.yml#/components/schemas/ExtraServiceRateQuery",
  "required": [
    "destinationCountryCode",
    "mailClass",
    "priceType",
    "rateIndicator",
    "weight"
  ],
  "type": "object",
  "properties": {
    "extraServices": {
      "type": "array",
      "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)",
      "items": {
        "type": "integer",
        "enum": [
          370,
          813,
          820,
          826,
          857,
          930,
          931,
          955
        ]
      }
    },
    "extraService": {
      "title": "Extra Service Codes",
      "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
      ]
    },
    "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.",
      "enum": [
        "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE",
        "PRIORITY_MAIL_INTERNATIONAL",
        "PRIORITY_MAIL_EXPRESS_INTERNATIONAL",
        "GLOBAL_EXPRESS_GUARANTEED"
      ]
    },
    "priceType": {
      "type": "string",
      "description": "Price type can be \n  * 'RETAIL'\n  * 'COMMERCIAL'\n  * 'COMMERCIAL_PLUS'\n  * 'NSA",
      "enum": [
        "RETAIL",
        "COMMERCIAL",
        "COMMERCIAL_PLUS",
        "NSA"
      ]
    },
    "itemValue": {
      "type": "string",
      "description": "The value of the item. Required for Insurance and Registered Mail."
    },
    "weight": {
      "$ref": "#/$defs/WeightPounds"
    },
    "mailingDate": {
      "$ref": "#/$defs/MailingDate"
    },
    "rateIndicator": {
      "type": "string",
      "description": "Use to specify USPS containers/packaging or container attributes that may affect postage.\n * E4 - Priority Mail Express Flat Rate Envelope - Post Office To Addressee\n * E6 - Priority Mail Express Legal Flat Rate Envelope\n * FA - Legal Flat Rate Envelope\n * FB - Medium Flat Rate Box/Large Flat Rate Bag\n * FE - Flat Rate Envelope\n * FP - Padded Flat Rate Envelope\n * FS - Small Flat Rate Box\n * PA - Priority Mail Express International Single Piece\n * PL - Large Flat Rate Box\n * SP - Single Piece\n * EP - ECOMPRO Single Piece\n * HA - ECOMPRO Legal Flat Rate Envelope\n * HB - ECOMPRO Medium Flat Rate Box\n * HE - ECOMPRO Flat Rate Envelope\n * HL - ECOMPRO Large Flat Rate Box\n * HP - ECOMPRO Padded Flat Rate Envelope\n * HS - ECOMPRO Small Flat Rate Box\n * LE - Single-piece parcel",
      "enum": [
        "E4",
        "E6",
        "E7",
        "FA",
        "FB",
        "FE",
        "FP",
        "FS",
        "PA",
        "PL",
        "SP",
        "EP",
        "HA",
        "HB",
        "HE",
        "HL",
        "HP",
        "HS",
        "LE"
      ]
    },
    "destinationCountryCode": {
      "$ref": "#/$defs/DestinationCountryCode"
    },
    "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,
  "$defs": {
    "DestinationCountryCode": {
      "title": "Destination Country Code",
      "pattern": "^[A-Z]{2}$",
      "type": "string",
      "description": "The ISO 3166-1 alpha-2 code representing the shipping destination."
    },
    "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"
    },
    "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"
    }
  }
}