OptionsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-options-response-schema.json",
  "title": "OptionsResponse",
  "description": "The response type varies depending on which request is passed",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-shipping-options-openapi.yml#/components/schemas/OptionsResponse",
  "type": "object",
  "oneOf": [
    {
      "$ref": "#/$defs/DomesticOptionsResponse"
    },
    {
      "$ref": "#/$defs/InternationalOptionsResponse"
    }
  ],
  "$defs": {
    "AllMailClasses": {
      "description": "List or enumeration of the domestic or international mail classes available",
      "oneOf": [
        {
          "$ref": "#/$defs/DomesticMailClass"
        },
        {
          "$ref": "#/$defs/InternationalMailClass"
        }
      ]
    },
    "Commitment": {
      "title": "Commitment",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Commitment name such as 1 Day, 2 Days, 3 Days, MILITARY, DPO, NO STD, or UNAVAILABLE."
        },
        "scheduleDeliveryDate": {
          "type": "string",
          "description": "Date USPS expects that the package or mailpiece will be delivered based on the origin, destination, and drop-off time and date in the request. Actual delivery date may vary based on when the package or mailpiece is entered or other conditions.\n\nNote: This field has been deprecated in favor of `expectedDeliveryDate` and will be removed in a future release. Please transition to using `expectedDeliveryDate`.\n",
          "format": "date",
          "deprecated": true
        },
        "expectedDeliveryDate": {
          "type": "string",
          "description": "Date in the YYYY-MM-DD format.",
          "format": "date"
        },
        "effectiveAcceptanceDate": {
          "type": "string",
          "description": "The effective acceptance date based on the requested acceptance date, time, and the facility cut-off times.",
          "format": "date"
        },
        "cutOffTime": {
          "type": "number",
          "description": "The latest time packages may be entered at the acceptance location. Packages entered after the cut-off time will have an effective date one day after the requested acceptance date and time.",
          "pattern": "^([0-1][0-9]|2[0-3])[0-5][0-9]$"
        },
        "guaranteedDelivery": {
          "type": "boolean",
          "description": "If true, the expectedDeliveryDate is guaranteed."
        },
        "isPriorityMailNextDay": {
          "type": "boolean",
          "description": "Indicates if the commitment is for Priority Mail Next Day service."
        }
      },
      "additionalProperties": true,
      "description": "The commitment and the scheduled delivery date of the package."
    },
    "DomesticMailClass": {
      "type": "string",
      "description": "The domestic mail service requested.\n",
      "enum": [
        "PARCEL_SELECT",
        "USPS_CONNECT_LOCAL",
        "USPS_CONNECT_REGIONAL",
        "USPS_CONNECT_MAIL",
        "USPS_GROUND_ADVANTAGE",
        "USPS_GROUND_ADVANTAGE_RETURN_SERVICE",
        "PRIORITY_MAIL_EXPRESS",
        "PRIORITY_MAIL_EXPRESS_RETURN_SERVICE",
        "PRIORITY_MAIL",
        "PRIORITY_MAIL_RETURN_SERVICE",
        "LIBRARY_MAIL",
        "MEDIA_MAIL",
        "BOUND_PRINTED_MATTER",
        "MARKETING_MAIL_PARCELS"
      ]
    },
    "DomesticOptions": {
      "type": "object",
      "properties": {
        "mailClass": {
          "$ref": "#/$defs/DomesticMailClass"
        },
        "rateOptions": {
          "description": "List of domestic rate options",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DomesticRateOptions"
          }
        }
      },
      "additionalProperties": false,
      "description": "TBD"
    },
    "DomesticOptionsResponse": {
      "type": "object",
      "properties": {
        "originZIPCode": {
          "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
          "type": "string",
          "description": "This is the originating ZIP Code™ for the package."
        },
        "destinationZIPCode": {
          "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
          "type": "string",
          "description": "This is the destination ZIP Code™ for the package."
        },
        "pricingOptions": {
          "description": "List of domestic pricing options",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DomesticPricingOption"
          }
        }
      },
      "additionalProperties": false,
      "description": "TBD"
    },
    "DomesticPricingOption": {
      "description": "The option for domestic pricing",
      "type": "object",
      "properties": {
        "shippingOptions": {
          "description": "List of available shipping options and delivery options for the package",
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/$defs/DomesticOptions"
          }
        },
        "priceType": {
          "$ref": "#/$defs/PriceTypeRequest"
        },
        "paymentAccount": {
          "description": "The total amount to be charged for the shipment",
          "allOf": [
            {
              "$ref": "#/$defs/PaymentAccount"
            },
            {
              "type": "object",
              "properties": {
                "CRID": {
                  "type": "string",
                  "description": "Customer Registration ID (CRID) associated with the business or mailer. Used to retrieve any contract-specific service standards."
                }
              },
              "additionalProperties": true
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "DomesticRateOptions": {
      "type": "object",
      "description": "Options for domestic rate",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "commitment": {
              "$ref": "#/$defs/Commitment"
            }
          }
        },
        {
          "$ref": "#/$defs/RateOptions"
        }
      ]
    },
    "DutiesTaxesFeesQuote": {
      "title": "Duties, taxes, and fees details.",
      "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."
              }
            }
          }
        }
      }
    },
    "InternationalMailClass": {
      "type": "string",
      "description": "The international mail service requested.\n\nNote:\n- `GLOBAL_EXPRESS_GUARANTEED` - Global Express Guaranteed Service is suspended as of September 29, 2024.\n",
      "enum": [
        "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE",
        "PRIORITY_MAIL_INTERNATIONAL",
        "PRIORITY_MAIL_EXPRESS_INTERNATIONAL",
        "GLOBAL_EXPRESS_GUARANTEED"
      ]
    },
    "InternationalOptions": {
      "description": "Options specific to international shipments",
      "type": "object",
      "properties": {
        "mailClass": {
          "$ref": "#/$defs/InternationalMailClass"
        },
        "rateOptions": {
          "description": "List of rate options",
          "type": "array",
          "items": {
            "$ref": "#/$defs/InternationalRateOptions"
          }
        }
      },
      "additionalProperties": false
    },
    "InternationalOptionsResponse": {
      "type": "object",
      "properties": {
        "originZIPCode": {
          "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$",
          "type": "string",
          "description": "This is the originating ZIP Code™ for the package."
        },
        "foreignPostalCode": {
          "$ref": "#/$defs/PostalCode"
        },
        "destinationCountryCode": {
          "type": "string",
          "description": "Country of destination."
        },
        "pricingOptions": {
          "description": "List of international pricing options",
          "type": "array",
          "items": {
            "$ref": "#/$defs/InternationalPricingOption"
          }
        }
      },
      "additionalProperties": false,
      "description": "TBD"
    },
    "InternationalPricingOption": {
      "type": "object",
      "description": "Option for international pricing",
      "properties": {
        "shippingOptions": {
          "description": "List of available shipping services and delivery options for the package",
          "type": "array",
          "readOnly": true,
          "items": {
            "$ref": "#/$defs/InternationalOptions"
          }
        },
        "priceType": {
          "$ref": "#/$defs/PriceTypeRequest"
        },
        "paymentAccount": {
          "$ref": "#/$defs/PaymentAccount"
        }
      },
      "additionalProperties": false
    },
    "InternationalRateOptions": {
      "type": "object",
      "description": "Options for international rate",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "dutiesTaxesFeesQuote": {
              "$ref": "#/$defs/DutiesTaxesFeesQuote"
            }
          }
        },
        {
          "$ref": "#/$defs/RateOptions"
        }
      ]
    },
    "PaymentAccount": {
      "title": "Payment Account",
      "type": "object",
      "properties": {
        "accountType": {
          "type": "string",
          "description": "The type of payment account.\n\nNote:\n- `EPS`, `PERMIT`, and `METER` are only available for Outbound Mail Classes. \n- `METER` is only available to PC Postage Providers.  \n- `MID` is only available for Return Mail Classes.\n",
          "enum": [
            "EPS",
            "PERMIT",
            "METER",
            "MID"
          ]
        },
        "accountNumber": {
          "type": "string",
          "description": "The Enterprise Payment Account, Permit number, Mailer ID (MID), or PC Postage meter number associated with a contract."
        }
      },
      "additionalProperties": true,
      "description": "Payment account information. Used only if `priceType` is `CONTRACT`."
    },
    "PostalCode": {
      "maxLength": 11,
      "type": "string",
      "description": "This is the Postal Code used in an international addresses.\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"
    },
    "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"
      ]
    },
    "PriceTypeRequest": {
      "title": "Price Type",
      "type": "string",
      "description": "Price type of the Shipping Request.\n\nNote: \n- If `priceType` is `CONTRACT`, `paymentAccount` is required.\n",
      "default": "COMMERCIAL",
      "enum": [
        "RETAIL",
        "COMMERCIAL",
        "CONTRACT"
      ]
    },
    "RateOptions": {
      "type": "object",
      "description": "Options used to determine the rate",
      "properties": {
        "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",
          "format": "double"
        },
        "totalBasePrice": {
          "type": "number",
          "description": "The price of the rate, fees, and pound postage.",
          "format": "double"
        },
        "rates": {
          "description": "List of available rates for the package including base postage and extra service fees",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "description": "The description of the price."
              },
              "startDate": {
                "type": "string",
                "description": "Effective start date of the rate.",
                "format": "date"
              },
              "endDate": {
                "description": "Effective end date of the rate. If blank, the rate does not have an end date as of yet.",
                "type": "string",
                "pattern": "^$|^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
              },
              "SKU": {
                "type": "string",
                "description": "Pricing SKU."
              },
              "price": {
                "type": "number",
                "description": "Amount of Postage Required, does not include insurance or other extra service fees.",
                "format": "double"
              },
              "zone": {
                "type": "string",
                "description": "For domestic requests: indicates the calculated zone between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, and `weight`.\n\nFor international requests: indicates the price group for a given `destinationCountryCode`, `mailClass`, `mailingDate`, and `rateIndicator`.\n"
              },
              "weight": {
                "type": "number",
                "description": "The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less."
              },
              "dimWeight": {
                "type": "number",
                "description": "The dimensional weight of the package, if greater than specified in weight, in ounces."
              },
              "dimensionalWeight": {
                "type": "number",
                "description": "The dimensional weight of package, if greater than specified in weight, in ounces. This will be removed in July 2025.",
                "deprecated": true
              },
              "priceType": {
                "$ref": "#/$defs/PriceType"
              },
              "fees": {
                "type": "array",
                "description": "Fees associated to the package.",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Name of the fee."
                    },
                    "SKU": {
                      "type": "string",
                      "description": "Pricing SKU."
                    },
                    "price": {
                      "type": "number",
                      "description": "The price for the fee.",
                      "format": "double"
                    }
                  }
                }
              },
              "productName": {
                "type": "string",
                "description": "A business friendly name associated to the product that can be displayed to a customer on a shipping portal."
              },
              "productDefinition": {
                "type": "string",
                "description": "A business friendly description associated to the product that can be displayed to a customer on a shipping portal."
              },
              "processingCategory": {
                "type": "string",
                "description": "Processing category for the provided rate, this value can be used in the 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 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 labels API to ensure the provided rate is applied.\n\n* `NONE` - None, translates to PTR code `N`\n* `AREA_DISTRIBUTION_CENTER` - Area Distribution Center, translates to PTR code `A`\n* `AUXILIARY_SERVICE_FACILITY` - Auxiliary Service Facility, translates to PTR code `F`\n* `DESTINATION_DELIVERY_UNIT` - Destination Delivery Unit, translates to PTR code `D`\n* `DESTINATION_NETWORK_DISTRIBUTION_CENTER` - Destination Network Distribution Center, translates to PTR code `B`\n* `DESTINATION_SECTIONAL_CENTER_FACILITY` - Destination Sectional Center Facility, translates to PTR code `S`\n* `DESTINATION_SERVICE_HUB` - Destination Service Hub, translates to PTR code `H`\n* `INTERNATIONAL_SERVICE_CENTER` - International Service Center, translates to PTR code `I`\n* `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` - Destination Regional Processing Distribution Center, translates to PTR code `B`\n\nNote:\n* Effective 01/18/2026: `DESTINATION_NETWORK_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is no longer eligible.\n* Effective 01/18/2026: (NSA Only) `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is available as an option.\n",
                "enum": [
                  "NONE",
                  "AREA_DISTRIBUTION_CENTER",
                  "AUXILIARY_SERVICE_FACILITY",
                  "DESTINATION_DELIVERY_UNIT",
                  "DESTINATION_NETWORK_DISTRIBUTION_CENTER",
                  "DESTINATION_SECTIONAL_CENTER_FACILITY",
                  "DESTINATION_SERVICE_HUB",
                  "INTERNATIONAL_SERVICE_CENTER",
                  "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER"
                ]
              },
              "mailClass": {
                "$ref": "#/$defs/AllMailClasses"
              }
            },
            "additionalProperties": false
          }
        },
        "extraServices": {
          "type": "array",
          "description": "Extra services requested on the package.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the extra service."
              },
              "SKU": {
                "type": "string",
                "description": "SKU of the extra service."
              },
              "price": {
                "type": "number",
                "description": "The price for the extra service.",
                "format": "double"
              },
              "extraService": {
                "type": "string",
                "description": "The code for the extra service."
              },
              "priceType": {
                "$ref": "#/$defs/PriceType"
              },
              "warnings": {
                "type": "array",
                "description": "List of warnings",
                "items": {
                  "type": "object",
                  "properties": {
                    "warningCode": {
                      "type": "string",
                      "description": "Warning code in response to the request."
                    },
                    "warningDescription": {
                      "type": "string",
                      "description": "A human-readable message describing the warning."
                    }
                  }
                }
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": true
    }
  }
}