International Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-international-label-vendor-response-schema.json",
  "title": "International Package Response for `application/vnd.usps.labels+json` and `application/vnd.usps.labels+xml`.",
  "description": "Response containing the international label metadata and Base64-encoded label image for vendor-specific media types.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-international-labels-openapi.yml#/components/schemas/InternationalLabelVendorResponse",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/$defs/InternationalLabelMetadata"
    },
    {
      "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`.\n",
          "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"
        }
      }
    }
  ],
  "$defs": {
    "Address": {
      "title": "Address",
      "type": "object",
      "properties": {
        "streetAddress": {
          "maxLength": 50,
          "minLength": 1,
          "type": "string",
          "description": "The number of a building along with the name of the road or street on which it is located."
        },
        "streetAddressAbbreviation": {
          "maxLength": 50,
          "minLength": 0,
          "type": "string",
          "description": "This is the abbreviation of 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."
    },
    "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 corresponding to the address."
        }
      },
      "additionalProperties": true,
      "description": "Fields used to identity the entity receiving a mail piece or package."
    },
    "ExtraServiceResponse": {
      "title": "Extra Service Response",
      "type": "array",
      "description": "Extra services requested on the mailpiece.",
      "minItems": 0,
      "items": {
        "type": "object",
        "properties": {
          "serviceID": {
            "type": "string",
            "description": "The unique identifier of the extra service."
          },
          "serviceName": {
            "type": "string",
            "description": "Name of the extra service."
          },
          "sku": {
            "type": "string",
            "description": "SKU of the extra service."
          },
          "price": {
            "type": "number",
            "description": "The price for the extra service.",
            "format": "float"
          },
          "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"
                },
                "warningDescription": {
                  "type": "string",
                  "description": "Warning or additional information regarding the Extra Service."
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      }
    },
    "InternationalAddress": {
      "title": "International Address",
      "additionalProperties": true,
      "description": "Address fields for International locations.",
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        },
        {
          "type": "object",
          "properties": {
            "city": {
              "maxLength": 28,
              "minLength": 1,
              "type": "string",
              "description": "This is the city name of the address."
            },
            "postalCode": {
              "maxLength": 11,
              "type": "string",
              "description": "This is the Postal Code used for international addresses.\n\nNote:\n- When shipping to Canada, this field must start with a letter (A-Z)\n- Different shipping destinations may require a postal code for shipping.  For more details, review the [Individual Country Listing](https://pe.usps.com/text/imm/immctry.htm) for your shipping destination\n"
            },
            "province": {
              "maxLength": 40,
              "type": "string",
              "description": "This is the province used for international addresses."
            },
            "provinceISOAlpha2Code": {
              "$ref": "#/$defs/ProvinceISOAlpha2Code"
            },
            "country": {
              "minLength": 1,
              "type": "string",
              "description": "This is the country name used in an international address."
            },
            "countryISOAlpha2Code": {
              "pattern": "^([a-zA-Z]){2}",
              "type": "string",
              "description": "ISO 3166-1 alpha-2 codes are two-letter country codes defined in ISO 3166-1, part of the ISO 3166 standard[1] published by the International Organization for Standardization (ISO), to represent countries, dependent territories, and special areas of geographical interest. They are the most widely used of the country codes published by ISO (the others being alpha-3 and numeric), and are used most prominently for the Internet's country code top-level domains (with a few exceptions). They are also used as country identifiers extending the postal code when appropriate within the international postal system for paper mail, and have replaced the previous one consisting of one-letter codes. They were first included as part of the ISO 3166 standard in its first edition in 1974."
            }
          },
          "additionalProperties": true
        }
      ]
    },
    "InternationalLabelAddress": {
      "title": "International Label Address",
      "required": [
        "city",
        "country",
        "countryISOAlpha2Code",
        "streetAddress"
      ],
      "type": "object",
      "additionalProperties": true,
      "description": "Uses for:\n\nThe international address where the package is being mailed to. The destination Country Code is used for calculating pricing.\n\nFor guidelines on acceptable international addresses, please reference [Section 122 of the International Mail Manual](https://pe.usps.com/text/imm/immc1_008.htm).\n\nNote:\n- The First and Last Name or Firm Name are always required.",
      "allOf": [
        {
          "$ref": "#/$defs/InternationalAddress"
        },
        {
          "$ref": "#/$defs/Addressee"
        },
        {
          "type": "object",
          "properties": {
            "phone": {
              "$ref": "#/$defs/Phone"
            },
            "provinceISOAlpha2Code": {
              "$ref": "#/$defs/ProvinceISOAlpha2Code"
            }
          }
        }
      ]
    },
    "InternationalLabelMetadata": {
      "title": "International Label Metadata response",
      "description": "Metadata information for an international label including tracking number, pricing details, postage, and extra services.",
      "type": "object",
      "properties": {
        "labelAddress": {
          "$ref": "#/$defs/InternationalLabelAddress"
        },
        "internationalTrackingNumber": {
          "type": "string",
          "description": "International Package Tracking number",
          "minLength": 13,
          "maxLength": 13
        },
        "constructCode": {
          "type": "string",
          "description": "The barcode construct code associated with the international tracking number",
          "minLength": 3,
          "maxLength": 3
        },
        "SKU": {
          "type": "string",
          "description": "Pricing SKU",
          "minLength": 15,
          "maxLength": 15
        },
        "postage": {
          "type": "number",
          "description": "Amount of Postage Required, does not include insurance or other extra service fees.",
          "minimum": 0.01,
          "maximum": 9999.99
        },
        "extraServices": {
          "$ref": "#/$defs/ExtraServiceResponse"
        },
        "internationalPriceGroup": {
          "type": "string",
          "description": "Indicates the price group for a given `countryISOAlpha2Code`, `mailClass`, `mailingDate`, and `rateIndicator`.",
          "minLength": 2,
          "maxLength": 2
        },
        "weightUOM": {
          "type": "string",
          "description": "Weight Unit of Measurement.\n  * lb - Pounds",
          "default": "lb",
          "enum": [
            "lb"
          ]
        },
        "weight": {
          "$ref": "#/$defs/weight"
        },
        "dimensionalWeight": {
          "type": "string",
          "description": "The dimensional weight of the package in pounds, if greater than the value specified in `weight`.",
          "minLength": 3
        },
        "mailingDate": {
          "type": "string",
          "description": "The date on which the package will be mailed as provided in the request.",
          "format": "date"
        },
        "fees": {
          "type": "array",
          "description": "Fees associated to the package.",
          "minItems": 0,
          "maxItems": 5,
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the fee."
              },
              "SKU": {
                "type": "string",
                "description": "Pricing SKU of the fee."
              },
              "price": {
                "type": "number",
                "description": "The price for the fee."
              }
            },
            "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."
        },
        "links": {
          "$ref": "#/$defs/Links"
        }
      },
      "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
      }
    },
    "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."
    },
    "ProvinceISOAlpha2Code": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "pattern": "^([a-zA-Z]){2}",
      "description": "The 2 letter abbreviation representing the destination province. Required for select destination countries when `prepayDutiesTaxesFees` is `true`."
    },
    "weight": {
      "type": "number",
      "description": "The calculated weight for the package based on user input. The greater of `dimensionalWeight` and `weight` will be used to calculate the rate.",
      "format": "double",
      "minimum": 0.01,
      "maximum": 9999.99
    }
  }
}