{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/usps/json-schema/usps-options-request-schema.json", "title": "OptionsRequest", "description": "All ingredients requested to calculate pricing based on USPS service standards.", "x-generated": "2026-11-11", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/usps-shipping-options-openapi.yml#/components/schemas/OptionsRequest", "oneOf": [ { "$ref": "#/$defs/DomesticOptionsRequest" }, { "$ref": "#/$defs/InternationalOptionsRequest" } ], "$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." }, "DestinationZIPCode": { "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$", "type": "string", "description": "The destination ZIP code for 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" }, "DomesticOptionsRequest": { "title": "Domestic Options Request", "description": "Domestic Options Request", "required": [ "destinationZIPCode", "originZIPCode", "packageDescription", "pricingOptions" ], "type": "object", "properties": { "pricingOptions": { "description": "List of domestic pricing options", "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/DomesticPricingOption" } }, "originZIPCode": { "$ref": "#/$defs/OriginZIPCode" }, "destinationZIPCode": { "$ref": "#/$defs/DestinationZIPCode" }, "destinationEntryFacilityType": { "type": "string", "description": "Types of Facilities:\n\n* NONE - Translate to Destination Rate Indicator N\n* DESTINATION_NETWORK_DISTRIBUTION_CENTER - Translate to Destination Rate Indicator B\n* DESTINATION_SECTIONAL_CENTER_FACILITY - Translate to Destination Rate Indicator S\n* DESTINATION_DELIVERY_UNIT - Translate to Destination Rate Indicator D\n* DESTINATION_SERVICE_HUB - Translate to Destination Rate Indicator H\n* DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER - Translate to Destination Rate Indicator B\n\nNote:\n- The Destination Entry Facility Type is only used in calculating Shipping Standards.\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", "DESTINATION_NETWORK_DISTRIBUTION_CENTER", "DESTINATION_SECTIONAL_CENTER_FACILITY", "DESTINATION_DELIVERY_UNIT", "DESTINATION_SERVICE_HUB", "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER" ], "default": "NONE" }, "packageDescription": { "$ref": "#/$defs/DomesticPackageDescription" }, "shippingFilter": { "type": "string", "description": "A filter for domestic results to return only one response based on lowest price or fastest service standard", "enum": [ "PRICE", "SERVICE_STANDARDS" ] } }, "additionalProperties": false }, "DomesticPackageDescription": { "description": "Details of package being shipped", "allOf": [ { "$ref": "#/$defs/ShippingOptionsPackageDescription" }, { "required": [ "mailClass" ], "type": "object", "properties": { "mailClass": { "type": "string", "description": "Mail classes for the label.\n\nNote:\n- `PARCEL_SELECT_LIGHTWEIGHT` is deprecated and will convert to `PARCEL_SELECT`.\n- `FIRST-CLASS_PACKAGE_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE`.\n- `ALL` is deprecated and will convert to `ALL_OUTBOUND`.\n- Certain mail classes, such as `MEDIA_MAIL`, `BOUND_PRINTED_MATTER`, and `LIBRARY_MAIL`, have eligibility rules on what can be mailed using that service. For more details on these mail classes, please visit [What are Package Services?](https://faq.usps.com/s/article/What-are-Package-Services).\n- The Heavy Printed Matter product is supported with `MARKETING_MAIL_PARCELS`. To create Heavy Printed Matter labels, the `rateIndicator` should be set to `PR` or `NP` for Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter or to `PN` or `NN` for Nonprofit Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter respectively.\n", "enum": [ "PARCEL_SELECT", "PARCEL_SELECT_LIGHTWEIGHT", "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", "FIRST-CLASS_PACKAGE_SERVICE", "LIBRARY_MAIL", "MEDIA_MAIL", "BOUND_PRINTED_MATTER", "MARKETING_MAIL_PARCELS", "ALL", "ALL_OUTBOUND", "ALL_RETURNS" ] }, "extraServices": { "maxItems": 5, "minItems": 0, "type": "array", "description": "Extra Services requested on the package. The available options are:\n* 365 - Global Direct Entry\n* 415 - USPS Label Delivery\n* 452 - USPS Returns\n* 480 - Tracking Plus 6 Months\n* 481 - Tracking Plus 1 Year\n* 482 - Tracking Plus 3 Years\n* 483 - Tracking Plus 5 Years\n* 484 - Tracking Plus 7 Years\n* 485 - Tracking Plus 10 Years\n* 486 - Tracking Plus Signature 3 Years\n* 487 - Tracking Plus Signature 5 Years\n* 488 - Tracking Plus Signature 7 Years\n* 489 - Tracking Plus Signature 10 Years\n* 498 - PO Box Locker – Stocking Fee (NSA Only)\n* 500 - PO Box Locker – Self-Service Pickup Fee (NSA Only)\n* 501 - PO Box Locker – Clerk-Assisted Pickup Fee (NSA Only)\n* 502 - PO Box Locker – Local Delivery Fee (NSA Only)\n* 810 - HAZMAT Air Eligible Ethanol Package\n* 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package\n* 812 - HAZMAT Class 3 – Flammable Liquid Package\n* 813 - HAZMAT Class 7 - Radioactive Materials Package\n* 814 - HAZMAT Class 8 - Corrosive Materials Package\n* 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package\n* 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package\n* 817 - HAZMAT Class 9 - Lithium Battery - Returns Package\n* 818 - HAZMAT Class 9 - Lithium batteries, marked package\n* 819 - HAZMAT Class 9 - Dry Ice Package\n* 820 - HAZMAT Class 9 - Lithium batteries, unmarked package\n* 821 - HAZMAT Class 9 - Magnetized Materials Package\n* 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package\n* 823 - HAZMAT Division 5.1 - Oxidizers Package\n* 824 - HAZMAT Division 5.2 - Organic Peroxides Package\n* 825 - HAZMAT Division 6.1 – Toxic Materials Package\n* 826 - HAZMAT Division 6.2 – Infectious Substances Package\n* 827 - HAZMAT Excepted Quantity Provision Package\n* 828 - HAZMAT Ground Only\n* 829 - HAZMAT ID8000 Consumer Commodity Package\n* 830 - HAZMAT Lighters Package\n* 831 - HAZMAT LTD QTY Ground Package\n* 832 - HAZMAT Small Quantity Provision Package\n* 853 - Perishable Material\n* 856 - Live Animals Transportation Fee\n* 857 - Hazardous Material\n* 858 - Cremated Remains\n* 910 - Certified Mail\n* 911 - Certified Mail Restricted Delivery\n* 912 - Certified Mail Adult Signature Required\n* 913 - Certified Mail Adult Signature Restricted Delivery\n* 915 - Collect on Delivery (COD)\n* 917 - COD Restricted Delivery\n* 920 - USPS Tracking\n* 921 - Signature Confirmation\n* 922 - Adult Signature Required 21 or Over\n* 923 - Adult Signature Restricted Delivery 21 or Over\n* 924 - Signature Confirmation Restricted Delivery\n* 925 - Priority Mail Express Merchandise Insurance\n* 930 - Insurance <= $500\n* 931 - Insurance > $500\n* 934 - Insurance Restricted Delivery\n* 940 - Registered Mail\n* 941 - Registered Mail Restricted Delivery\n* 955 - Return Receipt\n* 957 - Return Receipt Electronic\n* 972 - Live Animal and Perishable Handling Fee\n* 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)\n* 984 - Parcel Locker Delivery\n* 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)\n* 991 - Sunday Delivery\n", "items": { "$ref": "#/$defs/ExtraService" } }, "packageValue": { "minimum": 0, "type": "number", "description": "The merchandise value of the package, in US dollars. Required to receive prices for Insurance and Collect On Delivery extra services. The price of Insurance, Collect On Delivery, and Registered Mail extra services will vary based on the `packageValue` requested." }, "mailingDate": { "description": "The local date on which the package will be mailed. If the time is not provided, it will be defaulted to 6:00 p.m. local time. The local time is based on the `originZIPCode` provided in the request.\n", "type": "string", "oneOf": [ { "$ref": "#/$defs/MailingDate" }, { "$ref": "#/$defs/MailingDateTime" } ] } }, "additionalProperties": true, "description": "Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more." } ] }, "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." } } } } } }, "ExtraService": { "title": "Extra Service Codes", "type": "integer", "description": "Available extra service codes.", "enum": [ 365, 415, 452, 480, 481, 482, 483, 484, 485, 486, 487, 488, 489, 498, 500, 501, 502, 810, 811, 812, 813, 814, 815, 816, 817, 818, 819, 820, 821, 822, 823, 824, 825, 826, 827, 828, 829, 830, 831, 832, 853, 856, 857, 858, 910, 911, 912, 913, 915, 917, 920, 921, 922, 923, 924, 925, 930, 931, 934, 940, 941, 955, 957, 972, 981, 984, 986, 991 ] }, "InternationalExtraService": { "title": "Extra Service Codes", "type": "integer", "description": "Extra Services requested on the package. The available options are:\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)\n", "enum": [ 370, 813, 820, 826, 857, 930, 931, 955 ] }, "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 }, "InternationalOptionsRequest": { "title": "International Options Request", "description": "International Options Request", "required": [ "destinationCountryCode", "originZIPCode", "packageDescription", "pricingOptions" ], "type": "object", "properties": { "pricingOptions": { "description": "List of international pricing options", "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/InternationalPricingOption" } }, "originZIPCode": { "$ref": "#/$defs/OriginZIPCode" }, "foreignPostalCode": { "$ref": "#/$defs/PostalCode" }, "destinationCountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "The ISO 3166-1 alpha-2 code representing the shipping destination." }, "packageDescription": { "$ref": "#/$defs/InternationalPackageDescription" }, "shippingFilter": { "type": "string", "description": "A filter for international results to return only one response based on lowest price. There are no service standards for international.", "enum": [ "PRICE" ] }, "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/InternationalOptionsRequestLandedCostItem" } } }, "additionalProperties": false }, "InternationalOptionsRequestLandedCostItem": { "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, "pattern": "^\\w{1,20}$", "description": "A user-provided item identifier. The itemId is echoed in the response to correlate duties and taxes to this item." }, "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." }, "itemWeight": { "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)." } } }, "InternationalPackageDescription": { "description": "Details of package being shipped", "allOf": [ { "$ref": "#/$defs/ShippingOptionsPackageDescription" }, { "required": [ "mailClass" ], "type": "object", "properties": { "mailClass": { "type": "string", "description": "International Mail classes for the label.\n\n`GLOBAL_EXPRESS_GUARANTEED` is supported by shipping options, but is not supported by labels. 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", "ALL" ] }, "extraServices": { "maxItems": 5, "minItems": 0, "type": "array", "description": "Extra Services requested on the package. The available options are:\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)\n", "items": { "$ref": "#/$defs/InternationalExtraService" } }, "packageValue": { "minimum": 0, "type": "number", "description": "The merchandise value of the package, in US dollars. Required to receive prices for Insurance. The price of the Insurance extra service will vary based on the `packageValue` requested." }, "mailingDate": { "type": "string", "description": "Supports either a date or date-time entry, if using a date the time will be defaulted to 6:00 pm local time for the purpose of Service Delivery Standard estimates. A mailing date of 0-30 days in advance can be requested. ", "oneOf": [ { "$ref": "#/$defs/MailingDate" }, { "$ref": "#/$defs/MailingDateTime" } ] } }, "additionalProperties": true, "description": "Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more." } ] }, "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" } ] }, "MailingDate": { "type": "string", "description": "The date package will be mailed. The mailing date may be today plus 0 to 30 days in advance. Enter the date in the full-date notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).", "format": "date" }, "MailingDateTime": { "type": "string", "description": "The date and time a package will be mailed. The mailing date may be today plus 0 to 30 days in advance. Enter the date in the date-time notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).", "format": "date-time" }, "OriginZIPCode": { "pattern": "^\\d{5}(?:[-\\s]\\d{4})?$", "type": "string", "description": "The originating ZIP code for the package." }, "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 }, "ShippingOptionsPackageDescription": { "title": "Package Description", "type": "object", "required": [ "height", "length", "weight", "width" ], "properties": { "weight": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The package weight, in weightUOM (Unit Of Measure). Items must weigh 70 pounds (1120 ounces) or less." }, "length": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The length of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "height": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The height of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "width": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The width of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "girth": { "minimum": 0, "exclusiveMinimum": true, "type": "number", "description": "The girth of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages." }, "hasNonstandardCharacteristics": { "default": false, "type": "boolean", "description": "Package is nonstandard. Nonstandard packages include cylindrical tubes and rolls, certain high-density items, cartons containing more than 24 ounces of liquids in one or more glass containers, cartons containing 1 gallon or more of liquid in metal or plastic containers, and items in [201.7.6.2](https://pe.usps.com/text/dmm300/201.htm#7.6.2)." } }, "additionalProperties": true, "description": "Package Definitions" } } }