openapi: 3.0.0
info:
  title: Shipping Options
  description: "Find all relevant shipping options, rates and service standards."
  termsOfService: https://about.usps.com/termsofuse.htm
  contact:
    name: USPS Support
    email: apisupport@usps.gov
  version: 3.1.12
  x-updated-on: MM/DD/YYYY - <team name>
  x-reviewed-on: MM/DD/YYYY - <team name>
  x-approved-on: MM/DD/YYYY - <team name>
servers:
- url: https://api.usps.com/shipments/v3
  description: Base Path
paths:
  /options/search:
    post:
      tags:
      - Resources
      summary: Presents options for shipping a package.
      description: |-
        Based on the inputs below, the API generates a comprehensive list of shipping options that comply with USPS Shipping Standards, all within a single request.  For international mail classes deliveries there are no commitments.  APO, DPO, and FPO locations also do not offer commitments.
          | Element                          | Description |
          | -------------------------------- | --------|
          | **originZIPCode**                | The origin ZIP Code&#8482; is where the package is being mailed from and is used for calculating pricing. |
          | **destinationZIPCode**           | The destination ZIP Code&#8482; of the recipient is used for calculating pricing. |
          | **destinationEntryFacilityType** | The Destination Entry Facility Type the package will be mailed from and is used in calculating Shipping Standards. |
          | **packageDescription**           | Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more. |
          | **pricingOptions**               | Pricing options such as price type and supporting information needed for pricing the shipping option. |
      operationId: post-options-search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptionsRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/OptionsRequest'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionsResponse'
              examples:
                DomesticOptionsExample:
                  $ref: '#/components/examples/DomesticOptionsExample'
                InternationalOptionsExample:
                  $ref: '#/components/examples/InternationalOptionsExample'
              encoding:
                metadata:
                  contentType: application/json
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/OptionsResponse'
              examples:
                DomesticOptionsExample:
                  $ref: '#/components/examples/DomesticOptionsExample'
                InternationalOptionsExample:
                  $ref: '#/components/examples/InternationalOptionsExample'
              encoding:
                metadata:
                  contentType: application/xml
                  style: form
        "400":
          description: Bad Request.  There is an error in the received request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "401":
          description: Unauthorized request.
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "403":
          description: Access is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "429":
          description: Too Many Requests. Too many requests have been received from client in a short amount of time.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "503":
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        default:
          description: Other unanticipated errors that may occur.
          content: {}
      security:
        - OAuth:
            - shipments
