{ "$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 } } }