United States Postal Service Domestic Prices API

openapi: 3.2.0
info:
  title: USPS Domestic Prices API
  description: The USPS Domestic Prices API provides postage pricing based on origin and destination ZIP Codes, weight, dimensions, and mail class. Supports base rate lookups, extra service rates, and total rate calculations.
  version: '3.0'
  contact:
    name: USPS API Support
    url: https://developers.usps.com/
  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:
    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
    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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer Token.
externalDocs:
  description: USPS Domestic Prices API Documentation
  url: https://developers.usps.com/domesticpricesv3