Create OD Container Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-create-odcontainer-request-schema.json",
  "title": "Create OD Container Request",
  "description": "Create OD Container Request",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-pmod-openapi.yml#/components/schemas/CreateODContainerRequest",
  "required": [
    "originAddress",
    "destinationZIPCode",
    "destinationEntryFacilityType",
    "enclosedMailClass",
    "mailerName",
    "mailingDate",
    "weight",
    "processingCategory",
    "impbContainerType"
  ],
  "type": "object",
  "properties": {
    "imageInfo": {
      "$ref": "#/$defs/ImageInfo"
    },
    "originAddress": {
      "$ref": "#/$defs/DomesticAddress"
    },
    "senderAddress": {
      "description": "Uses for:\n\nThe address of the business entering the Open and Distribute container.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        }
      ]
    },
    "returnAddress": {
      "description": "Uses for:\n\nThe address of the business where the Open and Distribute container 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.\n\nThe First and Last Name or Firm Name are always required.\n",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticLabelAddress"
        }
      ]
    },
    "destinationZIPCode": {
      "maxLength": 5,
      "minLength": 5,
      "pattern": "^\\d{5}$",
      "type": "string",
      "description": "A 5-digit ZIP Code serviced by the `destinationEntryFacilityType` the container is being sent to.  The destination ZIP Code is used for calculating pricing and identifying the Destination Entry Facility."
    },
    "containerMailClass": {
      "description": "Mail class for the Open and Distribute container",
      "type": "string",
      "default": "PRIORITY_MAIL",
      "enum": [
        "PRIORITY_MAIL",
        "PRIORITY_MAIL_EXPRESS"
      ]
    },
    "enclosedMailClass": {
      "description": "The mail class of the items enclosed in the container.\n\nNote:\n- To add Heavy Printed Matter labels to an Open and Distribute container, set `enclosedMailClass` to `MARKETING_MAIL_PARCELS`. Use `USPS_MARKETING_MAIL` for USPS Marketing Mail letters and flats.\n",
      "type": "string",
      "enum": [
        "PARCEL_SELECT",
        "PERIODICALS",
        "PERIODICALS_NEWS",
        "PACKAGE_SERVICES",
        "USPS_MARKETING_MAIL",
        "BOUND_PRINTED_MATTER",
        "LIBRARY_MAIL",
        "MEDIA_MAIL",
        "MARKETING_MAIL_PARCELS"
      ]
    },
    "mailerName": {
      "$ref": "#/$defs/MailerName"
    },
    "processingCategory": {
      "type": "string",
      "description": "The type of packages that will be nested to the container. `MIXED` is only available for `DESTINATION_DELIVERY_UNIT` containers.",
      "enum": [
        "MACHINABLE",
        "MIXED",
        "NONSTANDARD"
      ]
    },
    "destinationEntryFacilityType": {
      "type": "string",
      "description": "The facility type where the container will be sent to.\n\nNote:\n* Effective 01/18/2026: `DESTINATION_NETWORK_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is no longer eligible.\n* Effective 01/18/2026: (NSA Only) `DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER` with `PARCEL_SELECT` is available as an option.",
      "enum": [
        "DESTINATION_NETWORK_DISTRIBUTION_CENTER",
        "DESTINATION_SECTIONAL_CENTER_FACILITY",
        "DESTINATION_DELIVERY_UNIT",
        "DESTINATION_AUXILIARY_SERVICE_FACILITY",
        "DESTINATION_AREA_DISTRIBUTION_CENTER",
        "DESTINATION_REGIONAL_PROCESSING_DISTRIBUTION_CENTER"
      ]
    },
    "mailingDate": {
      "$ref": "#/$defs/MailingDateOptions"
    },
    "trackingNumbers": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "IMpb tracking numbers of packages associated with the container. These can be generated with the Domestic Labels 3.0 API."
      }
    },
    "weightUOM": {
      "type": "string",
      "description": "Weight Unit of Measure\n   * lb - Pounds",
      "default": "lb",
      "enum": [
        "lb"
      ]
    },
    "weight": {
      "minimum": 0,
      "exclusiveMinimum": true,
      "type": "number",
      "description": "The package weight, in weightUOM (Unit Of Measure). \nContainers must weigh 70 pounds (1120 ounces) or less when impbContainerType is not 'OPEN_DISTRIBUTE_PALLET.'\n"
    },
    "impbContainerType": {
      "type": "string",
      "description": "IMpb Container Type requested.\n",
      "enum": [
        "OPEN_DISTRIBUTE_FULL_POSTAL_PAKS",
        "OPEN_DISTRIBUTE_HALF_TRAY_BOX",
        "OPEN_DISTRIBUTE_HALF_POSTAL_PAKS",
        "OPEN_DISTRIBUTE_PALLET",
        "OPEN_DISTRIBUTE_FULL_TRAY_BOX",
        "OPEN_DISTRIBUTE_EMM_TRAY_BOX",
        "OPEN_DISTRIBUTE_FLAT_TUB_TRAY_BOX",
        "SACK"
      ]
    },
    "imcbContainerType": {
      "type": "string",
      "description": "IMcb Container Type requested. \nWhen not provided, this will take the value of impbContainerType by default. \nThis field is not applicable when impbContainerType is 'OPEN_DISTRIBUTE_PALLET'.\n",
      "enum": [
        "OPEN_DISTRIBUTE_FULL_POSTAL_PAKS",
        "OPEN_DISTRIBUTE_HALF_TRAY_BOX",
        "OPEN_DISTRIBUTE_HALF_POSTAL_PAKS",
        "OPEN_DISTRIBUTE_FULL_TRAY_BOX",
        "OPEN_DISTRIBUTE_EMM_TRAY_BOX",
        "OPEN_DISTRIBUTE_FLAT_TUB_TRAY_BOX",
        "SACK"
      ]
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Addressee": {
      "title": "Addressee",
      "type": "object",
      "properties": {
        "firstName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "This is the first name corresponding to the address."
        },
        "lastName": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "This is the last name corresponding to the address."
        },
        "firm": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "This is the firm corresponding to the address. Firm is required for all domestic addresses in international label requests due to customs form requirements."
        }
      },
      "additionalProperties": true,
      "description": "Fields used to identity the entity receiving a mail piece or package"
    },
    "DomesticAddress": {
      "title": "Domestic Address",
      "additionalProperties": true,
      "description": "The address of the Business Mail Entry Unit (BMEU) or authorized acceptance location facility where the Open and Distribute container is being entered.  The origin ZIP Code is used for calculating pricing.",
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "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."
        },
        "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)."
        },
        "city": {
          "maxLength": 28,
          "minLength": 1,
          "type": "string",
          "description": "This is the city name of the address."
        },
        "state": {
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$",
          "type": "string",
          "description": "This is two-character state code of the address."
        },
        "ZIPCode": {
          "pattern": "^\\d{5}$",
          "type": "string",
          "description": "This is the 5-digit ZIP code."
        },
        "ZIPPlus4": {
          "pattern": "^\\d{4}$",
          "type": [
            "string",
            "null"
          ],
          "description": "This is the ZIP+4 extension."
        },
        "urbanization": {
          "maxLength": 96,
          "type": "string",
          "description": "An area, sector, or residential development within a geographic area (typically used for addresses in Puerto Rico)"
        }
      }
    },
    "DomesticLabelAddress": {
      "title": "Domestic Label Address",
      "required": [
        "ZIPCode",
        "city",
        "state",
        "streetAddress"
      ],
      "type": "object",
      "additionalProperties": true,
      "description": "Uses for:\n\nThe address where the package is being mailed from. The destination ZIP Code is used for calculating pricing.\n\nThe destination address of the recipient. The origin ZIP Code is used for calculating pricing.\n\nThe address of the business.\n\nThe 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.",
      "allOf": [
        {
          "$ref": "#/$defs/DomesticAddress"
        },
        {
          "$ref": "#/$defs/Addressee"
        },
        {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "phone": {
              "$ref": "#/$defs/Phone"
            },
            "email": {
              "$ref": "#/$defs/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.\n\nNote: Integrators are recommended to always use “false” to ensure no delivery issues. \n\nIn 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.\n"
            }
          }
        }
      ]
    },
    "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"
    },
    "ImageInfo": {
      "title": "Image Info",
      "type": "object",
      "properties": {
        "imageType": {
          "type": "string",
          "description": "The type of label image requested.  \nIf omitted then the default image type is `PDF`.\n",
          "default": "PDF",
          "enum": [
            "PDF",
            "TIFF",
            "JPG",
            "PNG",
            "GIF",
            "SVG",
            "ZPL203DPI",
            "ZPL300DPI",
            "NONE"
          ]
        },
        "labelType": {
          "type": "string",
          "description": "Ability to select the label image size.  If omitted then the default label size is `4X6LABEL`.\n",
          "default": "4X6LABEL",
          "enum": [
            "4X6LABEL"
          ]
        },
        "imcbLabelType": {
          "type": "string",
          "description": "Ability to select the 99M image size.  If omitted then the default label size is `6X4LABEL`.\n\nNote:\n- When using `ZPL203DPI` or `ZPL300DPI` the image returned will be rotated 90 degrees and be 4x6 inches, instead of 6x4 inches.\n",
          "default": "6X4LABEL",
          "enum": [
            "6X4LABEL"
          ]
        },
        "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.\n\nNote:\n  * When `imageType` is `ZPL203DPI` or `ZPL300DPI`, a `receiptOption` of `SAME_PAGE` is not supported.\n  * When `imageType` is `ZPL203DPI` or `ZPL300DPI` and `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.\n",
          "default": "SAME_PAGE",
          "enum": [
            "SAME_PAGE",
            "SEPARATE_PAGE",
            "NONE"
          ]
        },
        "suppressPostage": {
          "type": "boolean",
          "description": "Indicates if postage is printed on the label.  If omitted then the request will be defaulted to true.\n",
          "default": true
        },
        "suppressMailDate": {
          "type": "boolean",
          "description": "Indicates if the date is printed on the label.  If omitted then the value will default to true.",
          "default": true
        },
        "addZPLComments": {
          "type": "boolean",
          "default": false,
          "description": "Applicable only when `imageType` is `ZPL203DPI` or `ZPL300DPI`.  When `addZPLComments` is `true`, comments will be visible within the ZPL text response to the user to denote different sections of their label.  When `addZPLComments` is `false`, no comments will be included in the ZPL text response.  This will be ignored for any other `imageType`.\n\nExample of a ZPL comment: \n`^FX Start of label. 123e4567-e89b-12d3-a456-426614174000 ^FS`\n"
        }
      },
      "additionalProperties": false,
      "description": "Additional details used to determine how to generate the label image."
    },
    "MailerName": {
      "type": "string",
      "description": "Name of the business who is shipping the container."
    },
    "MailingDate": {
      "type": "string",
      "description": "The date package will be mailed. The mailing date may be today plus 0 to 7 days in advance. Enter the date in the full-date notation as defined by [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).",
      "format": "date"
    },
    "MailingDateOptions": {
      "type": "string",
      "description": "The mailing date for when the container will be shipped.\nThe mailing date may be today plus 0 to 7 days in advance.",
      "oneOf": [
        {
          "$ref": "#/$defs/MailingDate"
        },
        {
          "$ref": "#/$defs/MailingDateTime"
        }
      ]
    },
    "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"
    },
    "Phone": {
      "pattern": "^\\+?[1-9][0-9]{7,14}$",
      "type": "string",
      "description": "The phone number, including the country extension and area code, with no punctuation."
    }
  }
}