openapi: 3.0.0
info:
  title: Containers
  description: |
    Contact Us: [USPS API Support](https://emailus.usps.com/s/web-tools-inquiry) | [Terms of Service](https://about.usps.com/termsofuse.htm)
    
    The Intelligent Mail Container barcode (IMcb) provides visibility at the mail aggregate level. It is used on mailer-generated pallet labels to uniquely identify pallets and similar containers (i.e. All Purpose Containers, hampers, pallet boxes, etc.) in addition to identifying the mail owner and, it provides a link between the electronic mailing record and the physical mail aggregate.

    The IMcb uniquely identifies the mail owner, mail preparer, or consolidator by way of the Mailer ID field. Furthermore, the IMcb establishes a unique "serial number" for each container. These two features allow each container to be associated with a unique mailing and facilitate tracking of containers as they are loaded and unloaded from transportation.

    The IMcb is printed on Mailer-generated pallet labels and is designed to be scanned at acceptance and at other points throughout the transportation and processing network. Other human-readable data elements, beyond the IM Container barcode, such as text identifying the mail owner, destination, and type of mail are also required on the container placard. Further information on the use of this barcode can be found in the Mailing Standards of the United States Postal Service®, Domestic Mail Manual (DMM 300).

    Priority Mail Open and Distribute (PMOD) and Priority Mail Express Open and Distribute (PMEOD) labels and containers can be created with [Open and Distribute 3.0 - Create an Open and Distribute container](https://developers.usps.com/pmodv3#tag/Resources/operation/post-pmod).

  version: 3.1.8
servers:
  - url: https://apis.usps.com/containers/v3
    description: Production Environment Endpoint
  - url: https://apis-tem.usps.com/containers/v3
    description: Testing Environment Endpoint
security:
  - OAuth:
      - containers
paths:
  /containers/{container-id}/packages:
    post:
      tags:
        - Resources
      summary: Add packages or mail to a container manifest.
      description: |
        This endpoint allows the caller to add additional items to an already created container.  This endpoint can also be used to add items to Open and Distribute containers created through [Open and Distribute 3.0 - Create an Open and Distribute container](https://developers.usps.com/pmodv3#tag/Resources/operation/post-pmod).
      operationId: post-containers-with-container-id
      parameters:
        - name: container-id
          in: path
          description: Container id for the container
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/containerid_packages_body'
          application/xml:
            schema:
              $ref: '#/components/schemas/containerid_packages_body'
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
            application/xml:
              schema:
                $ref: '#/components/schemas/Container'
        "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 the 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: {}
    delete:
      tags:
        - Resources
      summary: Remove all packages from a container.
      description: |
        In the context of container tracking, deleting all tracking numbers from a container results in an empty container, which allows for the addition of new tracking numbers. This process effectively clears out any previous tracking information associated with the container, allowing for a fresh start.
      operationId: delete-containers-with-container-id
      parameters:
        - name: container-id
          in: path
          description: Container id for the container
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "204":
          description: Successful Response
        "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
            the 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: {}
  /containers/{container-id}/packages/{tracking-number}:
    delete:
      tags:
        - Resources
      summary: Remove individual packages from a container.
      description: "In the context of container tracking, deleting one tracking number from a container."
      operationId: delete-containers-with-container-id-with-packages
      parameters:
        - name: container-id
          in: path
          description: Container id for the container.
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: tracking-number
          in: path
          description: tracking number for the package.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "204":
          description: Successful Response
        "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
            the 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: {}
  /containers:
    post:
      tags:
        - Resources
      summary: Create a container label
      description: "Allows the caller to get a container label and associate packages to that container. \n"
      operationId: post-containers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Container'
          application/xml:
            schema:
              $ref: '#/components/schemas/Container'
      responses:
        "201":
          description: Resource created
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/Container'
              encoding:
                containerMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"labelMetadata\""
                  style: form
                labelImage:
                  contentType: "application/octet-stream, application/pdf, image/jpg, image/png, image/gif, image/tiff, image/svg+xml"
                  headers:
                    Content-Disposition:
                      description: Additional information on how the client should handle the content.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-image.jpg\""
                  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 the 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: {}
  /containers/manifest:
    post:
      tags:
        - Resources
      summary: Closes a container
      description: "Allows the caller to close a container and generate a manifest. \n"
      operationId: post-manifest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Manifest'
          application/xml:
            schema:
              $ref: '#/components/schemas/Manifest'
      responses:
        "204":
          description: Manifest successfully created.
        "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 the 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: {}
components:
  schemas:
    ImageInfo:
      title: Image Info
      type: object
      properties:
        imageType:
          type: string
          description: |
            The type of label image requested.  If omitted then the default image type is PDF.
            
            Note:
            - When using `ZPL203DPI` or `ZPL300DPI` the image returned will be rotated 90 degrees and be 4x6 inches, instead of 6x4 inches.
          default: PDF
          enum:
            - PDF
            - TIFF
            - JPG
            - PNG
            - GIF
            - SVG
            - ZPL203DPI
            - ZPL300DPI
            - NONE
        labelType:
          type: string
          description: |-
            Ability to select the label image size.  If omitted then the default label size is 6X4LABEL.
             * '6X4LABEL'
          default: 6X4LABEL
          enum:
            - 6X4LABEL
        addZPLComments:
          type: boolean
          default: false
          description: |
            Applicable only when `imageType` is `ZPL203DPI` or `ZPL300DPI`.  When `addZPLComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label.  When `addZPLComments` is `false`, no comments will be included in the ZPL text response.  This will be ignored for any other `imageType`.

            Example of a ZPL comment: 
            `^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`

     
      additionalProperties: false
      description: Additional details used to determine how to generate the label image.
      writeOnly: true
    Manifest:
      required:
        - containers
      type: object
      properties:
        mailingDate:
          $ref: '#/components/schemas/MailingDateOptions'
        containers:
          type: array
          minItems: 1
          items:
            type: string
            nullable: false
    Container:
      title: Container
      required:
        - MID
        - destinationEntryFacilityType
        - destinationZIPCode
        - mailClass
        - mailerName
        - originAddress
        - processingCategory
        - sortType
      type: object
      properties:
        containerID:
          maxLength: 34
          type: string
          description: Unique identifier for a container
          readOnly: true
        imageInfo:
          $ref: '#/components/schemas/ImageInfo'
        sortType:
          type: string
          description: The sort type of the container being shipped.
          enum:
            - TRUCK_BEDLOAD
            - PALLET
            - SACK
        trackingNumbers:
          minItems: 1
          type: array
          description: List of tracking numbers for the packages that are in the container.
          writeOnly: true
          items:
            type: string
        destinationEntryFacilityType:
          type: string
          description: The facility type where the container will be sent to.
          enum:
            - DESTINATION_NETWORK_DISTRIBUTION_CENTER
            - DESTINATION_SECTIONAL_CENTER_FACILITY
            - DESTINATION_DELIVERY_UNIT
            - DESTINATION_SERVICE_HUB
        destinationZIPCode:
          maxLength: 5
          minLength: 5
          pattern: "\\d{5}"
          type: string
          description: A 5-digit ZIP Code serviced by the `destinationEntryFacilityType` the container is being sent to.  This is used to identify the Destination Entry Facility.
        mailClass:
          type: string
          description: The mail class of the items enclosed in the container. The default value is `PARCEL_SELECT` 
          enum:
            - PARCEL_SELECT
        originAddress:
          required:
            - ZIPCode
            - city
            - state
            - streetAddress
          allOf:
            - $ref: '#/components/schemas/DomesticAddress'
        mailerName:
          type: string
          description: "Name of the firm/business that is shipping the container."
        processingCategory:
          type: string
          description: |-
            The type of packages that will be nested to the container. `MIXED` is only available for `DESTINATION_DELIVERY_UNIT` and `DESTINATION_SERVICE_HUB` containers.
            
            Note:
            * `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.
          enum:
            - MACHINABLE
            - MIXED
            - NON_MACHINABLE
            - NONSTANDARD
        containerTopology:
          type: string
          default: NESTED
          enum:
            - NESTED
        MID:
          pattern: "^(\\d{6}|\\d{9})$"
          type: string
          description: Mailer Identifier to use to create the container barcode.
        warnings:
          type: array
          readOnly: true
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Container_warnings'
        mailingDate:
          $ref: '#/components/schemas/MailingDateOptions'
      additionalProperties: false
      description: containers
    ErrorMessage:
      title: Error
      type: object
      properties:
        apiVersion:
          type: string
          description: The version of the API that was used and that raised the error.
        error:
          $ref: '#/components/schemas/ErrorMessage_error'
      additionalProperties: true
      description: Standard error message response.
    MailingDateOptions:
      description: |
        The mailing date for when the container will be shipped, when
        included in the request all packages nested to the container will be
        updated to align with the associated mailingDate. The mailing date may
        be today plus 0 to 7 days in advance. If it is not provided it will
        be set as today.
      type: string
      oneOf:
        - $ref: '#/components/schemas/MailingDate'
        - $ref: '#/components/schemas/MailingDateTime'
    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
    DomesticAddress:
      title: Domestic Address
      additionalProperties: true
      description: The address of the Business Mail Entry Unit (BMEU) or authorized acceptance location facility where the container is being entered.
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            city:
              maxLength: 28
              minLength: 1
              type: string
              description: This is the city name of the address.
            state:
              maxLength: 2
              minLength: 2
              pattern: ^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$
              type: string
              description: This is two-character state code of the address.
            ZIPCode:
              pattern: "\\d{5}"
              type: string
              description: This is the 5-digit ZIP code.
            ZIPPlus4:
              pattern: "\\d{4}"
              type: string
              description: This is the ZIP+4 extension.
              nullable: true
            urbanization:
              maxLength: 96
              type: string
              description: "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)"
          additionalProperties: true
    Address:
      title: Address
      type: object
      properties:
        streetAddress:
          maxLength: 50
          minLength: 1
          type: string
          description: The number of a building along with the name of the road or street on which it is located.
        streetAddressAbbreviation:
          maxLength: 50
          minLength: 0
          type: string
          description: This is the abbreviation of the street address line for the address.
          readOnly: true
        secondaryAddress:
          maxLength: 50
          type: string
          description: "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
        cityAbbreviation:
          type: string
          description: This is the abbreviation of the city name for the address.
          readOnly: true
      additionalProperties: true
      description: Address fields standard to all locations.
      xml:
        name: Address
    containerid_packages_body:
      type: object
      properties:
        trackingNumbers:
          type: array
          description: List of tracking numbers for the packages that are in the container.
          items:
            type: string
    Container_warnings:
      type: object
      properties:
        warningCode:
          type: string
        warningDescription:
          type: string
      xml:
        name: warning
    ErrorMessage_error_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.
    ErrorMessage_error_errors:
      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:
          $ref: '#/components/schemas/ErrorMessage_error_source'
      additionalProperties: true
    ErrorMessage_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:
            $ref: '#/components/schemas/ErrorMessage_error_errors'
      additionalProperties: true
      description: The high-level error that has occurred as indicated by the status
        code.
  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:
            containers: Both read and create access to containers API.