components:
  schemas:
    OptionsRequest:
      description: All ingredients requested to calculate pricing based on USPS service standards.
      oneOf:
      - $ref: '#/components/schemas/DomesticOptionsRequest'
      - $ref: '#/components/schemas/InternationalOptionsRequest'
    DomesticOptionsRequest:
      required:
      - destinationZIPCode
      - originZIPCode
      - packageDescription
      - pricingOptions
      type: object
      properties:
        pricingOptions:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/DomesticPricingOption'
        originZIPCode:
          $ref: '#/components/schemas/originZIPCode'
        destinationZIPCode:
          $ref: '#/components/schemas/destinationZIPCode'
        destinationEntryFacilityType:
          type: string
          description: "Types of Facilities:\n\n* NONE - Translate to Destination Rate Indicator N\n\n* DESTINATION_NETWORK_DISTRIBUTION_CENTER - Translate to Destination Rate Indicator B\n\n* DESTINATION_SECTIONAL_CENTER_FACILITY - Translate to Destination Rate Indicator S \n\n* DESTINATION_DELIVERY_UNIT - Translate to Destination Rate Indicator D  \n\n* DESTINATION_SERVICE_HUB - Translate to Destination Rate Indicator H \n\nIf any value other than NONE is selected, a destinationEntryFacilityAddress is required.  The destinationEntryFacilityAddress must be a valid facility to drop your package.\n\nThe destination entry facility type must be set to 'NONE' when there is a value provided for the 'inductionZipCode' field. "
          enum:
          - NONE
          - DESTINATION_NETWORK_DISTRIBUTION_CENTER
          - DESTINATION_SECTIONAL_CENTER_FACILITY
          - DESTINATION_DELIVERY_UNIT
          - DESTINATION_SERVICE_HUB
          default: NONE
        packageDescription:
          $ref: '#/components/schemas/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
    InternationalOptionsRequest:
      required:
      - destinationCountryCode
      - originZIPCode
      - packageDescription
      - pricingOptions
      type: object
      properties:
        pricingOptions:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/InternationalPricingOption'
        originZIPCode:
          $ref: '#/components/schemas/originZIPCode'
        foreignPostalCode:
          $ref: '#/components/schemas/postalCode'
        destinationCountryCode:
          type: string
          description: Country of destination.
        packageDescription:
          $ref: '#/components/schemas/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
      additionalProperties: false
    OptionsResponse:
      type: object
      description: The response type varies depending on which request is passed
      oneOf:
      - $ref: '#/components/schemas/DomesticOptionsResponse'
      - $ref: '#/components/schemas/InternationalOptionsResponse'
    DomesticOptionsResponse:
      type: object
      properties:
        originZIPCode:
          pattern: "^\\d{5}(?:[-\\s]\\d{4})?$"
          type: string
          description: This is the originating ZIP Code&#8482; for the package.
        destinationZIPCode:
          pattern: "^\\d{5}(?:[-\\s]\\d{4})?$"
          type: string
          description: This is destination ZIP Code&#8482; for the package.
        pricingOptions:
          type: array
          xml:
            name: pricingOptions
            wrapped: true
          items:
            $ref: '#/components/schemas/DomesticPricingOption'
      additionalProperties: false
      description: TBD
    InternationalOptionsResponse:
      type: object
      properties:
        originZIPCode:
          pattern: "^\\d{5}(?:[-\\s]\\d{4})?$"
          type: string
          description: This is the originating ZIP Code&#8482; for the package.
        foreignPostalCode:
          $ref: '#/components/schemas/postalCode'
        destinationCountryCode:
          type: string
          description: Country of destination.
        pricingOptions:
          type: array
          xml:
            name: pricingOptions
            wrapped: true
          items:
            $ref: '#/components/schemas/InternationalPricingOption'
      additionalProperties: false
      description: TBD
    DomesticOptions:
      type: object
      properties:
        mailClass:
          $ref: "#/components/schemas/DomesticMailClass"
        rateOptions:
          type: array
          xml:
            name: rateOptions
            wrapped: true
          items:
            $ref: '#/components/schemas/DomesticRateOptions'
      additionalProperties: false
      description: TBD
      xml:
        name: shippingOption
    InternationalOptions:
      type: object
      properties:
        mailClass:
          $ref: "#/components/schemas/InternationalMailClass"
        rateOptions:
          type: array
          xml:
            name: rateOptions
            wrapped: true
          items:
            $ref: '#/components/schemas/RateOptions'
      additionalProperties: false
      xml:
        name: shippingOption
    DomesticRateOptions:
      type: object
      description: TBD
      allOf:
      - type: object
        properties:
          commitment:
            $ref: '#/components/schemas/Commitment'
      - $ref: '#/components/schemas/RateOptions'
    RateOptions:
      type: object
      properties:
        totalPrice:
          type: number
          description: |
            The total price, including the `totalBasePrice` and all extra service prices.

            Note: This field is only returned when `extraServices` are passed in the request.
          format: double
          example: 3.35
        totalBasePrice:
          type: number
          description: "The price of the rate, fees, and pound postage."
          format: double
          example: 0.63
        rates:
          type: array
          xml:
            wrapped: true
          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
                example: "2021-07-16"
              endDate:
                type: string
                description: Effective end date of the rate.  If blank the rate doesn't have an end date as of yet.
                format: date
                example: "2021-07-16"
              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: Indicates the number of postal rate zones between the origin and destination ZIP Code&#8482;.
              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 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: "#/components/schemas/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 for a product that can be displayed to a customer on a shipping portal
              productDefinition:
                type: string
                description: A business friendly description for a 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.

                  * `CARDS` - Cards, translates to PTR code `0`
                  * `LETTERS` - Letters, translates to PTR code `1`
                  * `FLATS` - Flats, translates to PTR code `2`
                  * `MACHINABLE` - Machinable Parcel, translates to PTR code `3`
                  * `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.
                  * `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.
                  * `NONSTANDARD` - Nonstandard parcel, translates to PTR code `5`
                  * `CATALOGS` - Catalogs, translates to PTR code `C`
                  * `OPEN_AND_DISTRIBUTE` - Open and Distribute, translates to PTR code `O`
                  * `RETURNS` - Returns, translates to PTR code `R`
                  * `SOFT_PACK_MACHINABLE` - Soft Pack Machinable, translates to PTR code `S`
                  * `SOFT_PACK_NON_MACHINABLE` - Soft Package Non-machinable, translates to PTR code `T`

                enum:
                  - CARDS
                  - LETTERS
                  - FLATS
                  - MACHINABLE
                  - IRREGULAR
                  - NON_MACHINABLE
                  - NONSTANDARD
                  - CATALOGS
                  - OPEN_AND_DISTRIBUTE
                  - RETURNS
                  - SOFT_PACK_MACHINABLE
                  - SOFT_PACK_NON_MACHINABLE
                example: NONSTANDARD
              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.
                example: "SP"
              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.

                  * `NONE` - None, translates to PTR code `N`
                  * `AREA_DISTRIBUTION_CENTER` - Area Distribution Center, translates to PTR code `A`
                  * `AUXILIARY_SERVICE_FACILITY` - Auxiliary Service Facility, translates to PTR code `F`
                  * `DESTINATION_DELIVERY_UNIT` - Destination Delivery Unit, translates to PTR code `D`
                  * `DESTINATION_NETWORK_DISTRIBUTION_CENTER` - Destination Network Distribution Center, translates to PTR code `B`
                  * `DESTINATION_SECTIONAL_CENTER_FACILITY` - Destination Sectional Center Facility, translates to PTR code `S`
                  * `DESTINATION_SERVICE_HUB` - Destination Service Hub, translates to PTR code `H`
                  * `INTERNATIONAL_SERVICE_CENTER` - International Service Center, translates to PTR code `I`
                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
                example: NONE
              mailClass:
                oneOf:
                  - $ref: "#/components/schemas/DomesticMailClass"
                  - $ref: "#/components/schemas/InternationalMailClass"
            additionalProperties: false
            xml:
              name: rate
        extraServices:
          type: array
          description: Extra services requested on the package.
          xml:
            name: extraServices
            wrapped: true
          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
              extraService:
                type: string
                description: The code for the extra service.
                example: "957"
              priceType:
                $ref: "#/components/schemas/PriceType"
              warnings:
                type: array
                xml:
                  wrapped: true
                items:
                  type: object
                  properties:
                    warningCode:
                      type: string
                      description: Warning code in response to the request.
                      example: "001"
                    warningDescription:
                      type: string
                      description: A human-readable message describing the warning.
                      example: Contract rate not found for request. Published rate returned.
                  xml:
                    name: warning
            additionalProperties: false
      additionalProperties: true
      description: TBD
      xml:
        name: rateOption
    DomesticPackageDescription:
      allOf:
      - $ref: '#/components/schemas/ShippingOptionsPackageDescription'
      - required:
        - height
        - length
        - mailClass
        - weight
        - width
        type: object
        properties:
          mailClass:
            type: string
            description: |
              Mail classes for the label.

              Note:
              - `PARCEL_SELECT_LIGHTWEIGHT` is deprecated and will convert to `PARCEL_SELECT`
              - `FIRST-CLASS_PACKAGE_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE`
            enum:
            - PARCEL_SELECT
            - PARCEL_SELECT_LIGHTWEIGHT
            - USPS_CONNECT_LOCAL
            - USPS_CONNECT_REGIONAL
            - USPS_CONNECT_MAIL
            - USPS_GROUND_ADVANTAGE
            - PRIORITY_MAIL_EXPRESS
            - PRIORITY_MAIL
            - FIRST-CLASS_PACKAGE_SERVICE
            - LIBRARY_MAIL
            - MEDIA_MAIL
            - BOUND_PRINTED_MATTER
            - DOMESTIC_MATTER_FOR_THE_BLIND
            - ALL
          extraServices:
            maxItems: 5
            minItems: 0
            type: array
            description: |         
              Extra Services requested on the package. The available options are:
              * 365 - Global Direct Entry
              * 415 - USPS Label Delivery Service
              * 480 - Tracking Plus 6 Months
              * 481 - Tracking Plus 1 Year
              * 482 - Tracking Plus 3 Years
              * 483 - Tracking Plus 5 Years
              * 484 - Tracking Plus 7 Years
              * 485 - Tracking Plus 10 Years
              * 486 - Tracking Plus Signature 3 Years
              * 487 - Tracking Plus Signature 5 Years
              * 488 - Tracking Plus Signature 7 Years
              * 489 - Tracking Plus Signature 10 Years
              * 810 - Hazardous Materials - Air Eligible Ethanol
              * 811 - Hazardous Materials - Class 1 – Toy Propellant/Safety Fuse Package
              * 812 - Hazardous Materials - Class 3 - Flammable and Combustible Liquids
              * 813 - Hazardous Materials - Class 7 – Radioactive Materials
              * 814 - Hazardous Materials - Class 8 – Air Eligible Corrosive Materials
              * 815 - Hazardous Materials - Class 8 – Nonspillable Wet Batteries
              * 816 - Hazardous Materials - Class 9 - Lithium Battery Marked Ground Only
              * 817 - Hazardous Materials - Class 9 - Lithium Battery Returns
              * 818 - Hazardous Materials - Class 9 - Marked Lithium Batteries
              * 819 - Hazardous Materials - Class 9 – Dry Ice
              * 820 - Hazardous Materials - Class 9 – Unmarked Lithium Batteries
              * 821 - Hazardous Materials - Class 9 – Magnetized Materials
              * 822 - Hazardous Materials - Division 4.1 – Mailable Flammable Solids and Safety Matches
              * 823 - Hazardous Materials - Division 5.1 – Oxidizers
              * 824 - Hazardous Materials - Division 5.2 – Organic Peroxides
              * 825 - Hazardous Materials - Division 6.1 – Toxic Materials
              * 826 - Hazardous Materials - Division 6.2 Biological Materials
              * 827 - Hazardous Materials - Excepted Quantity Provision
              * 828 - Hazardous Materials - Ground Only Hazardous Materials
              * 829 - Hazardous Materials - Air Eligible ID8000 Consumer Commodity
              * 830 - Hazardous Materials - Lighters
              * 831 - Hazardous Materials - Limited Quantity Ground
              * 832 - Hazardous Materials - Small Quantity Provision (Markings Required)
              * 853 - Special Handling - Perishable Material
              * 856 - Live Animal Transportation Fee
              * 857 - Hazardous Materials
              * 858 - Cremated Remains
              * 910 - Certified Mail
              * 911 - Certified Mail Restricted Delivery
              * 912 - Certified Mail Adult Signature Required
              * 913 - Certified Mail Adult Signature Restricted Delivery
              * 915 - Collect on Delivery
              * 917 - Collect on Delivery Restricted Delivery
              * 920 - USPS Tracking Electronic
              * 921 - Signature Confirmation
              * 922 - Adult Signature Required
              * 923 - Adult Signature Restricted Delivery
              * 924 - Signature Confirmation Restricted Delivery
              * 925 - Priority Mail Express Merchandise Insurance
              * 930 - Insurance <= $500
              * 931 - Insurance > $500
              * 934 - Insurance Restricted Delivery
              * 940 - Registered Mail
              * 941 - Registered Mail Restricted Delivery
              * 955 - Return Receipt
              * 957 - Return Receipt Electronic
              * 972 - Live Animal and Perishable Handling Fee
              * 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)
              * 984 - Parcel Locker Delivery
              * 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)
              * 991 - Sunday Delivery
            xml:
              name: extraServices
              wrapped: true
            items:
              $ref: '#/components/schemas/ExtraService'
          packageValue:
            minimum: 0
            type: number
            description: "The merchandise value of the package, in US dollars. Used to calculate Insurance Fees if requested."
            example: 35
          mailingDate:
            description: "The date on which the package will be mailed. If the time is not provided, it will be defaulted to 6:00 p.m."
            type: string
            oneOf:
            - $ref: '#/components/schemas/MailingDate'
            - $ref: '#/components/schemas/MailingDateTime'
        additionalProperties: true
        description: "Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more."
    InternationalPackageDescription:
      allOf:
      - $ref: '#/components/schemas/ShippingOptionsPackageDescription'
      - required:
        - height
        - length
        - mailClass
        - weight
        - width
        type: object
        properties:
          mailClass:
            type: string
            description: |
              International Mail classes for the label.

              `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.
            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:
              * 813 - Hazardous Materials - Class 7 – Radioactive Materials
              * 820 - Hazardous Materials - Class 9 – Unmarked Lithium Batteries
              * 826 - Hazardous Materials - Division 6.2 Biological Materials
              * 857 - Hazardous Materials          
              * 930 - Insurance <= $500
              * 931 - Insurance > $500
              * 955 - Return Receipt (Unsupported as of 01/19/2025)
            xml:
              name: extraServices
              wrapped: true
            items:
              $ref: '#/components/schemas/InternationalExtraService'
          packageValue:
            minimum: 0
            type: number
            description: "The merchandise value of the package, in US dollars. Used to calculate Insurance Fees if requested."
            example: 35
          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:
            - type: string
              format: date
            - type: string
              format: date-time
        additionalProperties: true
        description: "Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more."
    ExtraService:
      title: Extra Service Codes
      pattern: "\\d{3}"
      type: integer
      description: Available extra service codes.
      enum:
      - 365
      - 415
      - 480
      - 481
      - 482
      - 483
      - 484
      - 485
      - 486
      - 487
      - 488
      - 489
      - 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
      pattern: "\\d{3}"
      type: integer
      description: |
        Extra Services requested on the package. The available options are:
        * 813 - Hazardous Materials - Class 7 – Radioactive Materials
        * 820 - Hazardous Materials - Class 9 – Unmarked Lithium Batteries
        * 826 - Hazardous Materials - Division 6.2 Biological Materials
        * 857 - Hazardous Materials
        * 930 - Insurance <= $500
        * 931 - Insurance > $500
        * 955 - Return Receipt (Unsupported as of 01/19/2025)
      enum:
        - 813
        - 820
        - 826
        - 857
        - 930
        - 931
        - 955
    Commitment:
      title: Commitment
      type: object
      properties:
        name:
          type: string
          description: "Commitment name such as 1-day, 2-day, 3-day, Military, DPO"
        scheduleDeliveryDate:
          type: string
          description: Date in the YYYY-MM-DD format.
          format: date
        guaranteedDelivery:
          type: boolean
          description: "If true, the scheduleDeliveryDate is guaranteed."
      additionalProperties: false
      description: The commitment and scheduled delivery date of the package.
    DomesticPricingOption:
      required:
      - priceType
      type: object
      properties:
        shippingOptions:
          type: array
          readOnly: true
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/DomesticOptions'
        priceType:
          type: string
          description: |
            Price type can be:
            * `RETAIL`
            * `COMMERCIAL`
            * `CONTRACT`
          default: COMMERCIAL
          enum:
          - RETAIL
          - COMMERCIAL
          - CONTRACT
        paymentAccount:
          $ref: '#/components/schemas/PaymentAccount'
      additionalProperties: false
      xml:
        name: pricingOption
    InternationalPricingOption:
      required:
      - priceType
      type: object
      properties:
        shippingOptions:
          type: array
          readOnly: true
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/InternationalOptions'
        priceType:
          type: string
          description: Price type can be  * 'RETAIL' * 'COMMERCIAL' * 'CONTRACT'
          default: COMMERCIAL
          enum:
          - RETAIL
          - COMMERCIAL
          - CONTRACT
        paymentAccount:
          $ref: '#/components/schemas/PaymentAccount'
      additionalProperties: false
      xml:
        name: pricingOption
    PaymentAccount:
      title: Payment Account
      type: object
      properties:
        accountType:
          type: string
          description: The type of payment account.  METER pricing is only available to PC Postage providers.
          example: EPS
          enum:
          - EPS
          - PERMIT
          - METER
        accountNumber:
          type: string
          description: "The Enterprise Payment Account, Permit number, or PC Postage meter number associated with a contract."
      additionalProperties: false
      description: Payment account information.
    ErrorMessage:
      title: Error
      type: object
      properties:
        apiVersion:
          type: string
          description: The version of the API that was used and that raised the error.
        error:
          type: object
          properties:
            code:
              type: string
              description: The error status code that has been returned in response to the request.
            message:
              type: string
              description: A human-readable message describing the error.
            errors:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    description: The status code response returned to the client.
                  code:
                    type: string
                    description: An internal subordinate code used for error diagnosis.
                  title:
                    type: string
                    description: A human-readable title that identifies the error.
                  detail:
                    type: string
                    description: A human-readable description of the error that occurred.
                  source:
                    type: object
                    properties:
                      parameter:
                        type: string
                        description: The input in the request which caused an error.
                      example:
                        type: string
                        description: An example of a valid value for the input parameter.
                    additionalProperties: true
                    description: The element that is suspected of originating the error.  Helps to pinpoint the problem.
                additionalProperties: true
          additionalProperties: true
          description: The high-level error that has occurred as indicated by the status code.
      additionalProperties: true
      description: Standard error message response.
    originZIPCode:
      pattern: "^\\d{5}(?:[-\\s]\\d{4})?$"
      type: string
      description: The originating ZIP code for the package.
    destinationZIPCode:
      pattern: "^\\d{5}(?:[-\\s]\\d{4})?$"
      type: string
      description: The destination ZIP code for the package.
    postalCode:
      maxLength: 11
      type: string
      description: This is the Postal Code used in an international addresses.
    ShippingOptionsPackageDescription:
      title: Package Description
      type: object
      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."
      additionalProperties: true
      description: Package Definitions
    MailingDate:
      type: string
      description: "The date package will be mailed. The mailing date may be today plus 0 to 7 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 7 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
    DomesticMailClass:
      type: string
      description: "USPS mail classes. \nThe domestic mail service requested.\n * 'PARCEL_SELECT'\n * 'PARCEL_SELECT_LIGHTWEIGHT'\n * 'USPS_CONNECT_LOCAL'\n * 'USPS_CONNECT_REGIONAL'\n * 'USPS_CONNECT_MAIL'\n * 'USPS_GROUND_ADVANTAGE'\n * 'PRIORITY_MAIL_EXPRESS'\n * 'PRIORITY_MAIL'\n * 'LIBRARY_MAIL'\n * 'MEDIA_MAIL'\n * 'BOUND_PRINTED_MATTER'\n"
      enum:
        - PARCEL_SELECT
        - USPS_CONNECT_LOCAL
        - USPS_CONNECT_REGIONAL
        - USPS_CONNECT_MAIL
        - USPS_GROUND_ADVANTAGE
        - PRIORITY_MAIL_EXPRESS
        - PRIORITY_MAIL
        - LIBRARY_MAIL
        - MEDIA_MAIL
        - BOUND_PRINTED_MATTER
      example: PARCEL_SELECT
    InternationalMailClass:
      type: string
      description: |
        International Mail classes for label
        The mail service requested.
        * `FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE`
        * `PRIORITY_MAIL_INTERNATIONAL`
        * `PRIORITY_MAIL_EXPRESS_INTERNATIONAL`
        * `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
      example: PRIORITY_MAIL_INTERNATIONAL
    PriceType:
      type: string
      description: |-
        The type of price applied.
         * Valid Options for Domestic Prices include: 'RETAIL', 'COMMERCIAL', & 'CONTRACT'
         * Valid Options for International Prices include: 'RETAIL', 'COMMERCIAL', 'COMMERCIAL_BASE', 'COMMERCIAL_PLUS', & 'CONTRACT'
      enum:
        - RETAIL
        - COMMERCIAL
        - COMMERCIAL_BASE
        - COMMERCIAL_PLUS
        - CONTRACT
      example: "COMMERCIAL"
  examples:
    DomesticOptionsExample:
      summary: Domestic Options Response
      description: Example response for a Domestic Options Request
      value:
        originZIPCode: "50311"
        destinationZIPCode: "60119"
        pricingOptions:
          - shippingOptions:
              - mailClass: PARCEL_SELECT
                rateOptions:
                  - commitment:
                      name: 2 Days
                      scheduleDeliveryDate: "2024-10-04"
                      guaranteedDelivery: false
                    totalBasePrice: 9.17
                    rates:
                      - description: Parcel Select Nonstandard DNDC Single-piece
                        startDate: "2024-07-14"
                        endDate: "2024-10-05"
                        price: 6.17
                        zone: "00"
                        weight: 1.0
                        dimensionalWeight: 0.0
                        dimWeight: 0.0
                        fees:
                          - name: Nonstandard Length > 22
                            price: 3.00
                            SKU: D811XVCXXXX0000
                        priceType: COMMERCIAL
                        mailClass: PARCEL_SELECT
                        productName: ""
                        productDefinition: ""
                        processingCategory: "NONSTANDARD"
                        rateIndicator: "SP"
                        destinationEntryFacilityType: "DESTINATION_NETWORK_DISTRIBUTION_CENTER"
                        SKU: DVXP0XXCXC00010
                    extraServices:
                      - name: Return Receipt Electronic
                        price: 2.62
                        extraService: "957"
                        priceType: COMMERCIAL
                        warnings:
                          - warningCode: "001"
                            warningDescription: "Contract rate not found for request. Published rate returned."
                        SKU: DXRX0EXXXCX0000
            priceType: COMMERCIAL
            paymentAccount:
              accountType: EPS
              accountNumber: "12345767890"
    InternationalOptionsExample:
      summary: International Options Response
      description: Example response for an International Options Request
      value:
        originZIPCode: "22407"
        foreignPostalCode: "63118"
        destinationCountryCode: CA
        pricingOptions:
          - shippingOptions:
              - mailClass: PRIORITY_MAIL_EXPRESS_INTERNATIONAL
                rateOptions:
                  - totalBasePrice: 65.64
                    rates:
                      - description: Priority Mail Express International ISC Single-piece
                        startDate: "2024-07-14"
                        endDate: "2024-10-05"
                        price: 65.64
                        zone: "01"
                        weight: 1.2
                        dimensionalWeight: 0.0
                        dimWeight: 0.0
                        fees: []
                        priceType: COMMERCIAL_BASE
                        mailClass: PRIORITY_MAIL_EXPRESS_INTERNATIONAL
                        productName: ""
                        productDefinition: ""
                        processingCategory: "FLATS"
                        rateIndicator: "PA"
                        destinationEntryFacilityType: "INTERNATIONAL_SERVICE_CENTER"
                        SKU: IEXX0XXXXB01020
                    extraServices:
                      - name: Insurance <= $500
                        price: 20.15
                        extraService: "930"
                        priceType: COMMERCIAL
                        warnings:
                          - warningCode: "001"
                            warningDescription: Contract rate not found for request. Published rate returned.
                        SKU: IXIE0XXXXCX0500
            priceType: COMMERCIAL
            paymentAccount:
              accountType: METER
              accountNumber: "123456789"

  headers:
    WWWAuthenticate:
      description: Hint to the client application which security scheme to authorize a resource request.
      required: false
      schema:
        type: string
        example: "WWW-Authenticate: Bearer realm=\"https://api.usps.com\""
    RetryAfter:
      description: Indicate to the client application a time after which they can retry a resource request.
      required: false
      schema:
        type: string
        example: "Retry-After: 30"
  securitySchemes:
    OAuth:
      type: oauth2
      description: The specified APIs accept an access token formatted as a JSON Web Token. The relative path to the OAuth2 version 3 API which supplies this access token is provided below for reference.
      flows:
        clientCredentials:
          tokenUrl: /oauth2/v3/token
          scopes:
            shipments: Read access to Shipping Options API.
