openapi: 3.0.0
info:
  title: Labels
  description: |
    Contact Us: [USPS API Support](https://emailus.usps.com/s/usps-APIs) | [Terms of Service](https://about.usps.com/termsofuse.htm)
    
    The USPS&#174; Labels API allows you to digitally create mailing labels for the following mail classes: USPS Ground Advantage&#8482;, Parcel Select&#174; Destination Entry, Parcel Select Lightweight&#174;, USPS Connect&#174; Local, USPS Connect&#174; Regional, Priority 
    Mail&#174;, Priority Mail Express&#174;, Bound Printed Matter, Library Mail, and Media Mail&#174;.
    
    * Use the [Getting Started guide](https://developers.usps.com/getting-started) to get started with the Labels API.
    * The USPS&#174; Labels API uses a token to authorize the use of an [Enterprise Payment](https://postalpro.usps.com/EPS) or Permit account. The specification to generate the token is in the [Payments 3.0 - Set Payment Account Information](https://developers.usps.com/paymentsv3#tag/Resources/operation/post-payments-payment-authorization).
    
    **Manifest Scheduling** 
    
    The following table outlines the Domestic Label manifesting schedule for specific conditions listed below. 
    
    | Condition                   | Scheduling |
    | ----------------------------| -------- |
    | **Return labels**    | 12:30am CT on the day after label creation. |
    | **Smart Locker labels**     | Electronic data is sent to Postal systems within 15 minutes of label creation. |
    | **Value of `true` provided for `immediateManifest` field**| Electronic data is sent to Postal systems within 15 minutes of label creation.  |
    | **Label is added to a [SCAN Form](https://developers.usps.com/scanv3#tag/Resources/operation/post-scan-form)**| Electronic data is sent to Postal systems within 15 minutes of SCAN Form creation.  |
    | **All other conditions**    | 12:30am CT after the `mailingDate` value provided by the user |
  version: 3.9.14
servers:
  - url: https://apis.usps.com/labels/v3
    description: Production Environment Endpoint
  - url: https://apis-tem.usps.com/labels/v3
    description: Testing Environment Endpoint
paths:
  /label:
    post:
      tags:
        - Resources
      summary: Create a domestic shipping label.
      description: |
        Generates a shipping label based upon the following:
        
        | Element                       | Description |
        | ----------------------------- | --------|
        | **toAddress**                 | Address where the package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing. |
        | **fromAddress**               | Address where the package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing. |
        | **senderAddress**             | Address of the business involved. The `senderAddress` can be different from the `fromAddress` when the business address is not where the package is being shipped from. |
        | **returnAddress**             | Address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label. |
        | **packageDescription**        | Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more. |
        | **imageInfo**                 | Additional details used to determine how to generate the label image. |
        | **customsForm**               | Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S., Possessions, Territories, and Freely Associated States (PTFAS).|
        
        The default media type of the response has multiple parts. Setting the Accept header to either application/json or application/xml will only affect the metadata part of the multipart response.
        
        **How to use this API**
        
        The metadata part of the multipart response representation is only in application/json format media type, as default. The application/xml media type is not supported at this time.
        
        Ignore the Content-Encoding header in the second part, the label image file. The contents of this part are not compressed.
        
        Ignore the Content-Transfer-Encoding header in the second part, the label image file. The contents of this part are always Base64 encoded.
        
        Ignore the Content-Encoding header in the third part, the receipt image file. The contents of this part are not compressed.
        
        Ignore the Content-Transfer-Encoding header in the third part, the receipt image file. The contents of this part are always Base64 encoded.
        
        **Instructions**
        
        Extract the first part of the multipart response as application/json media type.
        
        Extract the second part of the multipart response and Base64 decode it to yield the binary image file.
        
        Save the binary image file, given the Content-Type header value and the filename of this part (e.g. application/pdf, label.pdf). It is recommended that you run a virus scan on the resulting downloaded file.
        
        Extract the third part of the multipart response and Base64 decode it to yield the binary image file.
        
        Save the binary image file, given the Content-Type header value and the filename of this part (e.g. application/pdf, receipt.pdf). It is recommended that you run a virus scan on the resulting downloaded file.
      operationId: post-label
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
        - $ref: "#/components/parameters/X-Idempotency-Key"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelRequest'
            examples:
              GroundAdvantageRequest:
                $ref: '#/components/examples/GroundAdvantageRequest'
              GroundAdvantageRequestWithImageInfo:
                $ref: '#/components/examples/GroundAdvantageRequestWithImageInfo'
              HoldForPickupRequest:
                $ref: '#/components/examples/HoldForPickupRequest'
              PMECrematedRemainsRequest:
                $ref: '#/components/examples/PMECrematedRemainsRequest'
              CustomsFormRequest:
                $ref: '#/components/examples/CustomsFormRequest'
              SmartLockerRequest:
                $ref: '#/components/examples/SmartLockerRequest'
              LabelBrokerRequest:
                $ref: '#/components/examples/LabelBrokerRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/LabelRequest'
        required: true
      responses:
        "200":
          description: Successful operation.
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/LabelMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                receiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  style: form
                examples:
                  style: form
            application/vnd.usps.labels+json:
              schema:
                $ref: '#/components/schemas/LabelVendorResponse'
              examples:
                Base64EncodedImagesExample:
                  $ref: '#/components/examples/Base64EncodedImagesExample'
            application/vnd.usps.labels+xml:
              schema:
                $ref: '#/components/schemas/LabelVendorResponse'
              examples:
                Base64EncodedImagesXMLExample:
                  $ref: '#/components/examples/Base64EncodedImagesXMLExample'
            application/json:
              schema:
                $ref: '#/components/schemas/LabelMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                receiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  style: form
                examples:
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelMultiPartResponse'
              encoding:
                labelMetadata:
                  contentType: application/xml
                  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
                returnLabelMetadata:
                  contentType: application/xml
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                receiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  style: form
                examples:
                  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: { }
      security:
        - OAuth:
            - labels
    delete:
      tags:
        - Resources
      summary: Cancel a previously requested label or request a refund on label by providing the X-Idempotency-Key header
      description: |
        Cancel a label or submit a refund request by providing the X-Idempotency-Key header used to create the label.
        
        A label can be canceled if a Shipping Services File has not been created. If a Shipping Services File has been created, submit a refund request for an unused label.  A label is eligible for a refund if:
        - If the label has had a Shipping Services File created for it
        - The label is not from Click-N-Ship or PC Postage
        - Is a SCAN Form label that has had its Shipping Services File created
        
        Note:
        - If the label is canceled, a Shipping Services File will not be created.
        - If a refund request is successfully submitted, a disputeId will be returned that can be used to then track the status of the refund request. The system will only give one unique disputeId per customer reference ID (CRID) per day. Duplicate submissions of the same label, for the same CRID, on the same day, will be rejected.
      operationId: delete-label-by-idempotency
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
        - $ref: "#/components/parameters/X-Idempotency-Key"
      responses:
        "200":
          description: Successful Operation
          headers:
            X-Idempotency-Key:
              description: The idempotency key associated with the original label creation request.
              schema:
                type: string
                format: uuid
              example: 8be4df61-93ca-11d2-aa0d-00e098032b8c
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
              examples:
                Label Canceled:
                  $ref: '#/components/examples/ExampleCancel_CANCELED'
                Refund Submitted:
                  $ref: '#/components/examples/ExampleCancel_REFUND'
            application/xml:
              schema:
                $ref: '#/components/schemas/CancelResponse'
              examples:
                Label Canceled:
                  $ref: '#/components/examples/ExampleCancel_CANCELED'
                Refund Submitted:
                  $ref: '#/components/examples/ExampleCancel_REFUND'
        "400":
          description: Bad Request.  There is an error in the received request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Not Found Error:
                  $ref: '#/components/examples/ExampleCancelError_NOTFOUND'
                Refund Not Submitted:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_NOT_SUBMITTED'
                Refund Same Label Same Day:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_SAMELABEL_SAMEDAY'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Not Found Error:
                  $ref: '#/components/examples/ExampleCancelError_NOTFOUND'
                Refund Not Submitted:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_NOT_SUBMITTED'
                Refund Same Label Same Day:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_SAMELABEL_SAMEDAY'
        "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: { }
      security:
        - OAuth:
            - labels
  /return-label:
    post:
      tags:
        - Resources
      summary: Create a domestic returns shipping label.
      description: |
        Generates a returns shipping label based upon the input dimensions requested.

        | Element                        | Description |
        | ------------------------------ | -------- |
        | **toAddress**                  | Address where the return package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing. |
        | **fromAddress**                | Address where the return package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing. |
        | **senderAddress**              | Address of the business involved (typically the sender of the original package). The `senderAddress` can be different from the `toAddress` when the business address is not where the package is being shipped to.   |
        | **returnAddress**              | Address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label. This could be a secondary return address in case the `toAddress` is deemed undeliverable or returned to sender.   |
        | **packageDescription**         | Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more. |
        | **imageInfo**                  | Additional details used to update label characteristics |
        | **customsForm**                | Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).|


        The default media type of the response has multiple parts. Setting the Accept header to either 
        `application/json` or `application/xml` will only affect the metadata part of the multipart response.

        **How to use this API**
        
        The metadata part of the multipart response representation is only in application/json 
        format media type, as default. 

        Ignore the Content-Encoding header in the second part, the label image file. The contents of this part are not compressed.


        Ignore the Content-Transfer-Encoding header in the second part, the label image file. The contents of this part are always Base64 encoded.


        Ignore the Content-Encoding header in the third part, the receipt image file. The contents of this part are not compressed.


        Ignore the Content-Transfer-Encoding header in the third part, the receipt image file. The contents of this part are always Base64 encoded.

        **Instructions**

        Extract the first part of the multipart response as application/json media type.

        Extract the second part of the multipart response and Base64 decode it to yield the binary image file.

        Save the binary image file, given the Content-Type header value and the filename of this part (e.g. application/pdf, label.pdf). It is recommended that you run a virus scan on the resulting downloaded file.

        Extract the third part of the multipart response and Base64 decode it to yield the binary image file.
        
        Save the binary image file, given the Content-Type header value and the filename of this part (e.g. application/pdf, receipt.pdf). It is recommended that you run a virus scan on the resulting downloaded file.

      operationId: post-return-label
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
        - $ref: "#/components/parameters/X-Idempotency-Key"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnLabelRequest'
            examples:
              GroundAdvantageReturnLabelRequest:
                $ref: '#/components/examples/GroundAdvantageReturnLabelRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/ReturnLabelRequest'
        required: true
      responses:
        "200":
          description: Success
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/ReturnLabelMultiPartResponse'
              encoding:
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  style: form
            application/vnd.usps.labels+json:
              schema:
                $ref: '#/components/schemas/ReturnLabelVendorResponse'
              examples:
                JSONReturnLabelWithEmbeddedBased64Response:
                  $ref: '#/components/examples/JSONReturnLabelWithEmbeddedBased64Response'
            application/vnd.usps.labels+xml:
              schema:
                $ref: '#/components/schemas/ReturnLabelVendorResponse'
              examples:
                XMLReturnLabelWithEmbeddedBased64Response:
                  $ref: '#/components/examples/XMLReturnLabelResponseWithEmbeddedBase64EncodedImages'
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnLabelMultiPartResponse'
              encoding:
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/ReturnLabelMultiPartResponse'
              encoding:
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                returnReceiptImage:
                  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=\"receipt-image.jpg\""
                  style: form
                labelBrokerQR:
                  contentType: "image/png"
                  headers:
                    Content-Disposition:
                      description: Label Broker QR Code image, returned if `imageType` of `LABEL_BROKER` was requested and `imageInfo.includeLabelBrokerPDF` is `true`.
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: attachment; filename=\"label-broker-qr.png\""
                  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: { }
      security:
        - OAuth:
            - labels
  /label/{trackingNumber}:
    delete:
      tags:
        - Resources
      summary: Cancel a previously requested label or request a refund on label by providing it's tracking number
      description: |
        Cancel a label or submit a refund request by providing the label's tracking number.
        
        A label can be canceled if a Shipping Services File has not been created. If a Shipping Services File has been created, submit a refund request for an unused label.  A label is eligible for a refund if:
        - If the label has had a Shipping Services File created for it
        - The label is not from Click-N-Ship or PC Postage
        - Is a SCAN Form label that has had its Shipping Services File created
        
        Note:
        - If the label is canceled, a Shipping Services File will not be created.
        - If a refund request is successfully submitted, a disputeId will be returned that can be used to then track the status of the refund request. The system will only give one unique disputeId per customer reference ID (CRID) per day. Duplicate submissions of the same label, for the same CRID, on the same day, will be rejected.
      operationId: delete-label-by-tracking
      parameters:
        - $ref: "#/components/parameters/TrackingNumber"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
              examples:
                Label Canceled:
                  $ref: '#/components/examples/ExampleCancel_CANCELED'
                Refund Submitted:
                  $ref: '#/components/examples/ExampleCancel_REFUND'
            application/xml:
              schema:
                $ref: '#/components/schemas/CancelResponse'
              examples:
                Label Canceled:
                  $ref: '#/components/examples/ExampleCancel_CANCELED'
                Refund Submitted:
                  $ref: '#/components/examples/ExampleCancel_REFUND'
        "400":
          description: Bad Request.  There is an error in the received request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Not Found Error:
                  $ref: '#/components/examples/ExampleCancelError_NOTFOUND'
                Refund Not Submitted:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_NOT_SUBMITTED'
                Refund Same Label Same Day:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_SAMELABEL_SAMEDAY'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Not Found Error:
                  $ref: '#/components/examples/ExampleCancelError_NOTFOUND'
                Refund Not Submitted:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_NOT_SUBMITTED'
                Refund Same Label Same Day:
                  $ref: '#/components/examples/ExampleCancelError_REFUND_SAMELABEL_SAMEDAY'
        "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: { }
      security:
        - OAuth:
            - labels
    patch:
      tags:
        - Resources
      summary: Edit label attributes.
      description: |
        Allow customers to edit package attributes for previously created labels including weight, dimensions, rate indicator, processing category and containers. These fields eligible for editing will not impact label images, so previous label images can still be used.

        Changing these rate ingredients may affect the prices of the label.
        Therefore, the Payment Authorization token is required.

        Note: Label edits will not be supported for the following scenarios; instead, unused label refunds should be requested and new labels should be created.
        * All label edits are disallowed if the original label was created with `suppressPostage = false`.
        * No dimensional updates are supported for Cubic Soft Pack labels.
        * Cubic labels cannot be edited to non-cubic rate indicators.
      operationId: patch-label-edit
      parameters:
        - $ref: "#/components/parameters/TrackingNumber"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              Labels Update:
                $ref: '#/components/examples/ExamplePatch'
              Labels Update3:
                $ref: '#/components/examples/ExamplePatch3'
          application/xml:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              Meters Update:
                $ref: '#/components/examples/ExamplePatch'
              Labels Update2:
                $ref: '#/components/examples/ExamplePatch3'
        required: true
      responses:
        "200":
          description: Success
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelMetadata'
              examples:
                Edit Weight Response:
                  $ref: '#/components/examples/EditResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelMetadata'
        "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: { }
      security:
        - OAuth:
            - labels
  /indicia:
    post:
      tags:
        - Resources
      summary: Create a First-Class letter, flat, or card indicia.
      description: |
        Generates a First-Class indicia for use on letter, flat, or card mailings.

        Notes:
        - Only supported for 'PAYER' Roles with an EPS accountType.
        - Indicia should be placed in the top right corner of letters, flats, and cards in order to avoid delays in processing.
        - An Indicia created using this endpoint is non-refundable and cannot be refunded using the DELETE /indicia/imb endpoint.
      operationId: post-label-indicia
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        description: Indicia request payload containing necessary data for generating a First-Class indicia.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndiciaRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/IndiciaRequest'
        required: true
      responses:
        "201":
          description: Success
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/IndiciaResponse'
              encoding:
                indiciaMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"indiciaMetadata\""
                  style: form
                indiciaImage:
                  contentType: "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=\"indicia-image.jpg\""
                  style: form
                receiptImage:
                  contentType: "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=\"receipt-image.jpg\""
                  style: form
                examples:
                  style: form
            application/json:
              schema:
                $ref: '#/components/schemas/IndiciaResponse'
              encoding:
                metadata:
                  contentType: application/json
                  style: form
                examples:
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/IndiciaResponse'
              encoding:
                metadata:
                  contentType: application/xml
                  style: form
                examples:
                  style: form
            application/vnd.usps.labels+json:
              schema:
                $ref: '#/components/schemas/IndiciaResponse'
              examples:
                IndiciaExampleResponse:
                  $ref: '#/components/examples/IndiciaExampleResponse'
            application/vnd.usps.labels+xml:
              schema:
                $ref: '#/components/schemas/IndiciaResponse'
        "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: { }
      security:
        - OAuth:
            - labels
  /indicia/imb:
    post:
      tags:
        - Resources
      summary: Create an Intelligent Mail Barcode (IMB) label for First-Class letters, flats, and cards.
      description: |
        Generates an Intelligent Mail Barcode (IMB) label for First-Class letters, flats, and cards. [See specification USPS-B-3200](https://postalpro.usps.com/node/2190).

        Notes:
        - Only supported for 'PAYER' Roles with an EPS accountType.
        - When IMB labels are placed on letters, flats, or cards that are larger than the label itself, the label should be placed in the top right corner in order to avoid delays in processing.
      operationId: post-indicia-imb
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndiciaImbRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/IndiciaImbRequest'
        required: true
      responses:
        "201":
          description: Success
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/IndiciaImbResponse'
              encoding:
                indiciaMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"indiciaMetadata\""
                  style: form
                indiciaImage:
                  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=\"indicia-imb-image.jpg\""
                  style: form
                receiptImage:
                  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=\"receipt-imb-image.jpg\""
                  style: form
                examples:
                  style: form
            application/json:
              schema:
                $ref: '#/components/schemas/IndiciaImbResponse'
              encoding:
                metadata:
                  contentType: application/json
                  style: form
                examples:
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/IndiciaImbResponse'
              encoding:
                metadata:
                  contentType: application/xml
                  style: form
                examples:
                  style: form
            application/vnd.usps.labels+json:
              schema:
                $ref: '#/components/schemas/IndiciaImbResponse'
              examples:
                IndiciaIMBExampleResponse:
                  $ref: '#/components/examples/IndiciaIMBExampleResponse'
            application/vnd.usps.labels+xml:
              schema:
                $ref: '#/components/schemas/IndiciaImbResponse'
        "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: { }
      security:
        - OAuth:
            - labels
  /indicia/imb/{imb}:
    delete:
      tags:
        - Resources
      summary: Cancel a previously requested Intelligent Mail Barcode (IMB) label for First-Class letters, flats, and cards.
      description: |
        Cancel an Intelligent Mail Barcode (IMB) label for First-Class letters, flats, and cards or submit a refund request by providing the IMB.

        An IMB can be canceled if it has not yet been manifested. If it has been manifested, a refund request will be submitted for the unused IMB.

        Indicia without an IMB cannot be canceled.
        
        Note:
        - You can only request a refund of an IMB once.
      operationId: delete-indicia-imb
      parameters:
        - $ref: "#/components/parameters/IMB"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      responses:
        "200":
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IMBCancelResponse'
              examples:
                Label Canceled:
                  $ref: '#/components/examples/ExampleIMBCancel_CANCELED'
                Refund Submitted:
                  $ref: '#/components/examples/ExampleIMBCancel_DISPUTED'
            application/xml:
              schema:
                $ref: '#/components/schemas/IMBCancelResponse'
        "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: { }
      security:
        - OAuth:
            - labels
  /branding:
    post:
      tags:
        - Resources
      summary: Upload an SVG image to be used as a label branding image.
      description: |
        The USPS Logo Branding endpoint allows you to upload your custom image or 
        logo to USPS APIs. A UUID is generated for your custom image to 
        leverage for outbound Domestic Labels and Return Labels requests. The 
        user will indicate how their custom image or multiple images will 
        display, and the option to specify the shape of their image when 
        generating labels and return labels.

        Note:
        * It may take up to 15 minutes for the label image to propagate to all regions for label usage.
        * There is a limit of 100 images to be stored per customer reference ID (CRID). The CRID will be taken from the `LABEL_OWNER` role of your Payment Authorization token.
        * The root svg element requires a `viewbox` attribute
        * The displayed aspect ratio of images on a label is 1:1 for square images and 33:5 for rectangle images.
          * Recommendation: Allow the artwork inside the viewbox to occupy 100% of the space. This will allow your logo to be shown at the highest resolution possible.
        * `<script/>` element tags and `DOCTYPE` definitions are not allowed. The `<use/>` and `<image/>` tags are not allowed to use the attribute `xlink:href`.
      operationId: post-label-branding
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelBrandingUploadRequest'
            examples:
              LabelBrandingUploadExample:
                $ref: '#/components/examples/LabelBrandingUploadExample'
          application/xml:
            schema:
              $ref: '#/components/schemas/LabelBrandingUploadRequest'
            examples:
              LabelBrandingUploadExample:
                $ref: '#/components/examples/LabelBrandingUploadExample'
        required: true
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelBrandingUploadResponse'
              example:
                imageUUID: a0529b65-706b-4686-aff5-60e39857cd00
                imageName: testLogo
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelBrandingUploadResponse'
        "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: { }
      security:
        - OAuth:
            - labels
    get:
      tags:
        - Resources
      summary: Retrieve a paginated list of label branding images associated with your customer reference ID (CRID). You can sort the response using a query parameter.
      description: |
        Retrieve a paginated list of label branding images associated with your customer reference ID (CRID). The response may be sorted using the URL query parameters defined below.
      operationId: get-list-label-branding
      parameters:
        - name: limit
          in: query
          description: The number of items to return.
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: The number of items to skip before returning the results.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: orderBy
          in: query
          description: Sort results in ascending or descending order.
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: sortBy
          in: query
          description: Sort by field, e.g., `imageName` or `createdDateTime`.
          required: false
          schema:
            type: string
            enum: [imageName, createdDateTime]
            default: createdDateTime
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelBrandingGetListResponse'
              example:
                images:
                  - imageUUID: e791d26b-d081-4976-8abf-4ea1dbc15479
                    imageName: foo
                    imageData: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
                    createdDateTime: "2025-06-02T18:11:45.799633Z"
                  - imageUUID: a0529b65-706b-4686-aff5-60e39857cd00
                    imageName: testLogo
                    imageData: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
                    createdDateTime: "2025-04-23T16:07:19Z"
                limit: 10
                offset: 0
                totalCount: 2
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelBrandingGetListResponse'
        "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: { }
      security:
        - OAuth:
            - labels
  /branding/{imageUUID}:
    get:
      tags:
        - Resources
      summary: Retrieve a label branding image associated with your customer reference ID (CRID).
      description: |
        Retrieve a label branding image associated with your customer reference ID (CRID).
        The CRID will be taken from the `LABEL_OWNER` role of your Payment Authorization token.
      operationId: get-single-label-branding
      parameters:
        - $ref: "#/components/parameters/LabelBrandingImageUUID"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelBrandingGetImageResponse'
              example:
                imageUUID: a0529b65-706b-4686-aff5-60e39857cd00
                imageName: testLogo
                createdDateTime: "2025-04-23T16:07:19Z"
                imageData: PHN2Zz48L3N2Zz4=
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelBrandingGetImageResponse'
        "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: { }
      security:
        - OAuth:
            - labels
    delete:
      tags:
        - Resources
      summary: Delete a previously uploaded label branding image by imageUUID.
      description: |
        Delete a label branding image associated with your customer reference ID (CRID).
        The CRID will be taken from the `LABEL_OWNER` role of your Payment Authorization token.
      operationId: delete-label-branding
      parameters:
        - $ref: "#/components/parameters/LabelBrandingImageUUID"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelBrandingDeleteResponse'
              examples:
                LabelBrandingDeleteExample:
                  $ref: '#/components/examples/LabelBrandingDeleteExample'
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelBrandingDeleteResponse'
        "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: { }
      security:
        - OAuth:
            - labels
    patch:
      tags:
        - Resources
      summary: Rename the previously uploaded Label Branding Image by imageUUID.
      description: |
        Rename the previously uploaded Label Branding Image associated with your customer reference ID (CRID).
        The CRID will be taken from the `LABEL_OWNER` role of your Payment Authorization token.
      operationId: patch-label-branding
      parameters:
        - $ref: "#/components/parameters/LabelBrandingImageUUID"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandingPatchRequest'
            examples:
              Branding Image Update:
                $ref: '#/components/examples/BrandingExamplePatch'
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelBrandingPatchResponse'
              examples:
                LabelBrandingDeleteExample:
                  $ref: '#/components/examples/LabelBrandingPatchExample'
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelBrandingPatchResponse'
        "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: { }
      security:
        - OAuth:
            - labels
  /label-reprint/{trackingNumber}:
    post:
      tags:
        - Resources
      summary: Reprint a domestic shipping label by providing it's tracking number.
      description: |
        Reprint a Domestic Outbound or Domestic Return shipping label. Allows for different `ImageInfo` options to be specified.
        * Receipts cannot be reprinted.
        * Labels can only be reprinted up to the mailing date.
        * Labels can only be reprinted up to 3 times.
        * Canceled labels are not eligible for reprint.
      operationId: post-label-reprint-by-tracking
      parameters:
        - $ref: "#/components/parameters/TrackingNumber"
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelReprintRequest'
            examples:
              LabelReprintRequestExample:
                $ref: '#/components/examples/LabelReprintRequestExample'
          application/xml:
            schema:
              $ref: '#/components/schemas/LabelReprintRequest'
        required: true
      responses:
        "200":
          description: Successful operation.
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  style: form
            application/vnd.usps.labels+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LabelReprintDomesticOutboundResponse'
                  - $ref: '#/components/schemas/LabelReprintDomesticReturnResponse'
              examples:
                LabelReprintResponseExample:
                  $ref: '#/components/examples/LabelReprintResponseExample'
            application/vnd.usps.labels+xml:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LabelReprintDomesticOutboundResponse'
                  - $ref: '#/components/schemas/LabelReprintDomesticReturnResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  contentType: application/xml
                  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
                returnLabelMetadata:
                  contentType: application/xml
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/xml
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  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: { }
      security:
        - OAuth:
            - labels
  /label-reprint:
    post:
      tags:
        - Resources
      summary: Reprint a domestic shipping label by providing the X-Idempotency-Key header used to create the label.
      description: |
        Reprint a Domestic Outbound or Domestic Return shipping label. Allows for different `ImageInfo` options to be specified.
        * Receipts cannot be reprinted.
        * Labels can only be reprinted up to the mailing date.
        * Labels can only be reprinted up to 3 times.
        * Canceled labels are not eligible for reprint.
      operationId: post-label-reprint-by-idempotency
      parameters:
        - $ref: "#/components/parameters/X-Payment-Authorization-Token"
        - $ref: "#/components/parameters/X-Idempotency-Key"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelReprintRequest'
            examples:
              LabelReprintRequestExample:
                $ref: '#/components/examples/LabelReprintRequestExample'
          application/xml:
            schema:
              $ref: '#/components/schemas/LabelReprintRequest'
        required: true
      responses:
        "200":
          description: Successful operation.
          headers:
            X-Idempotency-Key:
              description: The idempotency key associated with the original label creation request.
              schema:
                type: string
                format: uuid
              example: 8be4df61-93ca-11d2-aa0d-00e098032b8c
          content:
            multipart/form-data:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  style: form
            application/vnd.usps.labels+json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LabelReprintDomesticOutboundResponse'
                  - $ref: '#/components/schemas/LabelReprintDomesticReturnResponse'
              examples:
                LabelReprintResponseExample:
                  $ref: '#/components/examples/LabelReprintResponseExample'
            application/vnd.usps.labels+xml:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LabelReprintDomesticOutboundResponse'
                  - $ref: '#/components/schemas/LabelReprintDomesticReturnResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  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
                returnLabelMetadata:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/json
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  style: form
            application/xml:
              schema:
                $ref: '#/components/schemas/LabelReprintMultiPartResponse'
              encoding:
                labelMetadata:
                  contentType: application/xml
                  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
                returnLabelMetadata:
                  contentType: application/xml
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"returnLabelMetadata\""
                  style: form
                returnLabelImage:
                  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
                reprintInfo:
                  contentType: application/xml
                  headers:
                    Content-Disposition:
                      style: simple
                      explode: false
                      schema:
                        type: string
                        example: "Content-Disposition: form-data; name=\"reprintInfo\""
                  style: form
                examples:
                  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: { }
      security:
        - OAuth:
            - labels
components:
  schemas:
    DomesticPackageDescription:
      title: Package Description with Rate Indicators
      additionalProperties: true
      allOf:
        - $ref: '#/components/schemas/BaseDomesticPackageDescription'
        - required:
            - rateIndicator
          type: object
          properties:
            rateIndicator:
              type: string
              description: |
                Use to specify USPS&#174; containers/packaging or container attributes that may affect postage.

                Note:
                  * Effective 07/12/2026:  Rate indicators `Q6`, `Q7`, `Q8`, `Q9`, and `Q0` are no longer supported.  The dimensions for Cubic Soft Pack tiers `P5`, `P6`, `P7`, `P8`, and `P9` will be updated to include the dimensions for Tiers 6-10.  For updated tiers and more information, please view the [Postal Bulletin](https://about.usps.com/postal-bulletin/2026/pb22705/html/updt_001.htm).
                
                Rate indicator list:
                  * 3D - 3-Digit
                  * 3N - 3-Digit Dimensional Rectangular
                  * 3R - 3-Digit Dimensional Nonrectangular
                  * 5D - 5-Digit
                  * BA - Basic
                  * BB - Mixed NDC
                  * CP - Cubic Parcel
                  * CM - USPS Connect&#174; Local Mail
                  * DC - NDC
                  * DE - SCF
                  * DF - 5-Digit
                  * DN - Dimensional Nonrectangular
                  * DR - Dimensional Rectangular
                  * E4 - Priority Mail Express Flat Rate Envelope - Post Office To Addressee
                  * E6 - Priority Mail Express Legal Flat Rate Envelope
                  * FA - Legal Flat Rate Envelope
                  * FB - Medium Flat Rate Box/Large Flat Rate Bag
                  * FE - Flat Rate Envelope
                  * FP - Padded Flat Rate Envelope
                  * FS - Small Flat Rate Box
                  * LC - USPS Connect&#174; Local Single Piece
                  * LF - USPS Connect&#174; Local Flat Rate Box
                  * LL - USPS Connect&#174; Local Large Flat Rate Bag
                  * LO - USPS Connect&#174; Local Oversized
                  * LS - USPS Connect&#174; Local Small Flat Rate Bag
                  * NN - Non-Presorted Nonprofit
                  * NP - Non-Presorted
                  * OS - Oversized
                  * PN - Presorted Nonprofit
                  * P5 - Cubic Soft Pack Tier 1
                  * P6 - Cubic Soft Pack Tier 2
                  * P7 - Cubic Soft Pack Tier 3
                  * P8 - Cubic Soft Pack Tier 4
                  * P9 - Cubic Soft Pack Tier 5
                  * Q6 - Cubic Soft Pack Tier 6
                  * Q7 - Cubic Soft Pack Tier 7
                  * Q8 - Cubic Soft Pack Tier 8
                  * Q9 - Cubic Soft Pack Tier 9
                  * Q0 - Cubic Soft Pack Tier 10
                  * PA - Priority Mail Express Single Piece
                  * PL - Large Flat Rate Box
                  * PM - Large Flat Rate Box APO/FPO/DPO
                  * PR - Presorted
                  * SN - SCF Dimensional Nonrectangular
                  * SP - Single Piece
                  * SR - SCF Dimensional Rectangular

              default: SP
              enum:
                - 3D
                - 3N
                - 3R
                - 5D
                - BA
                - BB
                - CP
                - CM
                - DC
                - DE
                - DF
                - DN
                - DR
                - E4
                - E6
                - FA
                - FB
                - FE
                - FP
                - FS
                - LC
                - LF
                - LL
                - LO
                - LS
                - NN
                - NP
                - OS
                - PN
                - P5
                - P6
                - P7
                - P8
                - P9
                - Q6
                - Q7
                - Q8
                - Q9
                - Q0
                - PA
                - PL
                - PM
                - PR
                - SN
                - SP
                - SR
          additionalProperties: true
    DomesticPackageDescriptionWithoutRateIndicator:
      title: Package Description without Rate Indicators
      additionalProperties: true
      allOf:
        - $ref: '#/components/schemas/BaseDomesticPackageDescription'
        - required:
            - packagingType
            - shape
          type: object
          properties:
            shape:
              type: string
              description: The shape of the package
              enum:
                - RECTANGULAR
                - NON_RECTANGULAR
            packagingType:
              type: string
              description: |
                USPS packaging or container attributes that may affect postage. If the packaging is customer provided, use `VARIABLE`.
              enum:
                - VARIABLE
                - 5-DIGIT_PRESORT
                - BASIC_PRESORT
                - FLAT_RATE_ENVELOPE
                - LEGAL_FLAT_RATE_ENVELOPE
                - PADDED_FLAT_RATE_ENVELOPE
                - SM_FLAT_RATE_BOX
                - MD_FLAT_RATE_BOX
                - LG_FLAT_RATE_BOX
                - CUBIC_PARCELS
                - CUBIC_SOFT_PACK
                - CONNECT_LOCAL_FLAT_RATE_BOX
                - CONNECT_LOCAL_SMALL_FLAT_RATE_BAG
                - CONNECT_LOCAL_LARGE_FLAT_RATE_BAG
          additionalProperties: true
    BaseDomesticPackageDescription:
      title: Package Description
      additionalProperties: true
      allOf:
        - $ref: '#/components/schemas/PackageDescription'
        - required:
            - destinationEntryFacilityType
            - height
            - length
            - mailClass
            - mailingDate
            - processingCategory
            - weight
            - width
          type: object
          properties:
            mailClass:
              type: string
              description: |
                The mail service requested.
                
                Note:
                - `PARCEL_SELECT` with a `destinationEntryFacilityType` of `NONE` will convert to `USPS_GROUND_ADVANTAGE`.
                - `PARCEL_SELECT_LIGHTWEIGHT` is deprecated and will convert to `PARCEL_SELECT`.
                - `FIRST-CLASS_PACKAGE_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE`.
                - Certain mail classes, such as `MEDIA_MAIL`, `BOUND_PRINTED_MATTER`, and `LIBRARY_MAIL`, have eligibility rules on what can be mailed using that service.  For more details on these mail classes, please visit [What are Package Services?](https://faq.usps.com/s/article/What-are-Package-Services).
                - The Heavy Printed Matter product is supported with `MARKETING_MAIL_PARCELS`. To create Heavy Printed Matter labels, the `rateIndicator` should be set to `PR` or `NP` for Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter or to `PN` or `NN` for Nonprofit Presorted or Nonpresorted USPS Marketing Mail Parcels Heavy Printed Matter respectively.
              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
                - MARKETING_MAIL_PARCELS
            processingCategory:
              type: string
              description: |-
                Value designates if shipment is `MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`.
                
                Note:
                * When requesting the mail class `USPS_CONNECT_MAIL`, users are required to use a processing category of `FLATS`.
                * The processing category `LETTERS` is only valid for mail classes `PRIORITY_MAIL` and `PRIORITY_MAIL_EXPRESS` for outbound shipments.
                * The processing category `FLATS` is not valid for mail class `USPS_GROUND_ADVANTAGE`.
                * `IRREGULAR` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.
                * `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.
              enum:
                - LETTERS
                - FLATS
                - MACHINABLE
                - IRREGULAR
                - NON_MACHINABLE
                - NONSTANDARD
            destinationEntryFacilityType:
              type: string
              description: |-
                Types of Facilities:
                * `NONE` - Translate to Destination Rate Indicator N
                * `DESTINATION_NETWORK_DISTRIBUTION_CENTER` - Translate to Destination Rate Indicator B
                * `DESTINATION_SECTIONAL_CENTER_FACILITY` - Translate to Destination Rate Indicator S
                * `DESTINATION_DELIVERY_UNIT` - Translate to Destination Rate Indicator D
                * `DESTINATION_SERVICE_HUB` - Translate to Destination Rate Indicator H
                * `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` - Translate to Destination Rate Indicator B
                
                Note:
                * If any value other than `NONE` is selected, a destinationEntryFacilityAddress is required.
                * The destinationEntryFacilityAddress must be a valid facility to drop your package
                * The destination entry facility type must be set to `NONE` when there is a value provided for the 'inductionZipCode' field
                * Effective 01/19/2025: `DESTINATION_DELIVERY_UNIT` is the only valid enumeration when using the 'USPS_CONNECT_MAIL' mail class
                * Effective 01/18/2026: `DESTINATION_NETWORK_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is no longer eligible.
                * Effective 01/18/2026: (NSA Only) `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is available as an option.
              enum:
                - NONE
                - DESTINATION_NETWORK_DISTRIBUTION_CENTER
                - DESTINATION_SECTIONAL_CENTER_FACILITY
                - DESTINATION_DELIVERY_UNIT
                - DESTINATION_SERVICE_HUB
                - DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER
            destinationEntryFacilityAddress:
              $ref: '#/components/schemas/DomesticAddress'
            packageOptions:
              allOf:
                - $ref: '#/components/schemas/DomesticPackageOptions'
                - type: object
                  properties:
                    immediateManifest:
                      type: boolean
                      default: false
                      description: |
                        Setting this field to `true` will send electronic data to Postal systems within 15 minutes of label creation.
                        
                        If invoked, this label <u><strong>cannot</strong></u> be canceled. Instead, one must request an unused label refund – which may be subject to an admin fee.                        
                        
                        Depending on time of label creation, your packages could be charged same day instead of next day.
                    originalPackage:
                      required:
                        - originalConstructCode
                        - originalTrackingNumber
                      type: object
                      description: |
                        * Note: packageOptions.originalPackage fields cannot be used in combination with packageOptions.returnReceiptTracking.
                      properties:
                        originalTrackingNumber:
                          maxLength: 34
                          minLength: 22
                          type: string
                          description: |
                            The tracking number associated with the package before it was over labeled.
                            For accurate tracking, this field requires a concatenated string consisting of the routingInformation and trackingNumber from the original label response.
                          example: "4201234567899212391234567812345671"
                        originalConstructCode:
                          maxLength: 3
                          minLength: 3
                          type: string
                          description: A 3-character code to identify the construct of the Original Label Tracking Number
                          example: C01
                  additionalProperties: true
            customerReference:
              maxItems: 4
              minItems: 0
              type: array
              description: |-
                Used for shippers to print a value on a label and included in the Shipping Services File (SSF).
                
                Note:
                 * Customer Reference #3-4 are only supported with label types `4X5LABEL`, `4X6LABEL`, and `6X4LABEL`.
                 * Customer Reference #3-4 cannot be used with a customs form.
                 * Customer Reference #3-4 will not be added to the SSF.
                 * Customer Reference will not display with `imageInfo.brandingImageFormat` value of `RECTANGLE`.
                 * When Customer Reference #4 is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.
              items:
                $ref: '#/components/schemas/DomesticCustomerReference'
            extraServices:
              maxItems: 5
              minItems: 0
              type: array
              description: |-
                Extra Service Code requested.
                * 365 - Global Direct Entry
                * 415 - USPS Label Delivery
                * 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 - HAZMAT Air Eligible Ethanol Package
                * 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package
                * 812 - HAZMAT Class 3 – Flammable Liquid Package
                * 813 - HAZMAT Class 7 - Radioactive Materials Package
                * 814 - HAZMAT Class 8 - Corrosive Materials Package
                * 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package
                * 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package
                * 817 - HAZMAT Class 9 - Lithium Battery - Returns Package
                * 818 - HAZMAT Class 9 - Lithium batteries, marked package
                * 819 - HAZMAT Class 9 - Dry Ice Package
                * 820 - HAZMAT Class 9 - Lithium batteries, unmarked package
                * 821 - HAZMAT Class 9 - Magnetized Materials Package
                * 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package
                * 823 - HAZMAT Division 5.1 - Oxidizers Package
                * 824 - HAZMAT Division 5.2 - Organic Peroxides Package
                * 825 - HAZMAT Division 6.1 – Toxic Materials Package
                * 826 - HAZMAT Division 6.2 – Infectious Substances Package
                * 827 - HAZMAT Excepted Quantity Provision Package
                * 828 - HAZMAT Ground Only
                * 829 - HAZMAT ID8000 Consumer Commodity Package
                * 830 - HAZMAT Lighters Package
                * 831 - HAZMAT LTD QTY Ground Package
                * 832 - HAZMAT Small Quantity Provision Package
                * 857 - Hazardous Material
                * 910 - Certified Mail
                * 911 - Certified Mail Restricted Delivery
                * 912 - Certified Mail Adult Signature Required
                * 913 - Certified Mail Adult Signature Restricted Delivery
                * 920 - USPS Tracking
                * 921 - Signature Confirmation
                * 922 - Adult Signature Required 21 or Over
                * 923 - Adult Signature Restricted Delivery 21 or Over
                * 924 - Signature Confirmation Restricted Delivery
                * 925 - Priority Mail Express Merchandise Insurance
                * 930 - Insurance <= $500
                * 931 - Insurance > $500
                * 934 - Insurance Restricted Delivery
                * 955 - Return Receipt
                * 957 - Return Receipt Electronic
                * 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)
                * 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)
                * 991 - Sunday Delivery
                
                Note:
                * When the extra service code "930" is provided in the request, if the item value is over $500, "930" will automatically be replaced with "931" - Insurance (Greater than $500).
                * USPS Label Delivery (Print and Deliver, extra service code "415"): When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page. This service is not available at all locations.
                * Some service codes require a combination with extra services such as "955" and "957". For all valid combinations, visit [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).
              items:
                $ref: '#/components/schemas/ExtraService'
            mailingDate:
              type: string
              description: |
                The local date on which the package will be mailed. If the time is not provided, it will be defaulted to 10:00 p.m. local time.  Local time will be based on the `destinationEntryFacilityAddress.ZIPCode` or `inductionZIPCode` when provided, otherwise `fromAddress.ZIPCode` will be used as the origin ZIP Code.
              oneOf:
                - $ref: '#/components/schemas/MailingDate'
                - $ref: '#/components/schemas/MailingDateTime'
            carrierRelease:
              type: boolean
              description: |
                Indicates whether recipients authorize a carrier to leave a shipment if no one is available to receive it at the time of delivery. Priority Mail Express&#174; shipments or items requiring a signature at delivery are not eligible (e.g. Signature Confirmation, Insurance > $500).

                Note:
                 * Carrier release is currently not supported when 'holdForPickup' is set to true
                 * Carrier Release is currently not supported with mail class values of 'PRIORITY_MAIL', 'PRIORITY_MAIL_EXPRESS', or 'USPS_GROUND_ADVANTAGE'
                 * Carrier Release is currently not supported with 'extraServices' 910, 911, 912, 913, 921, 922, 923, 924, 925, 930, 931, 934, 955, or 981
            physicalSignatureRequired:
              type: boolean
              description: |
                Indicates the method for the signature that will be used when signing for the package. For customers that are not specifically requiring a physical signature upon delivery, the "SIGNATURE_REQUIRED" option will indicate that the package is eligible for both an electronic signature online or a physical signature.
                For more information regarding USPS Electronic Signature Online (USPS eSOL) eligibility, please visit: https://faq.usps.com/s/article/USPS-Electronic-Signature-Online.
                For all mail classes, excluding Priority Mail Express, the default value is "SIGNATURE_REQUIRED".
                A value of "SIGNATURE_WAIVED" will not require the customer to sign for the package. "SIGNATURE_WAIVED" is only eligible for Priority Mail Express packages and is the default value.
                The 'carrierRelease' option is not eligible to be used in conjunction with 'signatureType'.
                The 'physicalSignatureRequired' field is required to include signature extra service code values such as 910, 911, 912, 913, 921, 922, 923, 924, 925, 931, 934, 955, 981 or an extraServiceCode value of 930 with a packageValue greater than 500.
            inductionZIPCode:
              $ref: '#/components/schemas/InductionZIPCode'
            serialNumberFormat:
              $ref: '#/components/schemas/SerialNumberFormat'
            shipperVisibilityMethod:
              type: string
              description: |
                When generating labels for a third party shipper the label provider must capture and provide contact details of the individual or entity to whom they provide the label. There are two methods for reporting shipper information to USPS:

                1. The label provider creates a unique USPS Mailer ID (MID) using the name, validated address, phone, and email contact information of each shipper. When using this method the Mailer ID should be submitted in the MID field in the LABEL_OWNER role when generating the payment authorization token and this field should be populated with 'MID_INFORMATION'

                2. An alternative method allows for the label provider to assign a unique alphanumeric value known as a platformUserId to each shipper and to report the platformUserId together with the required shipper contact details. When using this method the shipper contact details are required in the `senderAddress` object (including `streetAddress`, `city`, `state`, `ZIPCode`, `phone`, `email`, `platformUserId` & `firstName`/`lastName` or `firm`) and this field should be populated with 'SENDER_INFORMATION'.
              enum:
                - SENDER_INFORMATION
                - MID_INFORMATION
            mailOwnerMID:
              pattern: "^(\\d{6}|\\d{9})$"
              type: string
              description: This is the mailer ID associated with the mail owner for this label This provides an additional copy of the scan extract file to the MID's outbound folder.
            logisticsManagerMID:
              pattern: "^(\\d{6}|\\d{9})$"
              type: string
              description: This is the mailer ID associated with the logistics manager for this label This provides an additional copy of the scan extract file to the MID's outbound folder.
            nonprofit:
              $ref: '#/components/schemas/Nonprofit'
          additionalProperties: true
          description: |
            Package characteristics used to price the shipment including requested mail class, weight, dimensions, and more.
    DomesticPackageOptions:
      title: Package Options
      description: Options added to packages that are less frequently used.
      allOf:
        - $ref: '#/components/schemas/PackageOptions'
        - type: object
          properties:
            redirectAddress:
              deprecated: true
              allOf:
                - $ref: '#/components/schemas/DomesticLabelAddress'
            contentType:
              type: string
              description: |
                The type of contents in the package.
                
                Note:
                * `CREMATED_REMAINS` is currently only eligible for the `PRIORITY_MAIL_EXPRESS` mail class and is not eligible for Hold for Pickup shipments.  Please refer to [Publication 139](https://about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.
                * `DAY_OLD_POULTRY` is currently only eligible with mail class values of `USPS_GROUND_ADVANTAGE`, `PRIORITY_MAIL` and `PRIORITY_MAIL_EXPRESS`.
                * Shipments that contain Live Animals or Perishables will incur a Live Animal and Perishables Handling Fee per mail piece. Content types `HAZMAT`, `CREMATED_REMAINS`, and `MEDICAL_SUPPLIES` do not apply and will not incur a fee. For `DAY_OLD_POULTRY` shipments only, an additional Live Animal Transport Fee per pound is applied. For more information, please visit [Live Animals Transportation Fee FAQ](https://faq.usps.com/s/article/Live-Animal-Transportation-Fee#:~:text=The%20Live%20Animal%20Transportation%20fee%20is%20charged%20%240.20%20per%20pound,prices%20to%20Zones%205%2D9)
                * `HAZMAT` domestic labels with destination addresses to APO/FPO/DPO and PTFAS (except Puerto Rico) will not contain any Hazmat markings/indicators, including service type codes in the IMpb. When users indicate a shipment contains hazmat materials in the API request (via content type and/or extra services), that information will still be captured and sent in the shipping services file. For more information, please review the [USPS APIs release notes](https://postalpro.usps.gov/usps-apis-releases)
                * For guidelines on shipping Perishable and Hazardous Material, please refer to [Publication 52](https://pe.usps.com/text/pub52/welcome.htm).
                * For ZIP codes with restrictions:
                  * Please refer to the most recent [Postal Bulletin](https://about.usps.com/resources/postal-bulletin.htm) ZIP restriction table for more information. You can find this data under `Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`.
                  * When restriction `M` applies, then `BEES`, `DAY_OLD_POULTRY`, `ADULT_BIRDS`, `OTHER_LIVES`, `FRUITS`, `VEGETABLES`, and `LIVE_PLANTS` are not allowed.
                  * When restriction `X` applies, then `CREMATED_REMAINS` are not allowed.
              enum:
                - HAZMAT
                - CREMATED_REMAINS
                - BEES
                - DAY_OLD_POULTRY
                - ADULT_BIRDS
                - OTHER_LIVES
                - PERISHABLE
                - PHARMACEUTICALS
                - MEDICAL_SUPPLIES
                - FRUITS
                - VEGETABLES
                - LIVE_PLANTS
            generateGXEvent:
              type: boolean
              description: "Provides the option for a user to not create a \"GX\" event for the package. By default, a GX event will be created."
              default: true
            containers:
              maxItems: 3
              type: array
              description: containers
              items:
                $ref: '#/components/schemas/Container'
            ancillaryServiceEndorsements:
              type: string
              description: |
                Endorsements allow the sender to obtain the addressee's new (forwarding) address 
                (provided the appropriate endorsement is used and if the addressee filed a 
                Change-of-Address Order with the Postal Service) or the reason for non-delivery. 
                For more information see [PostalPro](https://postalpro.usps.com/address-quality/ancillary-service-endorsements).
                
                Note: 
                  * Ancillary Service Endorsements are currently not supported when 'holdForPickup' is set to 'true'.
                  * 'CHANGE_SERVICE_REQUESTED' with a mail class value of 'PRIORITY_MAIL' currently only supports a contentType of 'PERISHABLE'.
                  * 'CHANGE_SERVICE_REQUESTED' cannot be requested with a 'contentType' of 'HAZMAT' or any hazmat shipments.
                  * 'CHANGE_SERVICE_REQUESTED' with mail classes 'PARCEL_SELECT', 'USPS_GROUND_ADVANTAGE', and 'PRIORITY_MAIL' can only be used with extraServices '920' and '921'.
                  * Ancillary Service Endorsements are currently only supported with mail class values 'PARCEL_SELECT', 'USPS_GROUND_ADVANTAGE', 'PRIORITY_MAIL', and 'PRIORITY_MAIL_EXPRESS'.
                  * 'ELECTRONIC_SERVICE_REQUESTED' with a mail class value of 'PARCEL_SELECT' cannot be requested with a 'contentType' of 'HAZMAT' or any hazmat shipments.
              enum:
                - CHANGE_SERVICE_REQUESTED
                - ADDRESS_SERVICE_REQUESTED
                - ELECTRONIC_SERVICE_REQUESTED
                - RETURN_SERVICE_REQUESTED
                - TEMP_RETURN_SERVICE_REQUESTED
                - FORWARDING_SERVICE_REQUESTED
            returnReceiptTracking:
              type: boolean
              description: |
                Indicates whether a return receipt tracking number should be generated for the package.
                If set to `true`, the system will automatically add the Extra Service Code (ESC) `955`
                if it is not already present. When enabled, the `returnReceiptTrackingNumber` field will be populated in the response.
                
                Note: 
                  * `returnReceiptTracking` cannot be used in combination with `packageOptions.originalPackage` fields.
                  * Utilizing `returnReceiptTracking` will incur the `955` ESC associated fee.
              default: false
          additionalProperties: true
    DomesticPackageReturnOptions:
      title: Package Options
      description: Options added to packages that are less frequently used
      allOf:
        - $ref: '#/components/schemas/PackageOptions'
        - type: object
          properties:
            immediateManifest:
              type: boolean
              default: false
              description: |
                Setting this field to `true` will send electronic data to Postal systems within 15 minutes of label creation.
            redirectAddress:
              deprecated: true
              description: |
                **Deprecated**: Use the `ancillaryServiceEndorsements` field instead.
                
                Address to send the package to if it is not deliverable.
                
                Note:
                  - Required when `nonDeliveryOption` is a value of `REDIRECT`.

              allOf:
                - $ref: '#/components/schemas/DomesticLabelAddress'
            contentType:
              type: string
              description: |
                The type of contents in the package.
                * HAZMAT
                * CREMATED_REMAINS
                * BEES
                * DAY_OLD_POULTRY
                * ADULT_BIRDS
                * OTHER_LIVES
                * PERISHABLE
                * PHARMACEUTICALS
                * MEDICAL_SUPPLIES
                * FRUITS
                * VEGETABLES
                * LIVE_PLANTS
                
                Note:
                * `CREMATED_REMAINS` is currently only eligible for the `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` mail class.  Please refer to [Publication 139](https://about.usps.com/publications/pub139/welcome.htm) for guidelines on how to package and ship `CREMATED_REMAINS`.
                * `HAZMAT` domestic labels with destination addresses to APO/FPO/DPO and PTFAS (except Puerto Rico) will not contain any Hazmat markings/indicators, including service type codes in the IMpb. When users indicate a shipment contains hazmat materials in the API request (via content type and/or extra services), that information will still be captured and sent in the shipping services file. For more information, please review the [USPS APIs release notes](https://postalpro.usps.gov/usps-apis-releases)
                * For guidelines on shipping Hazardous Material, please refer to [Publication 52](https://pe.usps.com/text/pub52/welcome.htm).

              enum:
                - HAZMAT
                - CREMATED_REMAINS
                - BEES
                - DAY_OLD_POULTRY
                - ADULT_BIRDS
                - OTHER_LIVES
                - PERISHABLE
                - PHARMACEUTICALS
                - MEDICAL_SUPPLIES
                - FRUITS
                - VEGETABLES
                - LIVE_PLANTS
            generateGXEvent:
              type: boolean
              description: "Provides the option for a user to not create a \"GX\" event for the package. By default, a GX event will be created."
              default: true
            containers:
              maxItems: 3
              type: array
              description: containers
              items:
                $ref: '#/components/schemas/Container'
            ancillaryServiceEndorsements:
              type: string
              description: |
                Endorsements allow the sender to obtain the addressee's new (forwarding) address (provided the appropriate endorsement is used 
                and if the addressee filed a Change-of-Address Order with the Postal Service) or the reason for non-delivery. 
                For more information see [PostalPro](https://postalpro.usps.com/address-quality/ancillary-service-endorsements)

              deprecated: true
              enum:
                - CHANGE_SERVICE_REQUESTED
                - ADDRESS_SERVICE_REQUESTED
                - ELECTRONIC_SERVICE_REQUESTED
                - RETURN_SERVICE_REQUESTED
                - TEMP_RETURN_SERVICE_REQUESTED
                - FORWARDING_SERVICE_REQUESTED
          additionalProperties: true
    Container:
      title: Container
      required:
        - containerID
        - sortType
      type: object
      properties:
        containerID:
          maxLength: 34
          type: string
          description: Unique identifier for a container.
        sortType:
          type: string
          description: "Sort Types requested."
          enum:
            - TRUCK_BEDLOAD
            - OPEN_DISTRIBUTION_FULL_POSTAL_PAKS
            - OPEN_DISTRIBUTE_EMM_TRAY_BOX
            - OPEN_DISTRIBUTE_FULL_TRAY_BOX
            - OPEN_DISTRIBUTE_HALF_TRAY_BOX
            - OPEN_DISTRIBUTE_HALF_POSTAL_PAKS
            - OPEN_DISTRIBUTE_PALLET
            - OPEN_DISTRIBUTE_FLAT_TUB_TRAY_BOX
            - PALLET
            - RECEPTACLE
            - SACK
      additionalProperties: false
      description: containers
    DomesticCustomerReference:
      title: Customer Reference
      allOf:
        - $ref: '#/components/schemas/CustomerReference'
        - type: object
          properties:
            printReferenceNumber:
              type: boolean
              default: false
              description: |
                Indicates whether or not to print the customer reference number on the label in the Additional Information and User Segment.
                
                Note: 
                - Customer Reference numbers are not displayed on label types `2X7LABEL` or `4X4LABEL`.
                - Customer Reference numbers are not displayed with Customs Forms.
          additionalProperties: true
    ExtraService:
      title: Extra Service Codes
      type: integer
      description: |
        Extra Service Code (ESC) requested.

        Extra Service Code list:
          * 365 - Global Direct Entry
          * 415 - USPS Label Delivery
          * 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 - HAZMAT Air Eligible Ethanol Package
          * 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package
          * 812 - HAZMAT Class 3 – Flammable Liquid Package
          * 813 - HAZMAT Class 7 - Radioactive Materials Package
          * 814 - HAZMAT Class 8 - Corrosive Materials Package
          * 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package
          * 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package
          * 817 - HAZMAT Class 9 - Lithium Battery - Returns Package
          * 818 - HAZMAT Class 9 - Lithium batteries, marked package
          * 819 - HAZMAT Class 9 - Dry Ice Package
          * 820 - HAZMAT Class 9 - Lithium batteries, unmarked package
          * 821 - HAZMAT Class 9 - Magnetized Materials Package
          * 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package
          * 823 - HAZMAT Division 5.1 - Oxidizers Package
          * 824 - HAZMAT Division 5.2 - Organic Peroxides Package
          * 825 - HAZMAT Division 6.1 – Toxic Materials Package
          * 826 - HAZMAT Division 6.2 – Infectious Substances Package
          * 827 - HAZMAT Excepted Quantity Provision Package
          * 828 - HAZMAT Ground Only
          * 829 - HAZMAT ID8000 Consumer Commodity Package
          * 830 - HAZMAT Lighters Package
          * 831 - HAZMAT LTD QTY Ground Package
          * 832 - HAZMAT Small Quantity Provision Package
          * 857 - Hazardous Material
          * 910 - Certified Mail
          * 911 - Certified Mail Restricted Delivery
          * 912 - Certified Mail Adult Signature Required
          * 913 - Certified Mail Adult Signature Restricted Delivery
          * 920 - USPS Tracking
          * 921 - Signature Confirmation
          * 922 - Adult Signature Required 21 or Over
          * 923 - Adult Signature Restricted Delivery 21 or Over
          * 924 - Signature Confirmation Restricted Delivery
          * 925 - Priority Mail Express Merchandise Insurance
          * 930 - Insurance <= $500
          * 931 - Insurance > $500
          * 934 - Insurance Restricted Delivery
          * 955 - Return Receipt
          * 957 - Return Receipt Electronic
          * 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)
          * 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)
          * 991 - Sunday Delivery
           
         Note:
         - Extra Service Code "415 - USPS Label Delivery": When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page.
      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
        - 857
        - 910
        - 911
        - 912
        - 913
        - 920
        - 921
        - 922
        - 923
        - 924
        - 925
        - 930
        - 931
        - 934
        - 955
        - 957
        - 981
        - 986
        - 991
    DomesticCustomsForm:
      title: Customs Form
      description: Domestic Customs Form
      allOf:
        - $ref: '#/components/schemas/CustomsForm'
        - required:
            - contents
            - customsContentType
          type: object
          properties:
            customsContentType:
              type: string
              description: |
                Specifies the content of the package or envelope.
                 * MERCHANDISE
                 * GIFT
                 * DOCUMENT
                 * COMMERCIAL_SAMPLE
                 * RETURNED_GOODS
                 * OTHER
                 * HUMANITARIAN_DONATIONS
                 * DANGEROUS_GOODS
              enum:
                - MERCHANDISE
                - GIFT
                - DOCUMENT
                - COMMERCIAL_SAMPLE
                - RETURNED_GOODS
                - OTHER
                - HUMANITARIAN_DONATIONS
                - DANGEROUS_GOODS
            importersReference:
              maxLength: 40
              type: string
              description: "Importers Reference. The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            importersContact:
              maxLength: 30
              type: string
              description: "Importers Contact. Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            exportersReference:
              maxLength: 40
              type: string
              description: "Exporters Reference. The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            exportersContact:
              maxLength: 30
              type: string
              description: "Exporters Contact. Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            contents:
              minItems: 1
              maxItems: 30
              type: array
              description: |-
                Details of the contents of the package. The first five items will print on the label of the customs form, and the rest will print on a separate continuation page.
              items:
                required:
                  - itemDescription
                  - itemQuantity
                  - itemTotalValue
                  - itemTotalWeight
                  - weightUOM
                allOf:
                  - $ref: '#/components/schemas/ShippingContents'
          additionalProperties: true
          description: |-
            Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).
            Required only if a customs form is required based on Customs Content Type and Weight.
            
            Note:
              * A domestic label with customs forms are currently ineligible to be used with the extra service of "USPS Label Delivery" (415).
    DomesticReturnsCustomsForm:
      title: Customs Form
      description: Domestic Returns Custom Form
      allOf:
        - $ref: '#/components/schemas/CustomsForm'
        - type: object
          properties:
            customsContentType:
              type: string
              description: |
                Specifies the content of the package or envelope.
                 * MERCHANDISE
                 * GIFT
                 * DOCUMENT
                 * COMMERCIAL_SAMPLE
                 * RETURNED_GOODS
                 * OTHER
                 * HUMANITARIAN_DONATIONS
                 * DANGEROUS_GOODS
              enum:
                - MERCHANDISE
                - GIFT
                - DOCUMENT
                - COMMERCIAL_SAMPLE
                - RETURNED_GOODS
                - OTHER
                - HUMANITARIAN_DONATIONS
                - DANGEROUS_GOODS
            importersReference:
              maxLength: 40
              type: string
              description: "Importers Reference. The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            importersContact:
              maxLength: 30
              type: string
              description: "Importers Contact. Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            exportersReference:
              maxLength: 40
              type: string
              description: "Exporters Reference. The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax."
            exportersContact:
              maxLength: 30
              type: string
              description: "Exporters Contact. Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery."
            contents:
              minItems: 1
              maxItems: 30
              type: array
              description: |-
                Details of the contents of the package. The first five items will print on the label of the customs form, and the rest will print on a separate continuation page.
              items:
                $ref: '#/components/schemas/ShippingContents'
          additionalProperties: true
          description: |-
            Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).
            Required only if a customs form is required based on Customs Content Type and Weight.
            
            Note:
              * A domestic return label with a customs form cannot have an extra service of "USPS Label Delivery" (415).
    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.
            * `PDF`
            * `TIFF`
            * `JPG`
            * `PNG`
            * `GIF`
            * `SVG`
            * `ZPL203DPI`
            * `ZPL300DPI`
            * `EPL300DPI`
            * `LABEL_BROKER` - Request a USPS QR code to allow your customers with no access to a printer to print at participating Post Office Locations. All USPS API users and third-party integrators utilizing QR codes are subject to the [Label Broker terms and conditions](https://www.usps.com/terms-conditions/label-broker.htm). For more information please see the Label Broker guide available on [GitHub](https://github.com/USPS/api-examples/blob/main/USPS%20APIs%20Domestic%20Labels%20API%20Documentation_2023_0901%20Published.pdf) (Note: Only supports labelType of `4X6LABEL` or `6X4LABEL` and receiptOption of `NONE`).  A USPS Label Broker QR code image will be returned in the API response instead of a label image.
            * `NONE`
            
            Note:
            - Labels with customs forms only support formats of `PDF`, `TIFF`, `ZPL203DPI`, `ZPL300DPI`, `LABEL_BROKER`, and `NONE`.
            - Including Extra Service Code `415 - USPS Label Delivery` returns no images and is equivalent to requesting `NONE`.
            - `EPL300DPI` is not supported for Return Labels.
          default: PDF
          enum:
            - PDF
            - TIFF
            - JPG
            - PNG
            - GIF
            - SVG
            - ZPL203DPI
            - ZPL300DPI
            - EPL300DPI
            - LABEL_BROKER
            - NONE
        labelType:
          type: string
          description: |
            Ability to select the label image size.  If omitted then the default label size is `4X6LABEL`.
            
            Note:
              * Currently, customs forms only support `4X6LABEL`.
              * The `labelType` of `2X7LABEL` is not supported with the `imageType` of `ZPL203DPI` or `ZPL300DPI`.
              * The `labelType` of `4X6LABEL` is the only supported format with the `imageType` of `EPL300DPI`.
          default: 4X6LABEL
          enum:
            - 4X4LABEL
            - 4X5LABEL
            - 4X6LABEL
            - 6X4LABEL
            - 2X7LABEL
        shipInfo:
          type: boolean
          description: indicates if revenue protection information is printed on the label. (true or false)
          deprecated: true
        receiptOption:
          type: string
          description: |
            Label & Receipt print out options: Enter `SAME_PAGE` to print the Label and the Receipt on a single page. Enter `SEPARATE_PAGE` to print the Label and the Receipt on separate pages. Enter `NONE` to print the Label only and no Receipt.
            
            Note:
              * The `labelType` of `4X4LABEL` or `6X4LABEL` with the image `imageType` of `ZPL203DPI` or `ZPL300DPI` does not support a `receiptOption` of `SEPARATE_PAGE`.
              * When `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`, a `receiptOption` of `SAME_PAGE` is not supported.
              * When `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI` and `receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL or EPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
          default: SAME_PAGE
          enum:
            - SAME_PAGE
            - SEPARATE_PAGE
            - NONE
        brandingImageFormat:
          type: string
          description: |
            The format of label branding images to be shown on the generated label image.

            Note:
            * Label branding images will not be shown on labels with customs forms.
            * Label branding images are not currently supported with an `imageType` of `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`.
            * Label branding images are not currently supported with a `labelType` of `4X4LABEL`.
            * When a `brandingImageFormat` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.
            * When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference #3-#4 cannot be provided since they will not be shown.
            * When a `brandingImageFormat` of `ONE_SQUARE` or `TWO_SQUARES` is provided, Customer Reference numbers will be shifted to the right to accommodate the image.
            * When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference numbers, package number, and total packages will not be displayed on the label.
            * A `brandingImageFormat` of `ONE_SQUARE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, `6X4LABEL`, and `2X7LABEL` for both outbound and return labels.
            * A `brandingImageFormat` of `TWO_SQUARES` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for both outbound and return labels.
            * A `brandingImageFormat` of `RECTANGLE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for outbound labels and `4X5LABEL` and `6X4LABEL` for return labels.
          default: NONE
          enum:
            - ONE_SQUARE
            - TWO_SQUARES
            - RECTANGLE
            - NONE
        brandingImageUUIDs:
          type: array
          maxItems: 2
          minItems: 0
          default: [ ]
          description: |
            The UUIDs associated with custom images uploaded in the Logo Branding endpoint: /branding

            Note:
            * These UUIDs must have been created with the same Payment Authorization Label Owner CRID in use when creating the label
            * When using `ONE_SQUARE` or `RECTANGLE` the brandingImageUUIDs list should include only one imageUUID string.
            * When using `TWO_SQUARES` the brandingImageUUIDs list should include only two imageUUID strings.
          example: [ "345df38d-6130-4ad1-838c-8883af55c584" ]
          items:
            maxLength: 36
            minLength: 36
            pattern: "[A-Fa-f0-9]{8}-([A-Fa-f0-9]{4}-){3}[A-Fa-f0-9]{12}"
            type: string
        includeLabelBrokerPDF:
          type: boolean
          default: false
          description: |
            Applicable only when `imageType` is `LABEL_BROKER`. When `includeLabelBrokerPDF` is `true`, two label images will be returned in the multi-part and vendor response as `labelBrokerQR` and `labelImage`. `labelBrokerQR` will contain the base64 PNG of the Label Broker QR Code and `labelImage` will contain the base64 PDF of the Label stored in Label Broker. When `includeLabelBrokerPDF` is `false`, one image will be returned in the multi-part and vendor response as `labelImage` as the base64 PNG of the Label Broker QR Code.
        addZPLComments:
          type: boolean
          default: false
          deprecated: true
          description: |
            Note: This field has been deprecated in favor of `addImageComments`.
            
            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`
        addImageComments:
          type: boolean
          default: false
          description: |
            Applicable only when `imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`.  When `addImageComments` is `true`, comments will be visible within the ZPL or EPL text response to the user to denote different sections of their label.  When `addImageComments` is `false`, no comments will be included in the ZPL or EPL 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: true
      description: Additional details used to determine how to generate the label image.
    IndiciaImbImageInfo:
      title: Indicia IMB Image Info
      type: object
      properties:
        imageType:
          type: string
          description: "The image type to be created.  If omitted then the default image type is PDF."
          default: PDF
          enum:
            - PDF
            - TIFF
            - JPG
            - PNG
            - GIF
            - SVG
        labelType:
          type: string
          description: |
            The requested image size. 
            - Using `6X4LABEL` will return the image in the `indiciaImage` response field.
            - Using `IMI_DATA_ONLY` will return the IMI data in the `indiciaIMI` response field and not populate the `indiciaImage` or `receiptImage` field.

          default: 6X4LABEL
          enum:
            - 6X4LABEL
            - IMI_DATA_ONLY
        receiptOption:
          type: string
          description: |
            Indicia & Receipt print out options: Enter `SEPARATE_PAGE` to print the Indicia and the Receipt on separate pages. Enter `NONE` to print the Indicia only and no Receipt.
            
            Note:
            - `NONE` is the only option supported when `labelType` is set to `IMI_DATA_ONLY`.
          default: NONE
          enum:
            - SEPARATE_PAGE
            - NONE
      additionalProperties: true
      description: Additional details used to determine how to generate the indicia image.
    SerialNumberFormat:
      title: Serial Number Format
      type: string
      description: |
        Used to specify the barcode construct used for the generated tracking number.  For details on barcode constructs, reference Appendix J in [Pub 199](https://postalpro.usps.com/pub199).
        
        `STANDARD` - Will generate a `C01`, `C03`, `C05`, or `C07` barcode construct, based on the Label Owner's `MID` in the Payment Authorization Token.
        
        `EXTENDED` - Will generate a `C02` or `C06` barcode construct, based on the Label Owner's `MID` in the Payment Authorization Token.
      default: STANDARD
      enum:
        - STANDARD
        - EXTENDED
    Nonprofit:
      title: Nonprofit Indicator
      type: boolean
      description: |
        Used to specify if the shipment is a nonprofit mailing.  Shippers must be authorized for nonprofit mailings to qualify for nonprofit pricing.  All nonprofit mailings must not be used for product fulfillment.  For more details on Nonprofit Mailers, visit [Nonprofit Mailers](https://pe.usps.com/BusinessMail101?ViewName=NonprofitPrices).

        When `nonprofit` is `true` and `mailClass` is `MARKETING_MAIL_PARCELS`, nonprofit rates will be applied.  When using `rateIndicator` values, the `rateIndicator` must also be `NN` or `PN`.

        When `nonprofit` is `false` and `mailClass` is `MARKETING_MAIL_PARCELS`, standard rates will be applied.

        `nonprofit` is not supported for any other mail class.
      default: false
    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. Date USPS expects that the package or mailpiece will be delivered based on the origin, destination, and drop-off time and date in the request. Actual delivery date may vary based on when the package or mailpiece is entered or other conditions.

            Note: This field has been deprecated in favor of `expectedDeliveryDate` and will be removed in a future release. Please transition to using `expectedDeliveryDate`.
          deprecated: true
        expectedDeliveryDate:
          type: string
          description: Date in the YYYY-MM-DD format.
        isPriorityMailNextDay:
          type: boolean
          description: "Indicates if the commitment is for Priority Mail Next Day service."
      additionalProperties: true
      description: The commitment and scheduled delivery date of the package.
    LabelRequest:
      title: Domestic Package Request
      required:
        - fromAddress
        - packageDescription
        - toAddress
      type: object
      properties:
        imageInfo:
          description: Image Information
          allOf:
            - $ref: '#/components/schemas/ImageInfo'
            - type: object
              additionalProperties: true
              properties:
                suppressPostage:
                  type: boolean
                  description: |
                    Indicates if postage is printed on the label.  If omitted then the request will be defaulted to true.
                  default: true
                suppressMailDate:
                  type: boolean
                  description: |
                    Indicates if the `mailingDate` is printed on the label.  If omitted then the value will default to true.
        
                    Note:
                     * Mail Date cannot be suppressed on Domestic Customs Forms. The customs form will always display the Date of Mailing.
                     * The date the label was created cannot be suppressed and will always print on the label.
                  default: true
                returnLabel:
                  type: boolean
                  description: |-
                    Indicates if a pay on use returns label is requested along with the outbound label.  If omitted then the request will be defaulted to false.
        
                    The mail class of the generated return label will be based off of the mail class provided in `packageDescription.mailClass`.
                    * Priority Mail Express Return Service label will be generated with `packageDescription.mailClass` of `PRIORITY_MAIL_EXPRESS`.
                    * Priority Mail Return Service label will be generated with `packageDescription.mailClass` of `PRIORITY_MAIL`.
                    * USPS Ground Advantage Return Service label will be generated with all other `packageDescription.mailClass` enumerations.
        
                    Note:
                     * An `imageType` value of `LABEL_BROKER` is currently not supported when `returnLabel` is set to true.
                     * A `packageDescription.mailClass` value of `USPS_CONNECT_MAIL` is currently not supported when `returnLabel` is set to true.
                     * `returnLabel` cannot be set to `true` when generating customs forms.
                     * `returnLabel` is not available when Extra Service Code `415 - USPS Label Delivery` is used.
                  default: false
                packageNumber:
                  maximum: 9999
                  minimum: 1
                  type: integer
                  description: |-
                    The package number in a series such as 1 of 3, 2 of 3, etc.  If `totalPackages` is populated then `packageNumber` is required.  `packageNumber` must be less than or equal to `totalPackages`.  This feature is not supported on the 2x7 or 4x4 label format.
                    
                    Note:
                    * When `packageNumber` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.
                totalPackages:
                  maximum: 9999
                  minimum: 1
                  type: integer
                  description: The total number of packages in a series such as 999.  If packageNumber is populated then totalPackages is required.  totalPackages must be greater than or equal to packageNumber.  This feature is not supported by the 2x7 or 4x4 label format.
          additionalProperties: true
        toAddress:
          $ref: '#/components/schemas/DomesticLabelToAddress'
        fromAddress:
          $ref: '#/components/schemas/DomesticLabelAddress'
        senderAddress:
          $ref: '#/components/schemas/DomesticLabelSenderAddress'
        returnAddress:
          description: |
            The address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label.

            Note:
            * The First and Last Name or Firm Name are always required.
          allOf:
            - $ref: '#/components/schemas/DomesticLabelAddress'
        packageDescription:
          description: Package description
          oneOf:
            - $ref: '#/components/schemas/DomesticPackageDescription'
            - $ref: '#/components/schemas/DomesticPackageDescriptionWithoutRateIndicator'
        customsForm:
          $ref: '#/components/schemas/DomesticCustomsForm'
      additionalProperties: false
      description: Destination address of the recipient. Used in pricing as the destination ZIP Code&#8482;.
    LabelMetadata:
      title: Label Metadata
      type: object
      properties:
        labelAddress:
          $ref: '#/components/schemas/DomesticLabelAddress'
        routingInformation:
          type: string
          description: The "420" 3-digit GS1 Application Identifier and the 5 or 9 digit Destination ZIP Code&#8482;.
        trackingNumber:
          type: string
          description: The human-readable version of the package tracking number.
        constructCode:
          type: string
          description: The barcode construct code associated with the tracking number.
        SKU:
          type: string
          description: Pricing SKU.
        postage:
          type: number
          description: "Amount of Postage Required, does not include insurance or other extra service fees."
        extraServices:
          $ref: '#/components/schemas/ExtraServiceResponse'
        serviceTypeCode:
          type: string
          description: |
            The Service Type Code associated with the package. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).
        zone:
          type: string
          description: Indicates the calculated zone used for pricing between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, `rateIndicator`, and `weight`.
        mailingDate:
          type: string
          description: The date on which the package will be mailed as provided in the request. If the time was not provided, it will be defaulted to 10:00 p.m. local time.
          format: date-time
          example: "2026-01-01T22:00:00Z"
        commitment:
          $ref: '#/components/schemas/Commitment'
        weightUOM:
          type: string
          description: |-
            Weight Unit of Measurement
               * lb - Pounds
        weight:
          type: number
          description: "The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less."
        dimensionalWeight:
          type: number
          description: "The dimensional weight of the package, if greater than specified in weight, in ounces."
        fees:
          type: array
          description: Fees associated with 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: float
            additionalProperties: false
        permitHolderName:
          type: string
          description: The permit holder name.
        inductionType:
          type: object
          additionalProperties: false
          description: The permit holder induction type.
        labelBrokerID:
          maxLength: 10
          type: string
          description: Unique Label Broker ID that can be used as an alternative to the Label Broker QR Code to retrieve the label at a Post Office. Will only be provided when an imageType of LABEL_BROKER is requested.
        bannerText:
          type: string
          description: Banner text printed on the label.
          example: "USPS TRACKING # USPS Ship"
        retailDistributionCode:
          type: string
          description: Retail Description Code associated with label.
          example: "01"
        returnReceiptTrackingNumber:
          type: string
          description: |
            The human-readable version of the return Receipt tracking number.
            
            * Note: This will be included in the response when `packageOptions.returnReceiptTracking` is set to true in the request.
        links:
          $ref: '#/components/schemas/Links'
      additionalProperties: true
      description: Label Metadata returned from label creation and label edit.
    CancelResponse:
      title: Cancel Label Response
      type: object
      properties:
        trackingNumber:
          type: string
          description: The tracking number associated with the label that has been canceled or for which a refund request has been submitted.
          example: "9205590006662202169556"
        status:
          type: string
          description: |
            * `CANCELED` indicates that the label has been successfully canceled.
            * `DISPUTED` indicates that a refund request has been submitted.
          enum:
            - CANCELED
            - DISPUTED
          example: DISPUTED
        disputeId:
          type: string
          description: The Id of the submitted refund request.
          example: "104660"
    IMBCancelResponse:
      title: Cancel Intelligent Mail Barcode Response
      description: Cancel Intelligent Mail Barcode (IMB) Response
      type: object
      properties:
        imb:
          type: string
          description: The Human-readable form of the Intelligent Mail Barcode (IMB) that has been canceled or for which a refund request has been submitted.
          example: "00700123456000000001200669998"
        status:
          type: string
          description: |
            * `CANCELED` indicates that the IMB has been successfully canceled.
            * `DISPUTED` indicates that a refund request has been submitted.

            Note:            
            - The `CANCELED` status has been deprecated.  All Cancel requests will have the `DISPUTED` status returned back for the refund request submission.
          enum:
            - CANCELED
            - DISPUTED
          example: DISPUTED
        disputeId:
          type: string
          description: |
            The Id of the submitted refund request.
            
            Note:
            - The disputeId field may not be returned for IMBs created prior to 8/27/2025.
            - If a refund request is successfully submitted, a disputeId will be returned that can be used to then track the status of the refund request. The system will only give one unique disputeId per customer reference ID (CRID) per day. Duplicate submissions of the same label, for the same CRID, on the same day, will be rejected.
            - In some cases, a disputeId may be generated before the IMB is processed for payment. If this occurs, please resubmit the IMB for cancellation the following day for a new disputeId.
          example: "104660"
    LabelVendorResponse:
      title: Label Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`.
      type: object
      allOf:
        - $ref: '#/components/schemas/LabelMetadata'
        - type: object
          properties:
            labelImage:
              type: string
              description: |
                Contains the Base64-encoded file contents of the label image. Provided only when `imageInfo.imageType` is not `NONE`.
 
                Note:
                - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
              format: byte
            receiptImage:
              type: string
              description: |
                Contains the Base64-encoded file contents of the label receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.
 
                Note:
                - When `imageInfo.imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL or EPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
                - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
              format: byte
            labelBrokerQR:
              type: string
              description: "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`."
              format: byte
            returnLabel:
              description: Return label
              allOf:
                - $ref: '#/components/schemas/ReturnLabelMetadata'
                - type: object
                  properties:
                    returnLabelImage:
                      type: string
                      description: |
                        Contains the Base64-encoded file contents of the return label image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.imageType` is not `NONE`.
                      format: byte
                    returnReceiptImage:
                      type: string
                      description: |
                        Contains the Base64-encoded file contents of the return receipt image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.receiptOption` is `SEPARATE_PAGE`.
                        
                        Note:
                        - When `imageInfo.imageType` is `ZPL203DPI` or `ZPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
                      format: byte
                    labelBrokerQR:
                      type: string
                      description: "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`."
                      format: byte
    LabelMultiPartResponse:
      title: Label Package Response for `multipart/form-data`.
      type: object
      properties:
        labelMetadata:
          $ref: '#/components/schemas/LabelMetadata'
        returnLabelMetadata:
          $ref: '#/components/schemas/ReturnLabelMetadata'
        labelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the label image. Provided only when `imageInfo.imageType` is not `NONE`.
 
            Note:
            - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
          format: byte
        receiptImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the label receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.
 
            Note:
            - When `imageInfo.imageType` is `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL or EPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
            - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
          format: byte
        returnLabelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return label image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.imageType` is not `NONE`.
          format: byte
        returnReceiptImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return receipt image. Provided only when `imageInfo.returnLabel` is `true` and `imageInfo.receiptOption` is `SEPARATE_PAGE`.
            
            Note:
            - When `imageInfo.imageType` is `ZPL203DPI` or `ZPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
          format: byte
        labelBrokerQR:
          type: string
          description: "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`."
          format: byte
      additionalProperties: false
    ReturnLabelVendorResponse:
      title: Return Label Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`
      type: object
      allOf:
        - $ref: '#/components/schemas/ReturnLabelMetadata'
        - type: object
          properties:
            returnLabelImage:
              type: string
              description: |
                Contains the Base64-encoded file contents of the return label image. Provided only when `imageInfo.imageType` is not `NONE`. 
                
                Note:
                - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
              format: byte
            returnReceiptImage:
              type: string
              description: |
                Contains the Base64-encoded file contents of the return receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.
 
                Note:
                - When `imageInfo.imageType` is `ZPL203DPI` or `ZPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
                - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
              format: byte
            labelBrokerQR:
              type: string
              description: "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`."
              format: byte
    ReturnLabelMultiPartResponse:
      title: Return  Package Response for `multipart/form-data`.
      type: object
      properties:
        returnLabelMetadata:
          $ref: '#/components/schemas/ReturnLabelMetadata'
        returnLabelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return label image. Provided only when `imageInfo.imageType` is not `NONE`.
 
            Note:
            - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
          format: byte
        returnReceiptImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.

            Note:
            - When `imageInfo.imageType` is `ZPL203DPI` or `ZPL300DPI` and `imageInfo.receiptOption` is `SEPARATE_PAGE`, the receipt will be returned as an additional label segment within the single ZPL payload in `labelImage`. In this case, `receiptImage` will not be populated.
            - Not provided when Extra Service Code `415 - USPS Label Delivery` is requested, as no images are returned for this service.
          format: byte
        labelBrokerQR:
          type: string
          description: "The Label Broker QR Code image, Base64 encoded file contents. Only provided if `imageType` in the `imageInfo` is set to `LABEL_BROKER`."
          format: byte
      additionalProperties: false
    ReturnLabelMetadata:
      title: Return Label Metadata
      description: Return Label Metadata
      type: object
      properties:
        labelAddress:
          $ref: '#/components/schemas/DomesticLabelAddress'
        routingInformation:
          type: string
          description: The "420" 3-digit GS1 Application Identifier and the 5 or 9 digit Destination ZIP Code&#8482;
        trackingNumber:
          type: string
          description: The human readable version of the package tracking number
        SKU:
          type: string
          description: Pricing SKU
        sku:
          type: string
          description: Pricing SKU
          deprecated: true
        postage:
          type: number
          description: "Amount of Postage Required, does not include insurance or other extra service fees."
        extraServices:
          $ref: '#/components/schemas/ExtraServiceResponse'
        serviceTypeCode:
          type: string
          description: |
            The Service Type Code associated with the package. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes)
        zone:
          type: string
          description: Indicates the calculated zone used for pricing between the provided `originZIPCode` and `destinationZIPCode` for a given `mailClass`, `mailingDate`, `rateIndicator`, and `weight`.
        mailingDate:
          type: string
          description: The date and time when the request was processed, with a two-hour offset applied.
          format: date-time
          example: "2026-01-01T22:00:00Z"
        weightUOM:
          type: string
          description: |-
            Weight Unit of Measurement
               * lb - Pounds
        weight:
          type: number
          description: "The package weight, in weightUOM. Items must weigh 70 pounds (1120 ounces) or less."
        dimensionalWeight:
          type: number
          description: "The dimensional weight of package, if greater than specified in weight, in ounces."
        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: float
            additionalProperties: false
        labelBrokerID:
          maxLength: 10
          type: string
          description: Unique Label Broker ID that can be used as an alternative to the Label Broker QR Code to retrieve the label at a Post Office. Will only be provided when an imageType of LABEL_BROKER is requested.
        bannerText:
          type: string
          description: Banner text printed on the label
          example: "USPS TRACKING # USPS Ship"
        retailDistributionCode:
          type: string
          description: Retail Description Code associated with the label
          example: "01"
        links:
          $ref: '#/components/schemas/Links'
    ReturnLabelRequest:
      title: Returns Package Request
      required:
        - fromAddress
        - packageDescription
        - toAddress
      type: object
      properties:
        imageInfo:
          description: Image information
          allOf:
            - $ref: '#/components/schemas/ImageInfo'
            - type: object
              properties:
                suppressPostage:
                  type: boolean
                  deprecated: true
                  description: |
                    This field has been deprecated.  Postage value is not printed on Return Labels.
                  default: true
                suppressMailDate:
                  type: boolean
                  deprecated: true
                  description: |
                    This field has been deprecated.
                    
                    Note:
                     * Mail Date will not be printed on Return Labels without a customs form.
                     * Mail Date will be printed on Domestic Customs Forms. The customs form will always display the Date of Mailing.
                     * The date the label was created cannot be suppressed and will always print on the label.
                  default: true
                returnLabel:
                  type: boolean
                  deprecated: true
                  description: |-
                    This field has been deprecated.  A return label cannot be generated with a return label.  This field will be ignored in the request.
                  default: false
                receiptOption:
                  description: Receipt Option
                  type: string
                  default: NONE
              additionalProperties: true
        toAddress:
          description: |
            The address where the return package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing.

            Notes:
            * The First and Last Name or Firm Name are always required.
            * For return labels, the `toAddress` ZIP Plus 4 is looked up by the API, unless the `ignoreBadAddress` field is set to true or the address cannot be found. If `ignoreBadAddress` field is true then ZIP Plus 4 is required.
          allOf:
            - $ref: '#/components/schemas/DomesticLabelAddress'
        fromAddress:
          description: |
            The address where the return package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing.

            Notes:
            * The First and Last Name or Firm Name are always required.
            * If the `returnAddress` is not provided, the `fromAddress` will be used as the `returnAddress`.
          allOf:
            - $ref: '#/components/schemas/DomesticLabelAddress'
        senderAddress:
          description: |
            The address of the business involved (typically the sender of the original package). The `senderAddress` can be different from the `toAddress` when the business address is not where the package is being shipped to.

            Notes:
            * The First and Last Name or Firm Name are always required.
            * `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.
          allOf:
            - $ref: '#/components/schemas/DomesticLabelSenderAddress'
        returnAddress:
          description: |
            The address where the package should be returned to if it is deemed undeliverable or returned to sender. This address will be printed in the return address block of the label. This could be a secondary return address in case the toAddress is deemed undeliverable or returned to sender. 

            Note:
            * The First and Last Name or Firm Name are always required.
          allOf:
            - $ref: '#/components/schemas/DomesticLabelAddress'
        packageDescription:
          description: package description
          oneOf:
            - $ref: '#/components/schemas/ReturnsPackageDescription'
            - $ref: '#/components/schemas/ReturnsPackageDescriptionWithoutRateIndicator'
        customsForm:
          $ref: '#/components/schemas/DomesticReturnsCustomsForm'
      additionalProperties: false
      description: Domestic Package Request
    ReturnsPackageDescriptionWithoutRateIndicator:
      title: Returns Package Description without Rate Indicators
      additionalProperties: true
      allOf:
        - $ref: '#/components/schemas/BaseReturnsPackageDescription'
        - required:
            - packagingType
            - shape
          type: object
          properties:
            shape:
              type: string
              description: The shape of the package
              enum:
                - RECTANGULAR
                - NON_RECTANGULAR
            packagingType:
              type: string
              description: "USPS packaging or container attributes that may affect postage. If the packaging is customer provided, use `VARIABLE`."
              enum:
                - VARIABLE
                - 5-DIGIT_PRESORT
                - BASIC_PRESORT
                - FLAT_RATE_ENVELOPE
                - LEGAL_FLAT_RATE_ENVELOPE
                - PADDED_FLAT_RATE_ENVELOPE
                - SM_FLAT_RATE_BOX
                - MD_FLAT_RATE_BOX
                - LG_FLAT_RATE_BOX
                - CUBIC_PARCELS
                - CUBIC_SOFT_PACK
          additionalProperties: true
    ReturnsPackageDescription:
      title: Returns Package Description with Rate Indicators
      additionalProperties: true
      allOf:
        - $ref: '#/components/schemas/BaseReturnsPackageDescription'
        - required:
            - rateIndicator
          type: object
          properties:
            rateIndicator:
              type: string
              description: |
                Use to specify USPS containers/packaging or container attributes that may affect postage.

                Note:
                  * Effective 07/12/2026:  Rate indicators `Q6`, `Q7`, `Q8`, `Q9`, and `Q0` are no longer supported.  The dimensions for Cubic Soft Pack tiers `P5`, `P6`, `P7`, `P8`, and `P9` will be updated to include the dimensions for Tiers 6-10.  For updated tiers and more information, please view the [Postal Bulletin](https://about.usps.com/postal-bulletin/2026/pb22705/html/updt_001.htm).
                  
                Rate indicator list:
                 * CP - Cubic Parcel
                 * DN - Dimensional Nonrectangular
                 * DR - Dimensional Rectangular
                 * E4 - Priority Mail Express Flat Rate Envelope - Post Office To Addressee
                 * E6 - Priority Mail Express Legal Flat Rate Envelope
                 * FA - Legal Flat Rate Envelope
                 * FB - Medium Flat Rate Box/Large Flat Rate Bag
                 * FE - Flat Rate Envelope
                 * FP - Padded Flat Rate Envelope
                 * FS - Small Flat Rate Box
                 * OS - Oversized
                 * P5 - Cubic Soft Pack Tier 1
                 * P6 - Cubic Soft Pack Tier 2
                 * P7 - Cubic Soft Pack Tier 3
                 * P8 - Cubic Soft Pack Tier 4
                 * P9 - Cubic Soft Pack Tier 5
                 * Q6 - Cubic Soft Pack Tier 6
                 * Q7 - Cubic Soft Pack Tier 7
                 * Q8 - Cubic Soft Pack Tier 8
                 * Q9 - Cubic Soft Pack Tier 9
                 * Q0 - Cubic Soft Pack Tier 10
                 * PA - Priority Mail Express Single Piece
                 * PL - Large Flat Rate Box
                 * PM - Large Flat Rate Box APO/FPO/DPO
                 * SP - Single Piece
              default: SP
              enum:
                - CP
                - DN
                - DR
                - E4
                - E6
                - FA
                - FB
                - FE
                - FP
                - FS
                - OS
                - P5
                - P6
                - P7
                - P8
                - P9
                - PA
                - PL
                - PM
                - Q6
                - Q7
                - Q8
                - Q9
                - Q0
                - SP
          additionalProperties: true
    BaseReturnsPackageDescription:
      title: Returns Package
      allOf:
        - $ref: '#/components/schemas/PackageDescription'
        - required:
            - height
            - length
            - mailClass
            - processingCategory
            - weight
            - width
          type: object
          properties:
            mailClass:
              type: string
              description: |
                The mail service requested.
                
                Note:
                - `FIRST-CLASS_PACKAGE_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`
                - `GROUND_RETURN_SERVICE` is deprecated and will convert to `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`
              enum:
                - FIRST-CLASS_PACKAGE_RETURN_SERVICE
                - GROUND_RETURN_SERVICE
                - PRIORITY_MAIL_EXPRESS_RETURN_SERVICE
                - PRIORITY_MAIL_RETURN_SERVICE
                - USPS_GROUND_ADVANTAGE_RETURN_SERVICE
            processingCategory:
              type: string
              description: |-
                Value designates if the shipment is `MACHINABLE`, `NONSTANDARD`, `LETTERS`, or `FLATS`.
                
                Note:
                * The processing category `LETTERS` is only valid when the mail class is `PRIORITY_MAIL_RETURN_SERVICE` or `PRIORITY_MAIL_EXPRESS_RETURN_SERVICE` for returns shipments.
                * The processing category `FLATS` is not valid for mail class `USPS_GROUND_ADVANTAGE_RETURN_SERVICE`.
                * `IRREGULAR` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.
                * `NON_MACHINABLE` is deprecated and will convert to `NONSTANDARD` as of 01/19/2025.
              enum:
                - LETTERS
                - FLATS
                - MACHINABLE
                - IRREGULAR
                - NON_MACHINABLE
                - NONSTANDARD
            customerReference:
              maxItems: 4
              type: array
              description: |-
                Used for shippers to print a value on a label and included in the Shipping Services Files.
              items:
                $ref: '#/components/schemas/DomesticCustomerReference'
            extraServices:
              maxItems: 5
              minItems: 0
              type: array
              description: |-
                Extra Service Code requested.
                * 365 - Global Direct Entry
                * 415 - USPS Label Delivery
                * 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 - HAZMAT Air Eligible Ethanol Package
                * 811 - HAZMAT Class 1 - Toy Propellant/Safety Fuse Package
                * 812 - HAZMAT Class 3 – Flammable Liquid Package
                * 813 - HAZMAT Class 7 - Radioactive Materials Package
                * 814 - HAZMAT Class 8 - Corrosive Materials Package
                * 815 - HAZMAT Class 8 - Nonspillable Wet Battery Package
                * 816 - HAZMAT Class 9 - Lithium Battery Marked - Ground Only Package
                * 817 - HAZMAT Class 9 - Lithium Battery - Returns Package
                * 818 - HAZMAT Class 9 - Lithium batteries, marked package
                * 819 - HAZMAT Class 9 - Dry Ice Package
                * 820 - HAZMAT Class 9 - Lithium batteries, unmarked package
                * 821 - HAZMAT Class 9 - Magnetized Materials Package
                * 822 - HAZMAT Division 4.1 – Flammable Solids or Safety Matches Package
                * 823 - HAZMAT Division 5.1 - Oxidizers Package
                * 824 - HAZMAT Division 5.2 - Organic Peroxides Package
                * 825 - HAZMAT Division 6.1 – Toxic Materials Package
                * 826 - HAZMAT Division 6.2 – Infectious Substances Package
                * 827 - HAZMAT Excepted Quantity Provision Package
                * 828 - HAZMAT Ground Only
                * 829 - HAZMAT ID8000 Consumer Commodity Package
                * 830 - HAZMAT Lighters Package
                * 831 - HAZMAT LTD QTY Ground Package
                * 832 - HAZMAT Small Quantity Provision Package
                * 857 - Hazardous Material
                * 910 - Certified Mail
                * 911 - Certified Mail Restricted Delivery
                * 912 - Certified Mail Adult Signature Required
                * 913 - Certified Mail Adult Signature Restricted Delivery
                * 920 - USPS Tracking
                * 921 - Signature Confirmation
                * 922 - Adult Signature Required 21 or Over
                * 923 - Adult Signature Restricted Delivery 21 or Over
                * 924 - Signature Confirmation Restricted Delivery
                * 925 - Priority Mail Express Merchandise Insurance
                * 930 - Insurance <= $500
                * 931 - Insurance > $500
                * 934 - Insurance Restricted Delivery
                * 955 - Return Receipt
                * 957 - Return Receipt Electronic
                * 981 - Signature Requested (PRIORITY_MAIL_EXPRESS only)
                * 986 - PO to Addressee (PRIORITY_MAIL_EXPRESS only)
                * 991 - Sunday Delivery
                
                Note:
                 * When the extra service code "930" is provided in the request, if the item value is over $500, "930" will automatically be replaced with "931" - Insurance (Greater than $500).
                 * USPS Label Delivery (Extra Service Code "415"): When requesting this service, no images will be returned in the API response. The label and receipt will be printed and mailed to the `fromAddress` provided. The mailed label will always include a receipt on the page. This service is not available at all locations.
                 * Some service codes require a combination with extra services such as "955" and "957". For all valid combinations, visit [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).
              items:
                $ref: '#/components/schemas/ExtraService'
            packageOptions:
              $ref: '#/components/schemas/DomesticPackageReturnOptions'
            destinationEntryFacilityAddress:
              deprecated: true
              description: Destination entry facility address
              allOf:
                - $ref: '#/components/schemas/DomesticAddress'
            inductionZIPCode:
              $ref: '#/components/schemas/InductionZIPCode'
            shipperVisibilityMethod:
              type: string
              description: |
                When generating labels for a third party shipper the label provider must capture and provide contact details of the individual or entity to whom they provide the label. For return labels, there is one method for reporting shipper information to USPS:

                1. An alternative method allows for the label provider to assign a unique alphanumeric value known as a `platformUserId` to each shipper and to report the `platformUserId` together with the required shipper contact details. When using this method the shipper contact details are required in the `senderAddress` object (including `streetAddress`, `city`, `state`, `ZIPCode`, `phone`, `email`, `platformUserId` & `firstName`/`lastName` or `firm`) and this field should be populated with 'SENDER_INFORMATION'.
              enum:
                - SENDER_INFORMATION
          additionalProperties: true
          description: Details on the package being returned.
    AnyValue:
      description: "Can be anything: string, number, array, object, etc. (except `null`)"
    BrandingPatchRequest:
      title: JSON Patch Request
      type: array
      description: "Request to update branding information for labels using JSON Patch. Refer to the IETF JSON PATCH specification at https://datatracker.ietf.org/doc/html/rfc6902 for detailed guidelines."
      xml:
        name: patchRequest
        wrapped: true
      items:
        required:
          - op
          - path
        type: object
        properties:
          op:
            type: string
            description: The operation to perform on the resource.
            enum:
              - replace
          path:
            type: string
            description: The object or array location to perform the update to the resource. Must be a JSON pointer value.
            example: /imageName
            enum:
              - /imageName
          value:
            type: string
            description: value of a branding patch request
            maxLength: 50
            pattern: "^\\w{1,50}$"
        additionalProperties: false
        xml:
          name: update
          wrapped: true
    PatchRequest:
      title: JSON Patch Request
      type: array
      description: "IETF JSON PATCH, https://datatracker.ietf.org/doc/html/rfc6902"
      xml:
        name: patchRequest
        wrapped: true
      items:
        required:
          - op
          - path
        type: object
        properties:
          op:
            type: string
            description: The operation to perform on the resource.
            enum:
              - replace
          path:
            type: string
            description: The object or array location to perform the update to the resource. Must be a JSON pointer value.
            example: /packageDescription/weight
            enum:
              - /packageDescription/weight
              - /packageDescription/length
              - /packageDescription/height
              - /packageDescription/width
              - /packageDescription/processingCategory
              - /packageDescription/girth
              - /packageDescription/rateIndicator
              - /packageDescription/containers
          value:
            $ref: '#/components/schemas/AnyValue'
        additionalProperties: false
        xml:
          name: update
          wrapped: true
    IndiciaRequest:
      title: Indicia Request
      required:
        - indiciaDescription
      type: object
      properties:
        indiciaDescription:
          $ref: '#/components/schemas/IndiciaRequestDescription'
        imageInfo:
          type: object
          properties:
            receiptOption:
              type: string
              description: |
                Indicia & Receipt print out options: Enter `SEPARATE_PAGE` to print the Indicia and the Receipt on separate pages. Enter `NONE` to print the Indicia only and no Receipt.
              default: NONE
              enum:
                - SEPARATE_PAGE
                - NONE
            imageType:
              type: string
              description: |
                The type of indicia image requested. If omitted then the default image type is PDF.
                 * 'PDF'
                 * 'TIFF'
                 * 'JPG'
                 * 'PNG'
                 * 'GIF'
                 * 'SVG'
              default: PDF
              enum:
                - PDF
                - TIFF
                - JPG
                - PNG
                - GIF
                - SVG
            labelType:
              type: string
              description: |
                Ability to select the indicia image size.  If omitted then the default indicia size is 2X1.5LABEL.
                - Using `2X1.5LABEL` will return the image in the `indiciaImage` response field.
                - Using `IMI_DATA_ONLY` will return the IMI data in the `indiciaIMI` response field and not populate the `indiciaImage` field.
              default: 2X1.5LABEL
              enum:
                - 2X1.5LABEL
                - IMI_DATA_ONLY
              example: "2X1.5LABEL"
          additionalProperties: false
          description: Additional details used to determine how to generate the indicia image.
      additionalProperties: true
      description: Indicia request for letters, flats, and cards First-Class mailings.
    IndiciaRequestDescription:
      title: Indicia Request Description
      description: |
        The `IndiciaRequestDescription` object defines the physical dimensions, mailing date, processing category, and weight required for processing a First-Class letter, flat, or card.
      required:
        - height
        - length
        - mailingDate
        - processingCategory
        - thickness
        - weight
      type: object
      properties:
        processingCategory:
          type: string
          description: |
            * LETTERS            
              
              To be eligible for mailing at the price for letters, a piece must be:
                * Rectangular
                * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.
                * No more than 6-1/8 inches high x 11-1/2 inches long x 1/4 inch thick.
            
              For additional information on letters, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Letters).
            
            * FLATS 
            
              The Postal Service uses the word "flats" to refer to large envelopes, newsletters, and magazines. The words large envelopes and flats are used interchangeably. Whatever you call them, flats must:
            
                * Have one dimension that is greater than 6-1/8 inches high OR 11-½ inches long OR ¼ inch thick.
                * Be no more than 12 inches high x 15 inches long x ¾ inch thick.
            
              For additional information on flats, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Flats).
            
            * CARDS 
            
              To be eligible for mailing at the price for postcards, a piece must be:
                * Rectangular
                * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.
                * No more than 4-1/4 inches high x 6 inches long x 0.016 inch thick.
            
              For additional information on postcards, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Cards).
          enum:
            - LETTERS
            - FLATS
            - CARDS
        weight:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: "The letter/flat/card weight, in ounces. The maximum weight of a letter or card is 3.5 oz and the maximum weight of a flat is 13 oz."
        mailingDate:
          $ref: '#/components/schemas/MailingDateIndiciaOptions'
        length:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card length in inches.  For  `LETTERS` and `CARDS` the length is the dimension parallel to the delivery address as read. For  `FLATS` the length is the longest dimension.
          format: double
        height:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card height in inches.  The height is the dimension perpendicular to the length.
          format: double
        thickness:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card thickness in inches. The minimum dimension is always the thickness.
          format: double
        nonMachinableIndicators:
          type: object
          description: Set of boolean indicators used to determine whether a letter qualifies as nonmachinable.
          properties:
            isPolybagged:
              type: boolean
              description: "Is the letter/flat/card polybagged, polywrapped, enclosed in any plastic material, or has an exterior surface made of a material that is not paper. Windows in envelopes made of paper do not make mailpieces nonmachinable. Attachments allowable under applicable eligibility standards do not make mailpieces nonmachinable."
              default: false
            hasClosureDevices:
              type: boolean
              description: "Does the letter/flat/card have clasps, strings, buttons, or similar closure devices."
              default: false
            hasLooseItems:
              type: boolean
              description: "Does the letter/flat/card contain items such as pens, pencils, keys, or coins that cause the thickness of the mailpiece to be uneven; or loose keys or coins or similar objects not affixed to the contents within the mailpiece. Loose items may cause a letter to be nonmailable when mailed in paper envelopes; (see [DMM 601.3.3](https://pe.usps.com/text/dmm300/601.htm#ep1196660))."
              default: false
            isRigid:
              type: boolean
              description: Is the letter/flat/card too rigid (does not bend easily when subjected to a transport belt tension of 40 pounds around an 11-inch diameter turn).
              default: false
            isSelfMailer:
              type: boolean
              description: "Is the letter/flat/card a self-mailer that is not prepared according to [DMM 201.3.14](https://pe.usps.com/text/dmm300/201.htm#ep1079302)."
              default: false
            isBooklet:
              type: boolean
              description: "Is the letter/flat/card a booklet that is not prepared according to [DMM 201.3.16](https://pe.usps.com/text/dmm300/201.htm#ep1092751)."
              default: false
          additionalProperties: false
        imiType:
          $ref: '#/components/schemas/IMIType'
    IndiciaResponse:
      title: Indicia Response
      type: object
      description: |
        The IndiciaResponse object contains metadata for the generated First-Class indicia.
      properties:
        indiciaMetadata:
          description: Metadata for the generated indicia.
          type: object
          properties:
            SKU:
              type: string
              description: Pricing SKU
              example: DFLL0XXXXR00010
            postage:
              type: number
              description: "Amount of postage required, does not include insurance or other extra service fees."
              example: 0.74
            fees:
              type: array
              description: Fees associated to the mailpiece.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the fee.
                    example: Nonmachinable letter fee
                  SKU:
                    type: string
                    description: Pricing SKU for the fee.
                    example: DX1F0XXLXRX0000
                  price:
                    type: number
                    description: The price for the fee.
                    format: float
                    example: 0.49
                additionalProperties: false
            weight:
              type: number
              description: "The mailpiece weight, in ounces."
              example: 0.1
            indiciaIMI:
              $ref: '#/components/schemas/IndiciaIMI'
        indiciaImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the indicia image.
          format: byte
        receiptImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the label receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.
          format: byte
      additionalProperties: false
    IndiciaImbRequest:
      title: Indicia IMB Request
      type: object
      description: "Indicia IMB request for letters, flats, and cards First-Class mailings."
      additionalProperties: false
      required:
        - indiciaDescription
        - toAddress
        - returnAddress
      properties:
        indiciaDescription:
          $ref: "#/components/schemas/IndiciaImbRequestDescription"
        imageInfo:
          $ref: "#/components/schemas/IndiciaImbImageInfo"
        toAddress:
          $ref: '#/components/schemas/IndiciaImbAddress'
        returnAddress:
          description: "The address where the letter, flat, or card is being mailed from.  Address elements streetAddress, city, state, ZIPCode are required.  First and Last Name or Firm are also required."
          allOf:
            - $ref: '#/components/schemas/IndiciaImbAddress'
    IndiciaImbRequestDescription:
      title: Indicia Request Description
      description: Indicia intelligent mail barcode request description
      additionalProperties: false
      required:
        - height
        - length
        - mailingDate
        - processingCategory
        - thickness
        - weight
      type: object
      properties:
        processingCategory:
          type: string
          description: |
            * LETTERS            
              
              To be eligible for mailing at the price for letters, a piece must be:
                * Rectangular
                * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.
                * No more than 6-1/8 inches high x 11-1/2 inches long x 1/4 inch thick.
            
              For additional information on letters, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Letters).
            
            * FLATS 
            
              The Postal Service uses the word "flats" to refer to large envelopes, newsletters, and magazines. The words large envelopes and flats are used interchangeably. Whatever you call them, flats must:
            
                * Have one dimension that is greater than 6-1/8 inches high OR 11-½ inches long OR ¼ inch thick.
                * Be no more than 12 inches high x 15 inches long x ¾ inch thick.
            
              For additional information on flats, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Flats).
            
            * CARDS 
            
              To be eligible for mailing at the price for postcards, a piece must be:
                * Rectangular
                * At least 3-1/2 inches high x 5 inches long x 0.007 inch thick.
                * No more than 4-1/4 inches high x 6 inches long x 0.016 inch thick.
            
              For additional information on postcards, please refer to the [Postal Explorer](https://pe.usps.com/businessmail101?ViewName=Cards).
          enum:
            - LETTERS
            - FLATS
            - CARDS
        weight:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: "The letter/flat/card weight, in ounces. The maximum weight of a letter and cards is 3.5 oz and the maximum weight of a flat is 13 oz."
        mailingDate:
          $ref: '#/components/schemas/MailingDateIndiciaOptions'
        length:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card length in inches.  For  `LETTERS` and `CARDS` the length is the dimension parallel to the delivery address as read. For  `FLATS` the length is the longest dimension.
          format: double
        height:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card height in inches.  The height is the dimension perpendicular to the length.
          format: double
        thickness:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: The letter/flat/card thickness in inches. The minimum dimension is always the thickness.
          format: double
        itemValue:
          maximum: 999999.99
          minimum: 0.01
          type: number
          description: |
            Value of the letter, flat, or card in USD.

            Note:
              * This value must be set if extra service codes 930 (Insurance) or 934 (Insurance (Restricted Delivery)) are in the extraServices field.
        extraServices:
          maxItems: 3
          minItems: 0
          type: array
          description: |
            Extra Service Code requested for IMB letters, flats, and cards.

              * 910 - Certified Mail
              * 911 - Certified Mail Restricted Delivery
              * 930 - Insurance
              * 934 - Insurance Restricted Delivery
              * 940 - Registered Mail
              * 941 - Registered Mail Restricted Delivery
              * 955 - Return Receipt
              * 957 - Return Receipt Electronic

            Note:
              * When the extra service code "930" is provided in the request, if the item value is over $500, "930" will automatically be replaced with "931" - Insurance (Greater than $500).
              * Some service codes require a combination with extra services such as "955" and "957". For all valid combinations, visit [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes).
          items:
            $ref: '#/components/schemas/IndiciaImbExtraService'
        nonMachinableIndicators:
          type: object
          description: Set of boolean indicators used to determine whether a letter qualifies as nonmachinable.
          properties:
            isPolybagged:
              type: boolean
              description: "Is the letter/flat/card polybagged, polywrapped, enclosed in any plastic material, or has an exterior surface made of a material that is not paper. Windows in envelopes made of paper do not make mailpieces nonmachinable. Attachments allowable under applicable eligibility standards do not make mailpieces nonmachinable."
              default: false
            hasClosureDevices:
              type: boolean
              description: "Does the letter/flat/card have clasps, strings, buttons, or similar closure devices."
              default: false
            hasLooseItems:
              type: boolean
              description: "Does the letter/flat/card contain items such as pens, pencils, keys, or coins that cause the thickness of the mailpiece to be uneven; or loose keys or coins or similar objects not affixed to the contents within the mailpiece. Loose items may cause a letter to be nonmailable when mailed in paper envelopes; (see [DMM 601.3.3](https://pe.usps.com/text/dmm300/601.htm#ep1196660))."
              default: false
            isRigid:
              type: boolean
              description: Is the letter/flat/card too rigid (does not bend easily when subjected to a transport belt tension of 40 pounds around an 11-inch diameter turn).
              default: false
            isSelfMailer:
              type: boolean
              description: "Is the letter/flat/card a self-mailer that is not prepared according to [DMM 201.3.14](https://pe.usps.com/text/dmm300/201.htm#ep1079302)."
              default: false
            isBooklet:
              type: boolean
              description: "Is the letter/flat/card a booklet that is not prepared according to [DMM 201.3.16](https://pe.usps.com/text/dmm300/201.htm#ep1092751)."
              default: false
        imiType:
          $ref: '#/components/schemas/IMIType'
    IndiciaImbResponse:
      title: Indicia IMB Response
      type: object
      properties:
        indiciaMetadata:
          type: object
          description: Metadata for indicia
          properties:
            imb:
              type: string
              description: "Human-readable form of the intelligent mail barcode (IMB) value."
              example: "00700123456000000001200669998"
            constructCode:
              type: string
              description: |
                The barcode construct code associated with the tracking number.

                Notes:
                  - This field will be absent from the response if the request does not include extra services.
              example: "C08"
            trackingNumber:
              type: string
              description: |
                Human-readable form of the intelligent mail package barcode (IMPB) value.

                Notes:
                  - This field will be absent from the response if the request does not include extra services.
              example: "9307109876500000000010"
            SKU:
              type: string
              description: Pricing SKU
              example: DFLL0XXXXR00010
            totalPrice:
              type: number
              description: "Total price of the indicia, including postage and any fees."
              format: float
              example: 1.23
            postage:
              type: number
              description: "Amount of postage required, does not include insurance or other extra service fees."
              example: 0.74
            fees:
              type: array
              description: Fees associated to the mailpiece.
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the fee.
                    example: Nonmachinable letter fee
                  SKU:
                    type: string
                    description: Pricing SKU for the fee.
                    example: DX1F0XXLXRX0000
                  price:
                    type: number
                    description: The price for the fee.
                    format: float
                    example: 0.49
                additionalProperties: false
            weight:
              type: number
              description: "The mailpiece weight, in ounces."
              example: 0.1
            extraServices:
              $ref: '#/components/schemas/ExtraServiceResponse'
            serviceTypeCode:
              type: string
              description: |
                The Service Type Code associated with the mailpiece. A list of Service Type Codes can be found at: [https://postalpro.usps.com/IMPB_Service_Type_Codes](https://postalpro.usps.com/IMPB_Service_Type_Codes)
              example: "154"
            bannerText:
              type: string
              description: Banner text printed on the label.
              example: "USPS CERTIFIED MAIL™"
            mailClass:
              enum:
                - FIRST-CLASS
              description: The mail class of the indicia.
              example: FIRST-CLASS
            toAddress:
              description: The `toAddress` from the request that will be printed on the letter, flat, or card.
              allOf:
                - $ref: '#/components/schemas/IndiciaImbAddress'
            returnAddress:
              description: The `returnAddress` from the request that will be printed on the letter, flat, or card.
              allOf:
                - $ref: '#/components/schemas/IndiciaImbAddress'
            indiciaIMI:
              $ref: '#/components/schemas/IndiciaIMI'
        indiciaImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the indicia image. Provided only when `imageInfo.labelType` is not `IMI_DATA_ONLY`.
          format: byte
        receiptImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the indicia receipt image. Provided only when `imageInfo.receiptOption` is `SEPARATE_PAGE`.
          format: byte
      additionalProperties: false
    IndiciaIMI:
      title: Indicia IMI
      description: Base64 encoded string of the binary data used to create the Intelligent Mail Indicia (IMI) Data Matrix.
      type: string
      format: byte
      example: cjAwMDABAAAAVH+OkjNsBwDwATUBFACxbE0EAAAAAAAAAAAAAAAAzYEBAAAAWQKWI0dz/SOoaxEQfHYxdPXV6DhvxLEdR7mZ/LpTCndrMOr1zoUtknfVVvMJxAr98pbJvNQmFO6jcmWMvF5oIQ==
    ExtraServiceResponse:
      title: Extra Service Response
      type: array
      minItems: 0
      description: Extra services requested on the mailpiece.
      items:
        type: object
        properties:
          name:
            type: string
            description: Name of the extra service.
            example: Certified Mail Restricted Delivery
          SKU:
            type: string
            description: SKU of the extra service.
            example: "DXEX0XJXXRX0000"
          price:
            type: number
            description: The price for the extra service.
            format: float
            example: 13.7
          warnings:
            type: array
            description: Warnings and additional details around the Extra Services.
            minItems: 0
            items:
              type: object
              properties:
                warningCode:
                  type: string
                  description: Code corresponding to the warning
                  example: "003"
                warningDescription:
                  type: string
                  description: Warning or additional information regarding the Extra Service.
                  example: "Extra service may not be available for this destination"
              additionalProperties: false
            example:
              - warningCode: "001"
                warningDescription: "Contract rate not found for request. Published rate returned."
              - warningCode: "003"
                warningDescription: "Collect on Delivery fees paid via cash require an additional Money Order fee of $2.55."
        additionalProperties: false
    IndiciaImbExtraService:
      title: Indicia Extra Service Codes
      type: integer
      description: |
        Extra Service Code requested for IMB letters, flats, and cards.
        
          * 910 - Certified Mail
          * 911 - Certified Mail Restricted Delivery
          * 930 - Insurance
          * 934 - Insurance Restricted Delivery
          * 940 - Registered Mail
          * 941 - Registered Mail Restricted Delivery
          * 955 - Return Receipt
          * 957 - Return Receipt Electronic

        Note:
          * When the extra service code "930" is provided in the request, if the item value is over $500, "930" will automatically be replaced with "931" - Insurance (Greater than $500).
      enum:
        - 910
        - 911
        - 930
        - 934
        - 940
        - 941
        - 955
        - 957
    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
              description: List of Errors
              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.
    PackageDescription:
      title: Package Description
      type: object
      properties:
        weightUOM:
          type: string
          description: |-
            Weight Unit of Measurement
              * lb - Pounds
          default: lb
          enum:
            - lb
        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."
        dimensionsUOM:
          type: string
          description: |
            Dimensions unit of measure
            * in - Inches
          default: in
          enum:
            - in
        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, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and 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, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and 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, and Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. Girth is required only for a non-rectangular package in addition to Length, Width, and Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages."
        girth:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: "The girth of the container, in dimensionsUOM. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non- rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages."
        hasNonstandardCharacteristics:
          default: false
          type: boolean
          description: "Package is nonstandard. Nonstandard packages include cylindrical tubes and rolls, certain high-density items, cartons containing more than 24 ounces of liquids in one or more glass containers, cartons containing 1 gallon or more of liquid in metal or plastic containers, and items in [201.7.6.2](https://pe.usps.com/text/dmm300/201.htm#7.6.2)."
      additionalProperties: true
      description: Package Definitions
    DomesticAddress:
      title: Domestic Address
      additionalProperties: true
      description: Address fields for US locations
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            city:
              maxLength: 28
              minLength: 1
              type: string
              description: This is the city name of the address.
              example: WASHINGTON
            state:
              $ref: '#/components/schemas/State'
            ZIPCode:
              pattern: "^\\d{5}$"
              type: string
              description: This is the 5-digit ZIP code.
              example: "20260"
            ZIPPlus4:
              pattern: "^\\d{4}$"
              type: string
              description: This is the 4-digit component of the ZIP+4 code. Using the correct Zip+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error.
              nullable: true
              example: "0010"
            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.
          example: 475 L'Enfant Plaza SW
        streetAddressAbbreviation:
          maxLength: 50
          minLength: 0
          type: string
          description: This is the abbreviation of 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 city name for the address.
          readOnly: true
      additionalProperties: true
      description: Address fields standard to all locations.
    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 the two-character state code of the address.
      example: DC
    MailingDate:
      type: string
      description: |
        The date the package will be mailed.
        
        The mailing date may be today plus 0 to 7 days in advance.
        
        The time will default to 10 p.m. local time (based on the induction location of the package) for calculating the commitment and scheduled delivery date of the package.
        
        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
      example: "2025-01-01"
    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
      example: "2025-01-01T08:30:00Z"
    MailingDateIndiciaOptions:
      type: string
      description: Mailing Date Indicia Options
      oneOf:
        - $ref: '#/components/schemas/MailingDateIndicia'
        - $ref: '#/components/schemas/MailingDateTimeIndicia'
    MailingDateIndicia:
      type: string
      description: "The date the letter, flat, or card 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
      example: "2025-01-01"
    MailingDateTimeIndicia:
      type: string
      description: "The date and time the letter, flat, or card 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
      example: "2025-01-01T08:30:00Z"
    InductionZIPCode:
      pattern: "^\\d{5}$"
      type: string
      description: The 5-Digit ZIP Code representing the location where the package is being inducted (i.e. dropped off) into the mailstream.  When provided, this ZIP Code will be used for pricing instead of `fromAddress.ZIPCode`.  
    PackageOptions:
      title: Package Options
      type: object
      properties:
        packageValue:
          minimum: 0
          type: number
          description: |
            The merchandise value of the package, in US dollars. Used to calculate Insurance Fees if requested.

            Note:
             * Requires extraServiceCode 910, 911, 912, 913, 921, 922, 923, 924, 925, 934, 955, 981 or extraServiceCode 930 with a packageValue greater than 500
             * Package value is required when an 'extraServiceCode' value of '930' is provided.
          example: 35
        nonDeliveryOption:
          type: string
          description: |-
            Requested action in the case a package is undeliverable:
              - `RETURN` for package to be returned to `fromAddress`.
              - `REDIRECT` to return package to address specified in the `redirectAddress`.
              - `ABANDON` to dispose of undeliverable package
            
            Note:
              * `REDIRECT` and `ABANDON` will not impact the domestic package endpoint. Please use ancillary service endorsements instead.
              * An address must be provided in `redirectAddress` when a value of `REDIRECT` is provided.
          enum:
            - RETURN
            - REDIRECT
            - ABANDON
        omas:
          type: object
          description: Fields specific to Official Mail Accounting System (OMAS).  Used for Federal Agencies.
          properties:
            chargebackCode:
              type: string
              maxLength: 6
              pattern: "^[A-Za-z0-9]{1,6}$"
              example: "123456"
              description: Code used with OMAS transactions.
      additionalProperties: true
    IndiciaImbAddress:
      title: Indicia IMB Domestic Label Address
      required:
        - ZIPCode
        - city
        - state
        - streetAddress
      type: object
      additionalProperties: true
      description: "The address where the letter, flat, or card is being mailed to. Address elements streetAddress, city, state, ZIPCode are required.  First and Last Name or Firm are also required."
      allOf:
        - $ref: '#/components/schemas/DomesticAddress'
        - $ref: '#/components/schemas/Addressee'
        - type: object
          properties:
            ignoreBadAddress:
              writeOnly: true
              type: boolean
              description: |
                Allows Non-Validated Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.
                
                Note: Integrators are recommended to always use `false` to ensure no delivery issues. 
                
                In the event USPS cannot validate the street address, this tag will "bypass" address validation error when `true` is indicated to allow IMB indicia creation which could impact delivery.
          additionalProperties: true
    DomesticLabelAddress:
      title: Domestic Label Address
      required:
        - ZIPCode
        - city
        - state
        - streetAddress
      type: object
      additionalProperties: true
      description: |
        The address where the package is being shipped from. The ZIP Code™ in the `fromAddress` object is used to calculate pricing. 
        
        Notes:
        * The First and Last Name or Firm Name are always required.
        * If the `returnAddress` is not provided, the `fromAddress` will be used as the `returnAddress`.
        * If the `returnLabel` field is set to “true”, then the `fromAddress` ZIP Plus 4 is looked up by the API, unless the `ignoreBadAddress` field is set to true or the address cannot be found. If `ignoreBadAddress` field is true then ZIP Plus 4 is required.
      allOf:
        - $ref: '#/components/schemas/DomesticAddress'
        - $ref: '#/components/schemas/Addressee'
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/Phone'
            email:
              $ref: '#/components/schemas/Email'
            ignoreBadAddress:
              type: boolean
              description: |
                Allows Non-Validated Origin Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.
                
                Note: Integrators are recommended to always use `false` to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when `true` is indicated to allow label creation which could impact delivery.
          additionalProperties: true
    Addressee:
      title: Addressee
      type: object
      properties:
        firstName:
          maxLength: 50
          minLength: 1
          type: string
          description: First Name corresponding to the address.
        lastName:
          maxLength: 50
          minLength: 1
          type: string
          description: Last Name corresponding to the address.
        firm:
          maxLength: 50
          minLength: 0
          type: string
          description: Firm/business name corresponding to the address.
      additionalProperties: true
      description: Fields used to identity the entity receiving a mail piece or package
    Phone:
      pattern: "^\\+?[1-9][0-9]{7,14}$|^[0-9]{6,15}$"
      type: string
      description: "The phone number, including the country extension and area code or the local national format, with no punctuation."
    IMIType:
      type: string
      enum:
        - IMI_MIN
        - IMI_STD
        - IMI_MAX
      default: IMI_STD
      example: IMI_MIN
      description: The type of Intelligent Mail Indicia (IMI) to be generated.  The default option is `IMI_STD`.  The `imiType` can be changed only when `imageInfo.labelType` is set to `IMI_DATA_ONLY`.
    Email:
      maxLength: 50
      pattern: "^[a-zA-Z0-9_+&*-]+(?:\\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$"
      type: string
      description: 'Email address used for redirect notification via email. '
      format: email
    CustomerReference:
      title: Customer Reference
      description: Customer Reference
      type: object
      properties:
        referenceNumber:
          maxLength: 30
          minLength: 1
          type: string
          description: |
            A user-assigned number for internal use, such as Order, Invoice, Customer, or Return Merchandise Authorization Numbers. 
            
            Note:
            * Domestic outbound label and return label with `labelType` of `4X6LABEL` will display the entire value.
            * Return label with `labelType` of `4X6LABEL` with `brandingImageFormat` of `TWO_SQUARES` will show the first 25 characters.
            * For all other label formats, only a maximum of 18 characters will be shown on the shipping label.
            * These values will also be included in the Shipping Services File.
      additionalProperties: true
    CustomsForm:
      title: Customs Form
      type: object
      properties:
        contentComments:
          maxLength: 25
          type: string
          description: Required when customContentType is OTHER.
        restrictionType:
          type: string
          description: |-
            Restriction Types
              * QUARANTINE
              * SANITARY_INSPECTION
              * PHYTOSANITARY_INSPECTION
              * OTHER
          enum:
            - QUARANTINE
            - SANITARY_INSPECTION
            - PHYTOSANITARY_INSPECTION
            - OTHER
        restrictionComments:
          maxLength: 25
          type: string
          description: Restriction Comments.  Required when `restrictionType`=`OTHER`.
        AESITN:
          maxLength: 35
          minLength: 1
          type: string
          description: |
            AES/ITN Exemption should be populated with the electronic export internal transaction number (if required), or the appropriate Exemption/Exclusion Legend.

            * **AES - Automated Export System /   ITN - Internal Transaction Number**\
              The [internal transaction number (ITN)](https://pe.usps.com/text/imm/immc5_010.htm) is a 14-digit number that corresponds to an export transaction in the Automated Export System. It serves as proof that an exporter met his or her legal obligation to inform the U.S. government about the details of an export shipment.
            * **EEL- Exemptions, Exclusions, Legend**\
              An [AES exemption](https://pe.usps.com/text/imm/immc5_012.htm) is an instance in which you would not have to file in AES to get the 14-digit ITN. Instead of the ITN, you would enter the exemption’s section in the U.S. Foreign Trade Regulations on the export documentation where you would otherwise put the ITN.

            Sample - `NO EEI 30.37(a)`: Shipments valued at $2,500 or less.
          example: "NO EEI 30.37(a)"
        invoiceNumber:
          maxLength: 15
          minLength: 1
          type: string
          description: Invoice Number
        licenseNumber:
          maxLength: 16
          minLength: 1
          type: string
          description: License Number
        certificateNumber:
          maxLength: 12
          minLength: 1
          type: string
          description: Certificate Number
      additionalProperties: true
      description: |-
        Additional details required when creating shipments originating from or destinating to MPOs, APOs, FPOs, or DPOs (Military, Army, Fleet, and Diplomatic Post Offices) and some Military and U.S. Possessions, Territories, and Freely Associated States (PTFAS).
        Required only if a customs form is required based on Customs Content Type and Weight.
        
        Note:
          - Mail addressed to military and diplomatic post offices overseas is subject to certain conditions or restrictions of mailing regarding content, preparation, and handling. The APO/FPO/DPO table may be found on the most recent [postal bulletin](https://about.usps.com/resources/postal-bulletin.htm) found under `Pull-Out information` -> `Other Information` -> `Overseas Military/Diplomatic Mail`
    ShippingContents:
      title: Customs Form Package Contents
      type: object
      properties:
        itemDescription:
          maxLength: 30
          minLength: 1
          type: string
          description: |
            Description of the item.  It is important to note that the following descriptions, regardless of case sensitivity, are not considered valid: None, Not Applicable, N/A, Null, Gift, and Merchandise.
          example: Policy guidelines document
        itemQuantity:
          maximum: 9999
          minimum: 1
          type: integer
          description: Quantity of the item. Integer value required.
          example: 1
        itemValue:
          maximum: 999999.99
          minimum: 0.01
          type: number
          description: |
            Value of the individual item in USD.

            Note:
            * This field has been deprecated in favor of `itemTotalValue` and will be removed in a future release. Please transition to using `itemTotalValue`.
          example: 1
          deprecated: true
        itemTotalValue:
          maximum: 999999.99
          minimum: 0.01
          type: number
          description: |
            The total item value, in USD, of the items matching the `itemDescription`.
          example: 1
        weightUOM:
          type: string
          description: |-
            Weight Unit of Measurement
              * lb - Pounds
          default: lb
          enum:
            - lb
        itemWeight:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: |
            Provide the weight in `weightUOM` for the individual item listed with `itemDescription`.

            Note:
            * This field has been deprecated in favor of `itemTotalWeight` and will be removed in a future release. Please transition to using `itemTotalWeight`.
          example: 1.0001
          deprecated: true
        itemTotalWeight:
          minimum: 0
          exclusiveMinimum: true
          type: number
          description: |
            Provide the total weight in `weightUOM` for the all items matching the `itemDescription`.
          example: 1.0001
        HSTariffNumber:
          maxLength: 14
          minLength: 6
          type: string
          description: |
            For commercial items only. The HS tariff number is based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. 
            Providing this value is strongly recommended for faster processing. If not supplied, USPS will attempt to look up the HS tariff number, which may result in longer response times.
            The value should follow the pattern: `^\.*(?:[A-Za-z\d]\.*){6,14}$`.
            For more information, see: [https://hts.usitc.gov/current](https://hts.usitc.gov/current).
        countryofOrigin:
          pattern: "[A-Z]{2}"
          type: string
          description: 2 digit Alpha Country Code defined by ISO is required for international address.
        itemCategory:
          type: string
          description: Category of the item being shipped.
        itemSubcategory:
          type: string
          description: Subcategory of the item being shipped.
      additionalProperties: true
      description: "Required repeating up to 30 times if generating an Integrated Customs Form, otherwise not required."
    DomesticLabelToAddress:
      title: Domestic Label To Address
      type: object
      additionalProperties: true
      description: |-
        The address where the package is being shipped to. The ZIP Code™ in the `toAddress` object is used to calculate pricing.
        
        Notes:
        * The First and Last Name or Firm are always required.
        * Address elements `streetAddress`, `city`, `state`, `ZIPCode` are required unless a parcel locker is requested in which case the `facilityId`, Recipient Email, First and Last Name or Firm are required.
        * If the `holdForPickup` field is set to `true` then the `toAddress` object `facilityID`, `email`, and `phone` fields as well as the `fromAddress` object `firstName`, `lastName`, `email`, and `phone` fields are required.
      allOf:
        - $ref: '#/components/schemas/DomesticAddress'
        - $ref: '#/components/schemas/Addressee'
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/Phone'
            email:
              $ref: '#/components/schemas/Email'
            ignoreBadAddress:
              type: boolean
              description: |
                Allows Non-Validated Destination Street Address. Enter `true` to bypass street address validation failures/errors or `false` if only validated addresses should be allowed.
                
                Note: Integrators are recommended to always use `false` to ensure no delivery issues. 
                
                In the event USPS cannot validate the street address, this tag will “bypass” address validation error when `true` is indicated to allow label creation which could impact delivery.
  
                This will automatically be set to `false` if extra service code `415 - USPS Label Delivery` is requested.
            parcelLockerDelivery:
              type: boolean
              description: |
                Indicator to request delivery to a parcel locker instead of the recipient's address. If this field is set as true then the facilityId, email, and firstName/lastName or firm fields are required.

                Note:
                * Packages that require customs forms are not eligible to be shipped to a Smart Locker. Parcel lockers are not eligible for Hold for Pickup shipments.
              default: false
            holdForPickup:
              type: boolean
              description: "Indicator to request Hold for Pickup at a Post Office Facility. If this field is set as true then the `toAddress` object: 'facilityID', 'email', and 'phone' as well as the `fromAddress` object: 'firstName',  'lastName', 'email', and 'phone' fields are required."
              default: false
            facilityId:
              maxLength: 7
              type: string
              description: Facility ID is required when generating a label for parcel locker delivery or Hold for Pickup. The Facility ID is obtained from the API response in the /post-office-locator API.
          additionalProperties: true
    DomesticLabelSenderAddress:
      title: Domestic Label Sender Address
      required:
        - ZIPCode
        - city
        - state
        - streetAddress
      type: object
      additionalProperties: true
      description: |-
        The address of the business involved. The senderAddress can be different from the fromAddress when the business address is not where the package is being shipped from.
       
        Notes:
        - The First and Last Name or Firm Name are always required.
        - `senderAddress` is required when the `shipperVisibilityMethod` field is set to `SENDER_INFORMATION`.
      allOf:
        - $ref: '#/components/schemas/DomesticLabelAddress'
        - $ref: '#/components/schemas/Addressee'
        - type: object
          properties:
            platformUserId:
              maxLength: 30
              type: string
              description: This is a third-party unique identifier for the sender used for correlation purposes.
          additionalProperties: true
    Links:
      title: Hypermedia Links
      type: array
      description: Hypermedia links to related resources.
      items:
        required:
          - href
          - rel
        type: object
        properties:
          rel:
            type: array
            description: The short name(s) of the relationship corresponding to the link.
            items:
              type: string
          title:
            type: string
            description: A human-readable description of the link relationship.
          href:
            type: string
            description: The URL to a related resource.
            format: uri
          method:
            type: string
            description: The HTTP method to use to access this link.
            enum:
              - GET
              - POST
              - PUT
              - DELETE
          submissionMediaType:
            type: string
            description: The media type of the resource request.
          targetMediaType:
            type: string
            description: The media type of the resource response.
        additionalProperties: false
    LabelBrandingUploadRequest:
      title: Label Branding Image Upload Request
      description: Label Branding Image Upload Request
      type: object
      required:
        - imageData
      properties:
        imageName:
          type: string
          maxLength: 50
          pattern: "^\\w{1,50}$"
          description: |
            An optional descriptor for the image. 
            
            Additional requirements: 
            * No special characters or spaces
            * No more than 50 characters in length
          example: LogoOfCircle
        imageData:
          type: string
          minLength: 1
          maxLength: 13336
          pattern: "^[A-Za-z0-9+/=]+$"
          description: The plaintext contents of an .svg file base64 encoded. The image must be less than 10kb in size.
          example: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
      additionalProperties: false
    LabelBrandingUploadResponse:
      title: Label Branding Image Upload Response
      description: Label Branding Image Upload Response
      type: object
      properties:
        imageUUID:
          type: string
          description: The auto generated UUID of the image that was successfully uploaded.
          example: "345df38d-6130-4ad1-838c-8883af55c584"
        imageName:
          type: string
          description: The name of the image that was successfully uploaded.
          example: "LogoOfCircle"
      additionalProperties: false
    LabelBrandingDeleteResponse:
      title: Label Branding Image Delete Response
      description: Label Branding Image Delete Response
      type: object
      properties:
        imageName:
          type: string
          description: The name of the image that was successfully deleted.
          example: "LogoOfCircle"
        imageUUID:
          type: string
          description: The UUID of the image that was successfully deleted.
          example: "345df38d-6130-4ad1-838c-8883af55c584"
      additionalProperties: false
    LabelBrandingPatchResponse:
      title: Label Branding Image Patch Response
      description: Label Branding Image Patch Response
      type: object
      properties:
        imageUUID:
          type: string
          description: The UUID of the image that was successfully renamed.
          example: "345df38d-6130-4ad1-838c-8883af55c584"
        imageName:
          type: string
          description: The name of the image that was successfully renamed.
          example: "newImageName"
        createdDateTime:
          type: string
          format: date-time
          description: The time that the image was created.
          example: "2023-10-30T18:00:00Z"
        imageData:
          type: string
          description: The base64 image data associated with your image.
          example: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
      additionalProperties: false
    LabelBrandingGetListResponse:
      title: Label Branding Get List of Images Response with pagination
      type: object
      properties:
        images:
          type: array
          description: List of all label branding image names associated with the USPS Customer Registration ID (CRID).
          items:
            type: object
            properties:
              imageUUID:
                type: string
                description: UUID of the image. Used in Domestic Labels and Return Labels requests to apply an image to a label.
                example: "345df38d-6130-4ad1-838c-8883af55c584"
              imageName:
                type: string
                description: The descriptor text that was optionally associated with the image when the image was created.
                example: "LogoOfCircle"
              createdDateTime:
                type: string
                format: date-time
                description: The datetime that the image was created.
                example: "2023-10-30T18:00:00Z"
              imageData:
                type: string
                description: The base64 image data associated with your image.
                example: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
            additionalProperties: false
        limit:
          type: integer
          description: Current limit on number of included results.
          example: 1
        offset:
          type: integer
          description: Number of items skipped.
          example: 3
        totalCount:
          type: integer
          description: Total number of items.
          example: 2
      description: Paginated response schema for getting a list of label branding images.
    LabelBrandingGetImageResponse:
      title: Label Branding Get Image Response
      type: object
      properties:
        imageUUID:
          type: string
          description: UUID of the image. Used in Domestic Labels and Return Labels requests to apply an image to a label.
          example: "345df38d-6130-4ad1-838c-8883af55c584"
        imageName:
          type: string
          description: The descriptor text that was optionally associated with the image when the image was created.
          example: "LogoOfCircle"
        imageData:
          type: string
          description: The base64 image data associated with your image.
          example: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
        createdDateTime:
          type: string
          format: date-time
          description: The time that the image was created.
          example: "2023-10-30T18:00:00Z"
      additionalProperties: false
      description: Response schema for getting a single label branding image.
    LabelReprintRequest:
      title: Label Reprint Request
      type: object
      properties:
        imageInfo:
          $ref: '#/components/schemas/LabelReprintImageInfo'
      additionalProperties: false
      description: Request schema for reprinting a domestic label.
    LabelReprintMultiPartResponse:
      title: Label Reprint Multipart response. `labelMetadata` and `labelImage` are returned for outbound label reprint requests. `returnLabelMetadata` and `returnLabelImage` are returned for return label reprint requests.
      description: Label Reprint Multipart response. `labelMetadata` and `labelImage` are returned for outbound label reprint requests. `returnLabelMetadata` and `returnLabelImage` are returned for return label reprint requests.
      type: object
      properties:
        labelMetadata:
          $ref: '#/components/schemas/LabelMetadata'
        returnLabelMetadata:
          $ref: '#/components/schemas/ReturnLabelMetadata'
        labelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the label image.
          format: byte
        returnLabelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return label image.
          format: byte
        reprintInfo:
          $ref: '#/components/schemas/ReprintInfo'
      additionalProperties: false
    LabelReprintDomesticOutboundResponse:
      title: Outbound Label Reprint Response
      type: object
      properties:
        labelMetadata:
          $ref: '#/components/schemas/LabelMetadata'
        labelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the label image.
          format: byte
        reprintInfo:
          $ref: '#/components/schemas/ReprintInfo'
      additionalProperties: false
      description: Response schema for outbound label reprint requests.
    LabelReprintDomesticReturnResponse:
      title: Return Label Reprint Response
      type: object
      properties:
        returnLabelMetadata:
          $ref: '#/components/schemas/ReturnLabelMetadata'
        returnLabelImage:
          type: string
          description: |
            Contains the Base64-encoded file contents of the return label image.
          format: byte
        reprintInfo:
          $ref: '#/components/schemas/ReprintInfo'
      additionalProperties: false
      description: Response schema for return label reprint requests.
    ReprintInfo:
      title: Reprint Info
      type: object
      properties:
        reprintNumber:
          type: integer
          description: "Count of reprints made for the label."
          format: byte
        reprintLimit:
          type: integer
          description: "Maximum number of reprints permitted for the label."
          format: byte
      additionalProperties: false
      description: Schema containing reprint information for a label.
    LabelReprintImageInfo:
      title: Label Reprint Image Info
      description: Label Reprint 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:
            - Labels with customs forms only support formats of `PDF`, `TIFF`, `ZPL203DPI`, and `ZPL300DPI`.
          default: PDF
          enum:
            - PDF
            - TIFF
            - JPG
            - PNG
            - GIF
            - SVG
            - ZPL203DPI
            - ZPL300DPI
            - EPL300DPI
        labelType:
          type: string
          description: |
            Ability to select the label image size. If omitted then the default label size is `4X6LABEL`.

            Note:
              * Currently, customs forms only support `4X6LABEL`.
              * The `labelType` of `2X7LABEL` is not supported with the `imageType` of `ZPL203DPI` or `ZPL300DPI`.
              * The `labelType` of `4X6LABEL` is the only supported format with the `imageType` of `EPL300DPI`.
          default: 4X6LABEL
          enum:
            - 4X4LABEL
            - 4X5LABEL
            - 4X6LABEL
            - 6X4LABEL
            - 2X7LABEL
        suppressPostage:
          type: boolean
          description: |
            Indicates if postage is printed on the label. If omitted then the request will be defaulted to true.
          default: true
        suppressMailDate:
          type: boolean
          description: |
            Indicates if the `mailingDate` is printed on the label.  If omitted then the value will default to true.

            Note:
             * Mail Date cannot be suppressed on Domestic Customs Forms. The customs form will always display the Date of Mailing.
             * The date the label was created cannot be suppressed and will always print on the label.
          default: true
        brandingImageFormat:
          type: string
          description: |
            The format of label branding images to be shown on the generated label image.

            Note:
            * Label branding images will not be shown on labels with customs forms.
            * Label branding images are not currently supported with an `imageType` of `ZPL203DPI`, `ZPL300DPI`, or `EPL300DPI`.
            * Label branding images are not currently supported with a `labelType` of `4X4LABEL`.
            * When a `brandingImageFormat` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.
            * When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference #3-#4 cannot be provided since they will not be shown.
            * When a `brandingImageFormat` of `ONE_SQUARE` or `TWO_SQUARES` is provided, Customer Reference numbers will be shifted to the right to accommodate the image.
            * When a `brandingImageFormat` of `RECTANGLE` is provided, Customer Reference numbers, package number, and total packages will not be displayed on the label.
            * A `brandingImageFormat` of `ONE_SQUARE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, `6X4LABEL`, and `2X7LABEL` for both outbound and return labels.
            * A `brandingImageFormat` of `TWO_SQUARES` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for both outbound and return labels.
            * A `brandingImageFormat` of `RECTANGLE` is currently only supported with `labelType` of `4X6LABEL`, `4X5LABEL`, and `6X4LABEL` for outbound labels and `4X5LABEL` and `6X4LABEL` for return labels.
          default: NONE
          enum:
            - ONE_SQUARE
            - TWO_SQUARES
            - RECTANGLE
            - NONE
        brandingImageUUIDs:
          type: array
          maxItems: 2
          minItems: 0
          default: [ ]
          description: |
            The UUIDs associated with custom images uploaded in the Logo Branding endpoint: /branding

            Note:
            * These UUIDs must have been created with the same Payment Authorization Label Owner CRID in use when creating the label
            * When using `ONE_SQUARE` or `RECTANGLE` the brandingImageUUIDs list should include only one imageUUID string.
            * When using `TWO_SQUARES` the brandingImageUUIDs list should include only two imageUUID strings.
          example: [ "345df38d-6130-4ad1-838c-8883af55c584" ]
          items:
            maxLength: 36
            minLength: 36
            pattern: "[A-Fa-f0-9]{8}-([A-Fa-f0-9]{4}-){3}[A-Fa-f0-9]{12}"
            type: string
        packageNumber:
          maximum: 9999
          minimum: 1
          type: integer
          description: |-
            The package number in a series such as 1 of 3, 2 of 3, etc.  If `totalPackages` is populated then `packageNumber` is required.  `packageNumber` must be less than or equal to `totalPackages`.  This feature is not supported on the 2x7 or 4x4 label format.
            
            Note:
            * When `packageNumber` is provided with a Destination Entry Facility, the Drop-Off Location will not be displayed on the label.
        totalPackages:
          maximum: 9999
          minimum: 1
          type: integer
          description: The total number of packages in a series such as 999.  If packageNumber is populated then totalPackages is required.  totalPackages must be greater than or equal to packageNumber.  This feature is not supported by the 2x7 or 4x4 label format.
  parameters:
    TrackingNumber:
      name: trackingNumber
      in: path
      description: The tracking number of the domestic label.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    IMB:
      name: imb
      in: path
      description: The Intelligent Mail Barcode (IMB) for First-Class letters, flats, and cards.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        example: "00700123456000000001200669998"
        minLength: 20
        maxLength: 31
    LabelBrandingImageUUID:
      name: imageUUID
      in: path
      description: The UUID of a label branding image
      required: true
      style: simple
      explode: false
      schema:
        type: string
      example: "345df38d-6130-4ad1-838c-8883af55c584"
    X-Payment-Authorization-Token:
      name: X-Payment-Authorization-Token
      in: header
      description: |
        Payment Authorization Token from the payments API Call.
      required: true
      schema:
        type: string
      example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6I kpvaG4gRG9lIiwiYWRtaW4iOmZhbHNlfQ.gWDlJdpCTIHVYKkJSfAVNUn0ZkAjMxskDDm-5Fhe WJ7xXgW8k5CllcGk4C9qPrfa1GdqfBrbX_1x1E39JY8BYLobAfAg1fs_Ky8Z7U1oCl6HL63yJq_ wVNBHp49hWzg3-ERxkqiuTv0tIuDOasIdZ5FtBdtIP5LM9Oc1tsuMXQXCGR8GqGf1Hl2qv8MCyn NZJuVdJKO_L3WGBJouaTpK1u2SEleVFGI2HFvrX_jS2ySzDxoO9KjbydK0LNv_zOI7kWv-gAmA j-v0mHdJrLbxD7LcZJEGRScCSyITzo6Z59_jG_97oNLFgBKJbh12nvvPibHpUYWmZuHkoGvuy5RLUA
    X-Idempotency-Key:
      name: X-Idempotency-Key
      in: header
      description: |
        A unique UUID that serves as an idempotency key for safe request retries and duplicate charge prevention during label creation.
        This value must be a randomly generated UUID and unique per customer (CRID) across all label creation requests.
        When the same idempotency key is resubmitted with an identical request payload, the API will return the existing label without creating a duplicate or charging additional postage.
        The UUID will be included in the electronic manifest data (Shipping Services File D5 field) sent to Postal systems.
      required: false
      schema:
        type: string
        format: uuid
      example: 8be4df61-93ca-11d2-aa0d-00e098032b8c
  examples:
    ExampleCancel_CANCELED:
      summary: Canceled Label
      description: Cancel Label Response for a label that has been successfully canceled.
      value:
        trackingNumber: "9262593519935271903671"
        status: CANCELED
    ExampleCancel_REFUND:
      summary: Refund Request Submitted
      description: Cancel Label response for a label that was manifested and now has a refund request submitted.
      value:
        trackingNumber: "9262593519935271903671"
        status: DISPUTED
        disputeId: "103789"
    ExampleCancelError_NOTFOUND:
      summary: Label Not found
      description: Cancel Label error response for a label that cannot be found.
      value:
        apiVersion: /labels/v3
        error:
          code: "400"
          message: Bad Request
          errors:
            - title: Bad Request
              detail: Order not found
              code: 00000XX
              source:
                parameter: trackingNumber
    ExampleIMBCancel_CANCELED:
      summary: Canceled IMB
      description: Cancel IMB response for an IMB that has been successfully canceled.
      value:
        imb: "00700123456000000001200669998"
        status: CANCELED
    ExampleIMBCancel_DISPUTED:
      summary: Dispute Request Submitted
      description: Cancel IMB response for an IMB that was manifested and now has a refund request submitted.
      value:
        imb: "00700123456000000001200669998"
        status: DISPUTED
        disputeId: "103789"
    LabelBrandingUploadExample:
      summary: Label Branding Image Upload Request
      description: A request to upload an svg image of a logo including the optional imageName attribute.
      value:
        imageName: LogoOfCircle
        imageData: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
    LabelBrandingDeleteExample:
      summary: Label Branding Image Delete Request
      description: Label Branding Image Delete Request
      value:
        imageName: LogoOfCircle
        imageUUID: a0529b65-706b-4686-aff5-60e39857cd00
    LabelBrandingPatchExample:
      summary: Label Branding Image Patch Request
      description: Label Branding Image Patch Request
      value:
        imageUUID: a0529b65-706b-4686-aff5-60e39857cd00
        imageName: LogoOfCircle
        createdDateTime: 2023-10-30T18:00:00Z
        imageData: PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgZmlsbD0iIzAwMDAwMCIvPjwvc3ZnPg==
    ExampleCancelError_REFUND_NOT_SUBMITTED:
      summary: Refund Not Submitted
      description: "Cancel Label error response for a label that has been manifested, but a refund request cannot be submitted"
      value:
        apiVersion: /labels/v3
        error:
          code: "400"
          message: Bad Request
          errors:
            - title: Bad Request
              detail: A refund request for this order cannot be submitted
              code: 00000XX
              source:
                parameter: trackingNumber
    ExampleCancelError_REFUND_SAMELABEL_SAMEDAY:
      summary: Refund Same Label Same Day
      description: "Cancel Label error response for when a label has been manifested, but it is detected that the label has already had a refund request submitted already in the same day."
      value:
        apiVersion: /labels/v3
        error:
          code: "400"
          message: Bad Request
          errors:
            - title: Bad Request
              detail: A refund request for this order has already been submitted today
              code: 00000XX
              source:
                parameter: trackingNumber
    BrandingExamplePatch:
      summary: Update Image Name
      description: Edit image name of existing branding image.
      value:
        - op: replace
          path: /imageName
          value: companyShippingLogo
    ExamplePatch:
      summary: Update Labels
      description: Edit label with a patch.
      value:
        - op: replace
          path: /packageDescription/weight
          value: 2.5
        - op: replace
          path: /packageDescription/length
          value: 17.0
        - op: replace
          path: /packageDescription/height
          value: 9.0
        - op: replace
          path: /packageDescription/girth
          value: 4.5
        - op: replace
          path: /packageDescription/processingCategory
          value: FLAT
        - op: replace
          path: /packageDescription/rateIndicator
          value: CP
    ExamplePatch3:
      summary: Update Labels replacing containers
      description: Edit label with a patch.
      value:
        - op: replace
          path: /packageDescription/weight
          value: 3.5
        - op: replace
          path: /packageDescription/length
          value: 11.0
        - op: replace
          path: /packageDescription/height
          value: 8.0
        - op: replace
          path: /packageDescription/girth
          value: 3.5
        - op: replace
          path: /packageDescription/processingCategory
          value: FLAT
        - op: replace
          path: /packageDescription/containers
          value:
            - containerId: "12123"
              sortType: "12123"
            - containerId: "12134"
              sortType: "12124"
        - op: replace
          path: /packageDescription/rateIndicator
          value: CP
    EditResponse:
      value:
        labelAddress:
          streetAddress: 2700 S JEFFERSON AVE
          secondaryAddress: STE 150
          city: SAINT LOUIS
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
          firstName: JOHN
          lastName: DOE
          ignoreBadAddress: false
          routingInformation: "420631182628"
          trackingNumber: "9205590006662200704797"
          postage: 26.25
          extraServices:
            - name: "USPS Tracking"
              price: 0.0
              SKU: "DXTP0EXXXCX0000"
          zone: "01"
          commitment:
            - name: "1 Days"
              scheduleDeliveryDate: "2024-09-30"
              expectedDeliveryDate: "2024-09-30"
              isPriorityMailNextDay: false
          weightUOM: "LB"
          weight: 27.0
          dimensionalWeight: 0.0
          fees: [ ]
          labelBrokerID: ""
          constructCode: "C01"
          SKU: "DPXX0XXXXC01270"
    Base64EncodedImagesExample:
      summary: Create label response with embedded images in JSON
      description: Create label response with Base64 encoded embedded images in JSON
      value:
        labelAddress:
          firstName: John
          lastName: Doe
          streetAddress: 123 Main St
          city: Anytown
          state: CA
          ZIPCode: "12345"
        routingInformation: "42012345"
        trackingNumber: "123456789012"
        constructCode: ABC123
        SKU: "12345"
        postage: 10.99
        extraServices:
          - name: Certified Mail
            SKU: C123
            price: 3.99
          - name: Insurance
            SKU: I123
            price: 2.99
        zone: "05"
        mailingDate: "2024-09-08T12:00:00Z"
        commitment:
          name: 1-day
          scheduleDeliveryDate: "2024-09-09"
          expectedDeliveryDate: "2024-09-30"
          isPriorityMailNextDay: false
        weightUOM: lb
        weight: 1.5
        dimensionalWeight: 0.0
        fees:
          - name: Fuel Surcharge
            SKU: FUEL
            price: 1.23
        permitHolderName: John Doe
        labelBrokerID: LB12345
        labelImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        receiptImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        returnLabel:
          labelAddress:
            streetAddress: 456 Main St
            city: Anytown
            state: CA
            ZIPCode: "67890"
          routingInformation: "42067890"
          trackingNumber: "098765432109"
          SKU: "12345"
          postage: 10.99
          extraServices:
            - name: Certified Mail
              SKU: C123
              price: 3.99
          zone: "05"
          mailingDate: "2024-09-08T12:00:00Z"
          weightUOM: lb
          weight: 1.5
          dimensionalWeight: 0.0
          fees:
            - name: Fuel Surcharge
              SKU: FUEL
              price: 1.23
          labelBrokerID: LB54321
          links:
            - rel: [ Tracking URL ]
              href: https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=098765432109
          returnLabelImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
          returnReceiptImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
    Base64EncodedImagesXMLExample:
      summary: Create label response with embedded images in XML document
      description: Create label response with Base64 encoded embedded images in XML
      value: "<labelMetadata>\n    <labelImage>aW1hZ2UgdGVzdA==</labelImage>\n    <receiptImage>aW1hZ2UgcmVjZWl2ZQ==</receiptImage>\n    <labelAddress>\n        <streetAddress>123 Main St</streetAddress>\n        <secondaryAddress/>\n        <city>Anytown</city>\n        <state>CA</state>\n        <ZIPCode>12345</ZIPCode>\n    </labelAddress>\n    <routingInformation>42012345</routingInformation>\n    <trackingNumber>123456789012</trackingNumber>\n    <postage>10.99</postage>\n    <extraServices>\n        <name>Signature Confirmation</name>\n        <price>3.7</price>\n        <SKU>DXSU0EXPXCX0000</SKU>\n    </extraServices>\n    <extraServices>\n        <name>Insurance &lt;= $500</name>\n        <price>0</price>\n        <SKU>DXIX0XXXXCX0100</SKU>\n    </extraServices>\n    <zone>5</zone>\n    <commitment>\n        <name>2 Days</name>\n        <scheduleDeliveryDate>2024-11-09</scheduleDeliveryDate>\n      <expectedDeliveryDate>2024-11-09</expectedDeliveryDate>\n    <isPriorityMailNextDay>false</isPriorityMailNextDay>\n    </commitment>\n    <weightUOM>LB</weightUOM>\n    <weight>1.5</weight>\n    <dimensionalWeight>0.0</dimensionalWeight>\n    <fees>\n        <name>Nonstandard Length &gt; 22</name>\n        <price>4</price>\n        <SKU>D811XUXXXXX0000</SKU>\n    </fees>\n    <bannerText>USPS SIGNATURE TRACKING # USPS Ship</bannerText>\n    <retailDistributionCode>01</retailDistributionCode>\n    <serviceTypeCode>394</serviceTypeCode>\n    <returnLabel>\n        <labelAddress>\n            <streetAddress>456 Main St</streetAddress>\n            <secondaryAddress/>\n            <city>Anytown</city>\n            <state>CA</state>\n            <ZIPCode>67890</ZIPCode>\n            <firstName>JOHN</firstName>\n            <lastName>SMITH</lastName>\n        </labelAddress>\n        <routingInformation>42067890</routingInformation>\n        <trackingNumber>098765432109</trackingNumber>\n        <SKU>12345</SKU>\n        <postage>10.99</postage>\n        <extraServices>\n            <name>Signature Confirmation</name>\n            <price>3.7</price>\n            <SKU>DXSU0EXPXCX0000</SKU>\n        </extraServices>\n        <extraServices>\n            <name>Insurance &lt;= $500</name>\n            <price>0</price>\n            <SKU>DXIX0XXXXCX0100</SKU>\n        </extraServices>\n        <zone>01</zone>\n        <weightUOM>LB</weightUOM>\n        <weight>1.5</weight>\n        <dimensionalWeight>0.0</dimensionalWeight>\n        <fees>\n            <name>Nonstandard Length &gt; 22</name>\n            <price>4</price>\n            <SKU>D811XUXXXXX0000</SKU>\n        </fees>\n        <bannerText>USPS TRACKING # USPS Ship</bannerText>\n        <retailDistributionCode>01</retailDistributionCode>\n        <serviceTypeCode>022</serviceTypeCode>\n        <returnLabelImage>aW1hZ2UgdGVzdA==</returnLabelImage>\n        <returnReceiptImage>aW1hZ2UgdGVzdA==</returnReceiptImage>\n        <links>\n            <rel>Tracking URL</rel>\n            <href>https: //tools.usps.com/go/TrackConfirmAction_input?origTrackNum=098765432109</href>\n            <method>GET</method>\n        </links>\n        <SKU>DUXP0RXXXC01010</SKU>\n    </returnLabel>\n    <constructCode>C01</constructCode>\n    <SKU>DUXP0XXXXC01010</SKU>\n</labelMetadata>"
    JSONReturnLabelWithEmbeddedBased64Response:
      summary: JSON response for return labels api with embedded images
      description: JSON response for return labels api with base64 encoded embedded images
      value:
        labelAddress:
          firstName: John
          lastName: Doe
          streetAddress: 123 Main St
          city: Anytown
          state: CA
          ZIPCode: "12345"
          ZIPPlus4: "6789"
        routingInformation: "42012345"
        trackingNumber: "9405509898644824249889"
        SKU: "12345"
        postage: 8.75
        extraServices:
          - name: Certified Mail
            SKU: "67890"
            price: 3.5
        zone: "03"
        mailingDate: "2024-09-08T12:00:00Z"
        weightUOM: lb
        weight: 1.5
        dimensionalWeight: 0
        fees:
          - name: Return Receipt
            SKU: "54321"
            price: 2.75
        labelBrokerID: "1234567890"
        links:
          - rel: [ Tracking URL ]
            href: https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9405509898644824249889
        returnLabelImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        returnReceiptImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
    XMLReturnLabelResponseWithEmbeddedBase64EncodedImages:
      summary: XML response for return labels api with embedded images
      description: XML response for return labels api with base64 encoded embedded images
      value: "<labelMetadata>\n    <returnLabelImage>\n        iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2Hx0XAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAgAElEQVR4nOzdd5xTZX3f8d8s8GBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYOBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYOBoYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBg\n    </returnLabelImage>\n    <returnReceiptImage>\n        iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2Hx0XAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAgAElEQVR4nOzdd5xTZX3f8d8s8GBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYOBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYOBoYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBg\n    </returnReceiptImage>\n    <labelAddress>\n        <firstName>John</firstName>\n        <lastName>Doe</lastName>\n        <streetAddress>123 Main St</streetAddress>\n        <city>Anytown</city>\n        <state>CA</state>\n        <ZIPCode>12345</ZIPCode>\n        <ZIPPlus4>6789</ZIPPlus4>\n    </labelAddress>\n    <routingInformation>42012345</routingInformation>\n    <trackingNumber>9405509898644824249889</trackingNumber>\n    <SKU>DUXP0RXXUC01080</SKU>\n    <postage>8.75</postage>\n    <extraServices>\n        <name>Insurance &lt;= $500</name>\n        <price>6.85</price>\n        <SKU>DXIX0XXXXCX0400</SKU>\n    </extraServices>\n    <extraServices>\n        <name>Scan Weigh Pay</name>\n        <price>0</price>\n        <SKU>NA</SKU>\n    </extraServices>\n    <zone>03</zone>\n    <weight>1.5</weight>\n    <weightUOM>LB</weightUOM>\n    <dimensionalWeight>0</dimensionalWeight>\n    <bannerText>USPS TRACKING # USPS Ship</bannerText>\n    <retailDistributionCode>01</retailDistributionCode>\n    <serviceTypeCode>055</serviceTypeCode>\n    <sku>DUXP0RXXUC01080</sku>\n    <links>\n        <rel>Tracking URL</rel>\n        <title/>\n        <href>https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=420123459405509898644824249889</href>\n        <method>GET</method>\n        <submissionMediaType/>\n        <targetMediaType/>\n    </links>\n</labelMetadata>"
    GroundAdvantageRequest:
      summary: USPS Ground Advantage request
      description: Example request to generate a USPS Ground Advantage request
      value:
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: 2700 S Jefferson Ave
          secondaryAddress: STE 150
          city: St. Louis
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: SP
          weightUOM: lb
          weight: 0.5
          dimensionsUOM: in
          length: 9
          height: 6
          width: 0.25
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-05"
          extraServices: [ ]
          destinationEntryFacilityType: NONE
    GroundAdvantageRequestWithImageInfo:
      summary: USPS Ground Advantage request with Image Info
      description: Example request to generate a USPS Ground Advantage request with image information block
      value:
        imageInfo:
          imageType: PDF
          labelType: 4X6LABEL
          receiptOption: NONE
          suppressPostage: true
          suppressMailDate: true
          returnLabel: false
          brandingImageFormat: NONE
          includeLabelBrokerPDF: false
          addZPLComments: false
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: 2700 S Jefferson Ave
          secondaryAddress: STE 150
          city: St. Louis
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: SP
          weightUOM: lb
          weight: 0.5
          dimensionsUOM: in
          length: 9
          height: 6
          width: 0.25
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-05"
          extraServices: [ ]
          destinationEntryFacilityType: NONE
    HoldForPickupRequest:
      summary: Hold for Pickup Request
      description: Example request to generate a label using the Hold for Pickup feature
      value:
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: 2700 S Jefferson Ave
          secondaryAddress: STE 150
          city: St. Louis
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
          holdForPickup: true
          facilityId: "1437366"
          email: hold@pickup.com
          phone: "6148098581"
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
          email: hold@pickup.com
          phone: "6147476321"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: P5
          length: 6.0
          height: 6.0
          width: 6.0
          weight: 1.0
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-03"
          extraServices:
            - 920
          destinationEntryFacilityType: NONE
    PMECrematedRemainsRequest:
      summary: Priority Mail Express Cremated Remains Request
      description: Example request to generate a label when shipping Cremated Remains using Priority Mail Express
      value:
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: 2700 S Jefferson Ave
          secondaryAddress: STE 150
          city: St. Louis
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
          ignoreBadAddress: true
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
          ignoreBadAddress: true
        packageDescription:
          mailClass: PRIORITY_MAIL_EXPRESS
          rateIndicator: PA
          length: 6.0
          height: 6.0
          width: 6.0
          weight: 1.0
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-03T17:33:20.4170000Z"
          extraServices:
            - 986
          destinationEntryFacilityType: NONE
          packageOptions:
            contentType: CREMATED_REMAINS
    CustomsFormRequest:
      summary: Customs Form Request
      description: Example request to generate a label with a customs form being delivered to an APO/FPO/DPO location
      value:
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: PSC 123 BOX 1234
          city: APO
          state: AE
          ZIPCode: "09008"
          ZIPPlus4: "0041"
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
        returnAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 850 Twin Rivers Dr
          city: Columbus
          state: OH
          ZIPCode: "43216"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: SP
          weightUOM: lb
          dimensionsUOM: in
          length: 6.0
          height: 6.0
          width: 6.0
          weight: 5.0
          processingCategory: MACHINABLE
          mailingDate: "2025-07-30"
          destinationEntryFacilityType: NONE
        customsForm:
          restrictionType: QUARANTINE
          AESITN: NO EEI 30.37(w)
          invoiceNumber: "1234567890"
          certificateNumber: "987654321"
          customsContentType: MERCHANDISE
          contents: [
            {
              itemDescription: Item 1,
              itemQuantity: 1,
              itemTotalValue: 50,
              weightUOM: lb,
              itemTotalWeight: 3,
              HSTariffNumber: 1234.56.78,
              countryofOrigin: US
            },
            {
              itemDescription: Item 2,
              itemQuantity: 1,
              itemTotalValue: 50,
              weightUOM: lb,
              itemTotalWeight: 2,
              HSTariffNumber: 2345.67.89,
              countryofOrigin: US
            }
          ]
    SmartLockerRequest:
      summary: Smart Locker Request
      description: Example request to generate a label being delivered to a USPS Smart Locker
      value:
        toAddress:
          firstName: Nick
          lastName: Fury
          parcelLockerDelivery: true
          facilityId: "1434185"
          email: ben@test.com
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
        returnAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 846 Grandon
          city: Columbus
          state: OH
          ZIPCode: "43209"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: P5
          weightUOM: lb
          dimensionsUOM: in
          length: 6.0
          height: 6.0
          width: 6.0
          weight: 1.0
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-02"
          destinationEntryFacilityType: NONE
    LabelBrokerRequest:
      summary: Label Broker Request
      description: Example request to generate both a Label Broker QR Code and its respective Label PDF
      value:
        imageInfo:
          imageType: LABEL_BROKER
          includeLabelBrokerPDF: true
        toAddress:
          firstName: Nick
          lastName: Fury
          streetAddress: 2700 S Jefferson Ave
          secondaryAddress: STE 150
          city: St. Louis
          state: MO
          ZIPCode: "63104"
          ZIPPlus4: "2351"
        fromAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 45 L St SW
          city: Washington
          state: DC
          ZIPCode: "20024"
        returnAddress:
          firstName: Sam
          lastName: Wilson
          streetAddress: 846 Grandon
          city: Columbus
          state: OH
          ZIPCode: "43209"
        packageDescription:
          mailClass: USPS_GROUND_ADVANTAGE
          rateIndicator: P5
          weightUOM: lb
          dimensionsUOM: in
          length: 6.0
          height: 6.0
          width: 6.0
          weight: 1.0
          processingCategory: NONSTANDARD
          mailingDate: "2024-10-02"
          destinationEntryFacilityType: NONE
    GroundAdvantageReturnLabelRequest:
      summary: USPS Ground Advantage Return Label Request
      description: Example request to generate a USPS Ground Advantage return label
      value:
        imageInfo:
          suppressPostage: false
          receiptOption: NONE
          imageType: PDF
        toAddress:
          firstName: John
          lastName: Smith
          streetAddress: 1200 Pennsylvania Avenue NW
          city: Washington
          state: DC
          ZIPCode: "20004"
        fromAddress:
          firstName: John
          lastName: Doe
          streetAddress: 1400 L St NW
          secondaryAddress: Lbby 2
          city: Washington
          state: DC
          ZIPCode: "20005"
        packageDescription:
          mailClass: PRIORITY_MAIL_RETURN_SERVICE
          rateIndicator: CP
          processingCategory: MACHINABLE
          extraServices: [ ]
          weightUOM: lb
          weight: 0.5
          dimensionsUOM: in
          length: 12
          height: 4.0
          width: 3.0
          customerReference:
            - referenceNumber: This is a return
              printReferenceNumber: true
    IndiciaExampleResponse:
      summary: Create an Indicia response with embedded image in JSON
      description: Create an Indicia response with embedded image in JSON
      value:
        indiciaImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        receiptImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        indiciaMetadata:
          SKU: DFLL0XXXXR00020
          postage: 0.97
          fees:
            - name: Nonmachinable letter fee
              SKU: N/A
              price: 0.4
          weight: 2.0
    IndiciaIMBExampleResponse:
      summary: Create an Indicia with IMB response with embedded image in JSON
      description: Create an Indicia with IMB response with embedded image in JSON
      value:
        indiciaImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        receiptImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        indiciaMetadata:
          SKU: DFLL0XXXXR00020
          postage: 0.97
          fees:
            - name: Nonmachinable letter fee
              SKU: N/A
              price: 0.4
          weight: 2.0
          imb: "0070009876500000057563118262800"
    LabelReprintRequestExample:
      summary: Request to reprint a label
      description: Request to reprint a label
      value:
        imageInfo:
          imageType: PDF
          labelType: 4X6LABEL
          suppressPostage: true
          suppressMailDate: true
          brandingImageFormat: ONE_SQUARE
          brandingImageUUIDs: ["828224ba-2a30-4c95-adcf-6bc3efb790f8"]
          packageNumber: 1
          totalPackages: 3
    LabelReprintResponseExample:
      summary: Response when reprinting an outbound label.
      description: Response when reprinting an outbound label.
      value:
        labelMetadata:
          labelAddress:
            streetAddress: 123 Main St
            secondaryAddress: STE 150
            city: Anytown
            state: CA
            ZIPCode: "12345"
            ZIPPlus4: "6789"
            firstName: John
            lastName: Doe
          routingInformation: "42012345"
          trackingNumber: "123456789012"
          constructCode: ABC123
          SKU: "12345"
          postage: 10.99
          extraServices:
            - name: Certified Mail
              SKU: C123
              price: 3.99
            - name: Insurance
              SKU: I123
              price: 2.99
          zone: "05"
          mailingDate: "2024-09-08T12:00:00Z"
          commitment:
            name: 1-day
            scheduleDeliveryDate: "2024-09-09"
            expectedDeliveryDate: "2024-09-09"
            isPriorityMailNextDay: false
          weightUOM: lb
          weight: 1.5
          dimensionalWeight: 0.0
          fees:
            - name: Fuel Surcharge
              SKU: FUEL
              price: 1.23
          permitHolderName: John Doe
          labelBrokerID: LB12345
        labelImage: iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAyklEQVR42mNgwAf///5ebGxgYGJiYmBjY2MzDw8PAAzHAxiQI3A4VCYgKQZjIyMjIyMzCwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwK6IBwC7CvHf3RbAAAAAElFTkSuQmCC
        reprintInfo:
          reprintNumber: 1
          reprintLimit: 3
  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"
    ETag:
      description: Entity Tag response header indicating version of resource. All DELETE and PUT operations require an ETag.  The ETag is returned in the GET operation and is good for one hour or until it is used in a DELETE or PUT operation.
      schema:
        type: string
        example: "ETag: \"33a64df551425fcc55e4d42a148795d9f25f89d4\""
  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:
            labels: "Read, create, and cancel access to Labels."
        authorizationCode:
          authorizationUrl: /oauth2/v3/authorize
          tokenUrl: /oauth2/v3/token
          scopes:
            labels: "Read, create, and cancel access to Labels."
