United States Postal Service Domestic Prices API

openapi: 3.1.0
info:
  title: USPS Addresses Domestic Prices API
  description: The USPS Addresses API validates and corrects address information, eliminating errors, improving package delivery service and package pricing. Supports address standardization, city and state lookup, and ZIP Code validation.
  version: '3.0'
  contact:
    name: USPS API Support
    url: https://developers.usps.com/
    email: https://emailus.usps.com/s/web-tools-inquiry
  x-generated-from: documentation
servers:
- url: https://apis.usps.com
  description: Production
- url: https://apis-tem.usps.com
  description: Testing Environment for Mailers (TEM)
security:
- bearerAuth: []
tags:
- name: Domestic Prices
  description: Domestic postage pricing and rate calculation operations
paths:
  /prices/v3/base-rates/search:
    post:
      operationId: searchBaseRates
      summary: USPS Domestic Prices Search Base Rates
      description: Returns base postage rates for domestic shipments based on origin and destination ZIP Codes, weight, dimensions, and mail class.
      tags:
      - Domestic Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRateRequest'
            examples:
              SearchBaseRatesRequestExample:
                summary: Default searchBaseRates request
                x-microcks-default: true
                value:
                  originZIPCode: '20212'
                  destinationZIPCode: '90210'
                  weight: 1.5
                  length: 12.0
                  width: 8.0
                  height: 4.0
                  mailClass: PRIORITY_MAIL
                  processingCategory: MACHINABLE
                  destinationEntryFacilityType: NONE
                  rateIndicator: DR
      responses:
        '200':
          description: Base rates returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
              examples:
                SearchBaseRates200Example:
                  summary: Default searchBaseRates 200 response
                  x-microcks-default: true
                  value:
                    rates:
                    - skuCode: DPXX0XXXXB00020
                      description: Priority Mail
                      price: 8.7
                      maxWeight: 70
                      fees: []
        '400':
          description: Bad request - invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /prices/v3/extra-service-rates/search:
    post:
      operationId: searchExtraServiceRates
      summary: USPS Domestic Prices Search Extra Service Rates
      description: Returns rates for additional USPS services such as insurance, signature confirmation, certified mail, and other extra services.
      tags:
      - Domestic Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtraServiceRateRequest'
            examples:
              SearchExtraServiceRatesRequestExample:
                summary: Default searchExtraServiceRates request
                x-microcks-default: true
                value:
                  originZIPCode: '20212'
                  destinationZIPCode: '90210'
                  extraServiceCode: '955'
                  mailClass: PRIORITY_MAIL
                  weight: 1.5
      responses:
        '200':
          description: Extra service rates returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtraServiceRateResponse'
              examples:
                SearchExtraServiceRates200Example:
                  summary: Default searchExtraServiceRates 200 response
                  x-microcks-default: true
                  value:
                    extraServices:
                    - extraServiceCode: '955'
                      name: Signature Confirmation
                      price: 3.8
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /prices/v3/total-rates/search:
    post:
      operationId: searchTotalRates
      summary: USPS Domestic Prices Search Total Rates
      description: Returns total postage rates including base rate plus any extra service fees for domestic shipments. Provides a single total price for the complete shipping configuration.
      tags:
      - Domestic Prices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalRateRequest'
            examples:
              SearchTotalRatesRequestExample:
                summary: Default searchTotalRates request
                x-microcks-default: true
                value:
                  originZIPCode: '20212'
                  destinationZIPCode: '90210'
                  weight: 1.5
                  length: 12.0
                  width: 8.0
                  height: 4.0
                  mailClass: PRIORITY_MAIL
                  extraServices:
                  - extraServiceCode: '955'
      responses:
        '200':
          description: Total rates returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotalRateResponse'
              examples:
                SearchTotalRates200Example:
                  summary: Default searchTotalRates 200 response
                  x-microcks-default: true
                  value:
                    rates:
                    - totalBasePrice: 8.7
                      totalPrice: 12.5
                      fees:
                      - name: Signature Confirmation
                        price: 3.8
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RateResponse:
      type: object
      description: Base rate search response.
      properties:
        rates:
          type: array
          description: List of available rates for the requested criteria.
          items:
            type: object
            properties:
              skuCode:
                type: string
                description: USPS SKU code for the rate.
                example: DPXX0XXXXB00020
              description:
                type: string
                description: Human-readable rate description.
                example: Priority Mail
              price:
                type: number
                description: Rate price in USD.
                example: 8.7
              maxWeight:
                type: number
                description: Maximum weight in pounds for this rate.
                example: 70
              fees:
                type: array
                description: Additional fees included in this rate.
                items:
                  type: object
    BaseRateRequest:
      type: object
      required:
      - originZIPCode
      - destinationZIPCode
      - weight
      - mailClass
      description: Request parameters for base rate search.
      properties:
        originZIPCode:
          type: string
          description: 5-digit origin ZIP Code.
          example: '20212'
        destinationZIPCode:
          type: string
          description: 5-digit destination ZIP Code.
          example: '90210'
        weight:
          type: number
          description: Package weight in pounds.
          example: 1.5
        length:
          type: number
          description: Package length in inches.
          example: 12.0
        width:
          type: number
          description: Package width in inches.
          example: 8.0
        height:
          type: number
          description: Package height in inches.
          example: 4.0
        mailClass:
          type: string
          description: USPS mail class for the shipment.
          enum:
          - PRIORITY_MAIL
          - PRIORITY_MAIL_EXPRESS
          - FIRST_CLASS_PACKAGE_SERVICE
          - PARCEL_SELECT
          - MEDIA_MAIL
          - LIBRARY_MAIL
          - BOUND_PRINTED_MATTER
          example: PRIORITY_MAIL
        processingCategory:
          type: string
          description: Processing category for the package.
          enum:
          - MACHINABLE
          - NON_MACHINABLE
          - IRREGULAR
          - LETTERS
          - FLATS
          example: MACHINABLE
        destinationEntryFacilityType:
          type: string
          description: Type of destination entry facility.
          enum:
          - NONE
          - DESTINATION_DELIVERY_UNIT
          - DESTINATION_SERVICE_FACILITY
          - DESTINATION_SECTIONAL_CENTER_FACILITY
          - DESTINATION_BULK_MAIL_CENTER
          example: NONE
        rateIndicator:
          type: string
          description: Rate indicator code for special rate categories.
          example: DR
    Error:
      type: object
      description: API error response.
      properties:
        apiVersion:
          type: string
          example: '3.0'
        error:
          type: object
          properties:
            code:
              type: string
              example: PRICE_ERR_001
            message:
              type: string
              example: Invalid mail class
    TotalRateRequest:
      type: object
      required:
      - originZIPCode
      - destinationZIPCode
      - weight
      - mailClass
      description: Request parameters for total rate search.
      properties:
        originZIPCode:
          type: string
          description: 5-digit origin ZIP Code.
          example: '20212'
        destinationZIPCode:
          type: string
          description: 5-digit destination ZIP Code.
          example: '90210'
        weight:
          type: number
          description: Package weight in pounds.
          example: 1.5
        length:
          type: number
          description: Package length in inches.
          example: 12.0
        width:
          type: number
          description: Package width in inches.
          example: 8.0
        height:
          type: number
          description: Package height in inches.
          example: 4.0
        mailClass:
          type: string
          description: USPS mail class.
          example: PRIORITY_MAIL
        extraServices:
          type: array
          description: List of extra services to include in total rate.
          items:
            type: object
            properties:
              extraServiceCode:
                type: string
                description: Extra service code.
                example: '955'
    TotalRateResponse:
      type: object
      description: Total rate response including base and extra service rates.
      properties:
        rates:
          type: array
          description: List of total rates.
          items:
            type: object
            properties:
              totalBasePrice:
                type: number
                description: Base postage price in USD.
                example: 8.7
              totalPrice:
                type: number
                description: Total price including all fees in USD.
                example: 12.5
              fees:
                type: array
                description: Breakdown of additional fees.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Fee name.
                      example: Signature Confirmation
                    price:
                      type: number
                      description: Fee amount in USD.
                      example: 3.8
    ExtraServiceRateRequest:
      type: object
      required:
      - extraServiceCode
      - mailClass
      description: Request parameters for extra service rate search.
      properties:
        originZIPCode:
          type: string
          description: 5-digit origin ZIP Code.
          example: '20212'
        destinationZIPCode:
          type: string
          description: 5-digit destination ZIP Code.
          example: '90210'
        extraServiceCode:
          type: string
          description: Code identifying the extra service.
          example: '955'
        mailClass:
          type: string
          description: USPS mail class.
          example: PRIORITY_MAIL
        weight:
          type: number
          description: Package weight in pounds.
          example: 1.5
    ExtraServiceRateResponse:
      type: object
      description: Extra service rate response.
      properties:
        extraServices:
          type: array
          description: List of extra service rates.
          items:
            type: object
            properties:
              extraServiceCode:
                type: string
                description: Extra service code.
                example: '955'
              name:
                type: string
                description: Name of the extra service.
                example: Signature Confirmation
              price:
                type: number
                description: Price for the extra service in USD.
                example: 3.8
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer Token obtained from the USPS OAuth API.
externalDocs:
  description: USPS Addresses API Documentation
  url: https://developers.usps.com/addressesv3