These release notes are sourced from USPS.

1. Revision History 

DateAuthorFile VersionChange Description
11/13/15Evan BetlerV1.1Initial public draft
12/1/15Evan BetlerV1.3Updates include:

–        Sections 2.4.2.1, 2.4.3.1: Corrected inconsistency in eDelCon countries

–        Section 2.2.3.1:

o   “Priority Express CPP” removed as valid <ServiceType>

–        Section 2.2.3.2:

o   Removed <FromPhone> from list of new tags

–        Sections 2.2.1-3:

o   Corrected order of new customs request tags

o   Corrected <CustomsContentType> enumerations

o   <HSTariffNumber> and <CountryOfOrigin> are required tags with optional values

–        Section 2.3.1: Clarification added regarding documents, non-negotiable documents and their relation to baked-in Insurance

–        Sections 2.3.1, 2.4.2: Added clarification that additional Insurance cannot be purchased for non-negotiable documents

12/8/15Evan BetlerV1.5Updates include:

–        Section 2.1.1.4: Clarified weight logic for First-Class Package Service (online)

–        Section 2.1.1.6: Updated Retail Ground <Service> request enumeration and <MailService> response value

–        Sections 2.3.1, 2.4.2: <ParcelIndemnityCoverage> updates

12/28/15Evan BetlerV1.7Updates include:

–        Sections 2.2.1.2 – 2.2.3.2:

o   Updated <InCaseOfNonDelivery> tag names, options and Redirect Address tags

o   Updated <CountryOfOrigin> valid enumerations to use full country names

o   Updated <RestrictionType> valid enumerations (see strikethrough)

–        Section 2.1.1.4: Updated First-Class Package Service commercial plus pricing request/response logic (see strikethrough)

–        Section 2.3.1, 2.4.1, 2.4.2: Updated logic for non-negotiable insurance covereage in the API response (baked-in insurance of up to $100 is assumed for non-negotiable documents and will not be returned in any response)

2. Implementation Summary 

Updates noted herein will be available in the Web Tools external testing environment for integrator access on December 12, 2015. The test environment can be accessed, using your production UserID, via the following URL scheme, host and path:

  • Secure APIs: https://stg-secure.shippingapis.com/ShippingApi.dll
  • Non-secure APIs: http://stg-production.shippingapis.com/ShippingApi.dll

If you receive an authorization error, please contact webtools@usps.gov and include your UserID.

The production release date is early morning January 17, 2016. This release includes the following changes:

2.1      Domestic Rate API Updates (RateV4)

2.1.1      January Price Change

  1. Price updates
    • Price to price updates only; no request or response schema updates
    • Reference http://pe.usps.gov/ for updated prices
  2. Elimination of Priority Mail Express Flat Rate Box
    • “Flat Rate Box” will no longer be a valid <Container> enumerations when <Service>=”Priority Mail Express”, ”Priority Mail Express Commercial”, ”Priority Mail Express CPP”, ”Priority Mail Express HFP”, ”Priority Mail Express HFP Commercial”, ”Priority Mail Express HFP CPP”, “Priority Mail Express SH”, ”Priority Mail Express SH Commercial”
      • An error response will be returned
    • Priority Mail Express Flat Rate Box (ID=”55”, “56”) will no longer be returned for any request, including <Service>=”All”, “Online”, “Plus”
  3. Elimination of Priority Mail Regional Rate Box C
    • “REGIONALRATEBOXC” will no longer be a valid <Container> enumeration
      • An error response will be returned
    • The Priority Mail Regional Rate Box C (ID=”58”, “59”) will no longer be returned for any request, including <Service>=”All”, “Online”, “Plus”
  4. Elimination of First-Class Package Service commercial plus pricing
    • When <Service>=”PLUS”, Web Tools will not return <CommercialPlusRate> for First Class Package Service (CLASS ID=”61”, “53”), regardless of weight less than or greater than 13 oz.
    • When <Service>=”ONLINE” and weight less than 16 oz., First Class Package Service (CLASS ID=”61”, “53”) with <CommercialRate> will be returned
  5. Rebranding of Parcel Select Nonpresort as Parcel Select Ground
    • For eligible customers: When <Service>=”ONLINE”, Web Tools will return new <MailService>=”Parcel Select Ground” value for CLASS ID=”77” (Parcel Select Nonpresort)
    • For eligible customers: Web Tools will support new <Service>=”PARCEL SELECT GROUND”
  6. Rebranding of Standard Post as Retail Ground
    • When <Service>=”STANDARD POST”, Web Tools will return new <MailService>=” USPS Retail Ground&lt;sup&gt;&#8482;&lt;/sup&gt;” value for CLASS ID=”4” (Standard Post)
    • When <Service>=” RETAIL GROUND”, Web Tools will return new <MailService>=” USPS Retail Ground&lt;sup&gt;&#8482;&lt;/sup&gt;” value for CLASS ID=”4” (Standard Post)

2.2      Domestic Label API Updates

2.2.1      Priority Mail, First Class Parcel / Package Service, Package Services label without postage (DeliveryConfirmationV4, SignatureConfirmationV4)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Elimination of Priority Mail Regional Rate Box C
      • “REGIONALRATEBOXC” will no longer be valid <Container> enumeration
        • An error response will be returned
      • Rebranding of Standard Post as Retail Ground
        • When <Service>=”STANDARD POST”, Web Tools will:
          • Return a Retail Ground label image
            • Banner Text = USPS RETAIL GROUND™
            • Service icon will remain the solid black box
          • Web Tools will support new <Service>=”RETAIL GROUND” and:
            • Return a Retail Ground label image
              • Banner Text = RETAIL GROUND
              • Service icon will remain the solid black box
  1. Customs compliance requirements for items destined to military (APO, FPO), diplomatic (DPO), and US Possessions, Territories and Freely Associated States (PTFAS) (see https://ribbs.usps.gov/index.cfm?page=intcustomsforms for customs requirements)
    • The following customs data XML inputs will be added to the request and applicable for items destined to the APO/FPO/DPO and PTFAS ZIP Codes:
      • <ShippingContents> / <ItemDetail> grouping
        • <Description> (required for each item, 256-character maximum)
        • <Quantity> (required for each item, numeric, 4-character maximum)
        • <Value> (required for each item, decimal, 8-character maximum, decimal and cents must be provided (i.e. 12.00))
        • <NetPounds> (ounces or pounds required for each item)
        • <NetOunces> (ounces or pounds required for each item)
        • <HSTariffNumber> (required tag, optional value, 12-character maximum)
        • <CountryOfOrigin> (required tag, optional value, full valid country name per the “Full Country Listing” at http://pe.usps.com/ 2-character ISO country code)
      • <FromPhone> (optional, 24-character maximum)
      • <SenderMID> (optional, numeric, 9-character maximum)
      • <ToPhone> (optional, 24-character maximum)
      • <CustomsContentType> (required)
        • Enumerations: MERCHANDISE, GIFT, DOCUMENTS, SAMPLE, RETURN, OTHER, HUMANITARIAN, DANGEROUSGOODS
      • <ContentComments> (required only when <CustomsContentType>=OTHER, 25-character maximum)
      • <RestrictionType> (optional)
        • Enumerations: QUARANTINE, SANITARY INSPECTION, PHYTOSANITARY INSPECTION, OTHER RESTRICTION
      • <RestrictionComments> (required only when <RestrictionType>=OTHER RESTRICTION, 25-character maximum)
      • <ImportersReference> (optional, 30-character maximum)
      • <ImportersContact> (optional, 50-character maximum)
      • <ExportersReference> (optional, 14-character maximum)
      • <ExportersContact> (optional, 50-character maximum, used for phone or email contact information)
      • <AESITN> (required, 35-character maximum)
      • <InvoiceNumber> (optional, 15-character maximum)
      • <LicenseNumber> (optional, 16-character maximum)
      • <CertificateNumber> (optional, 12-character maximum)
      • <NonDeliveryOption>
        • Valid enumerations: “Abandon”, “Return to Sender”, “Redirect” (redirect only available to domestic/US addresses)
        • When <NonDeliveryOption>=”Redirect”, use the following fields to indicate the domestic redirect information:
          • <AltReturnAddress1> (use this tag for an apartment or suite number)
          • <AltReturnAddress2> (use this tag for the primary street address)
          • <AltReturnAddress3> (use this tag for the city)
          • <AltReturnAddress4> (use this tag for the 2-digit state abbreviation)
          • <AltReturnAddress5> (use this tag for the 5-digit ZIP Code)
          • <AltReturnAddress6> <RedirectCity> (use this tag for the +4 portion of the ZIP Code)
          • <AltReturnCountry> (must be United States)
        • The response label image for items destined to APO/FPO/DPO and PTFAS ZIP Codes will be a single ply 4×6” 2976A or 2976 customs form with optional continuation page following the format guidelines at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
          • See Appendix A for customs form image sample

2.2.2      Priority Mail Express Labels without postage (ExpressMailLabel)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Elimination of Priority Mail Express Flat Rate Box
      • “FLAT RATE BOX” will no longer be valid <Container> enumeration
        • An error response will be returned
  1. Customs compliance requirements for items destined to military (APO, FPO), diplomatic (DPO), and US Possessions, Territories and Freely Associated States (PTFAS) (see https://ribbs.usps.gov/index.cfm?page=intcustomsforms for customs requirements)
    • The following customs data XML inputs will be added to the request and applicable for items destined to the APO/FPO/DPO and PTFAS ZIP Codes:
      • <ShippingContents> / <ItemDetail> grouping
        • <Description> (required for each item, 256-character maximum)
        • <Quantity> (required for each item, numeric, 4-character maximum)
        • <Value> (required for each item, decimal, 8-character maximum, decimal and cents must be provided (i.e. 12.00))
        • <NetPounds> (ounces or pounds required for each item)
        • <NetOunces> (ounces or pounds required for each item)
        • <HSTariffNumber> (required tag, optional value, 12-character maximum)
        • <CountryOfOrigin> (required tag, optional value, full valid country name per the “Full Country Listing” at http://pe.usps.com/ 2-character ISO country code)
      • <FromPhone> (optional, 24-character maximum)
      • <SenderMID> (optional, numeric, 9-character maximum)
      • <ToPhone> (optional, 24-character maximum)
      • <CustomsContentType> (required)
        • Enumerations: MERCHANDISE, GIFT, DOCUMENTS, SAMPLE, RETURN, OTHER, HUMANITARIAN, DANGEROUSGOODS
      • <ContentComments> (required only when <CustomsContentType>=OTHER, 25-character maximum)
      • <RestrctionType> (optional)
        • Enumerations: QUARANTINE, SANITARY INSPECTION, PHYTOSANITARY INSPECTION, OTHER RESTRICTION
      • <RestrictionComments> (required only when <RestrictionType>=OTHER RESTRICTION, 25-character maximum)
      • <ImportersReference> (optional, 30-character maximum)
      • <ImportersContact> (optional, 50-character maximum)
      • <ExportersReference> (optional, 14-character maximum)
      • <ExportersContact> (optional, 50-character maximum, used for phone or email contact information)
      • <AESITN> (required, 35-character maximum)
      • <InvoiceNumber> (optional, 15-character maximum)
      • <LicenseNumber> (optional, 16-character maximum)
      • <CertificateNumber> (optional, 12-character maximum)
      • <NonDeliveryOption>
        • Valid enumerations: “Abandon”, “Return to Sender”, “Redirect” (redirect only available to domestic/US addresses)
        • When <NonDeliveryOption>=”Redirect”, use the following fields to indicate the domestic redirect information:
          • <AltReturnAddress1> (use this tag for an apartment or suite number)
          • <AltReturnAddress2> (use this tag for the primary street address)
          • <AltReturnAddress3> (use this tag for the city)
          • <AltReturnAddress4> (use this tag for the 2-digit state abbreviation)
          • <AltReturnAddress5> (use this tag for the 5-digit ZIP Code)
          • <AltReturnAddress6> <RedirectCity> (use this tag for the +4 portion of the ZIP Code)
          • <AltReturnCountry> (must be United States)
        • The response label image for items destined to APO/FPO/DPO and PTFAS ZIP Codes will be a single ply 4×6” 2976B customs form with optional continuation page following the format guidelines at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
          • See Appendix A for customs form image sample

2.2.3      eVS payment labels (eVS)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Elimination of Priority Mail Express Flat Rate Box
      • “FLAT RATE BOX” will no longer be valid <Container> enumeration when <Service>=”EXPRESS”, “PRIORITY EXPRESS”, “PRIORITY EXPRESS CPP”
        • An error response will be returned
      • Elimination of Priority Mail Regional Rate Box C
        • “REGIONALRATEBOXC” will no longer be valid <Container> enumeration
          • An error response will be returned
        • Elimination of First-Class Package Service commercial plus pricing
          • Web Tools will return an error when <Service>=”FIRST CLASS” and <PriceOptions>=”COMMERCIAL PLUS”
          • When <Service>=”FIRST CLASS” and <PriceOptions>=”COMMERCIAL BASE” and weight is between 13 and 16 oz., the response will be successful and appropriate price returned
          • “ComPlsPrice” marking to left of permit indicia will no longer be shown
        • Rebranding of Parcel Select Nonpresort as Parcel Select Ground
          • When <Service>=”PARCEL SELECT NPS”, Web Tools will:
            • Return a Parcel Select Ground label image
              • Banner Text = PARCEL SELECT GROUND or PARCEL SELECT GND
              • Service icon will remain the solid black box
            • Web Tools will support new <Service>=”PARCEL SELECT GROUND”
              • Return a Parcel Select Ground label image
                • Banner Text = PARCEL SELECT GROUND or PARCEL SELECT GND
                • Service icon will remain the solid black box
              • Pharmaceuticals and medical supplies
                • New <ContentType> enumerations: “Pharmaceuticals”, “MedicalSupplies”
  1. Customs compliance requirements for items destined to military (APO, FPO), diplomatic (DPO), and US Possessions, Territories and Freely Associated States (PTFAS) (see https://ribbs.usps.gov/index.cfm?page=intcustomsforms for customs requirements)
    • The following customs data XML inputs will be added to the request and applicable for items destined to the APO/FPO/DPO and PTFAS ZIP Codes:
      • <ShippingContents> / <ItemDetail> grouping
        • <Description> (required for each item, 256-character maximum)
        • <Quantity> (required for each item, numeric, 4-character maximum)
        • <Value> (required for each item, decimal, 8-character maximum, decimal and cents must be provided (i.e. 12.00))
        • <NetPounds> (ounces or pounds required for each item)
        • <NetOunces> (ounces or pounds required for each item)
        • <HSTariffNumber> (required tag, optional value, 12-character maximum)
        • <CountryOfOrigin> (required tag, optional value, full valid country name per the “Full Country Listing” at http://pe.usps.com/ 2-character ISO country code)
      • <SenderMID> (optional, numeric, 9-character maximum)
      • <CustomsContentType> (required)
        • Enumerations: MERCHANDISE, GIFT, DOCUMENTS, SAMPLE, RETURN, OTHER, HUMANITARIAN, DANGEROUSGOODS
      • <ContentComments> (required only when <CustomsContentType>=OTHER, 25-character maximum)
      • <RestrctionType> (optional)
        • Enumerations: QUARANTINE, SANITARY INSPECTION, PHYTOSANITARY INSPECTION, OTHER RESTRICTION
      • <RestrictionComments> (required only when <RestrictionType>=OTHER RESTRICTION, 25-character maximum)
      • <ExportersReference> (optional, 14-character maximum)
      • <ExportersContact> (optional, 50-character maximum, used for phone or email contact information)
      • <ImportersReference> (optional, 30-character maximum)
      • <ImportersContact> (optional, 50-character maximum)
      • <AESITN> (required, 35-character maximum)
      • <InvoiceNumber> (optional, 15-character maximum)
      • <LicenseNumber> (optional, 16-character maximum)
      • <CertificateNumber> (optional, 12-character maximum)
      • <NonDeliveryOption>
        • Valid enumerations: “Abandon”, “Return to Sender”, “Redirect” (redirect only available to domestic/US addresses)
        • When <NonDeliveryOption>=”Redirect”, use the following fields to indicate the domestic redirect information:
          • <AltReturnAddress1> (use this tag for an apartment or suite number)
          • <AltReturnAddress2> (use this tag for the primary street address)
          • <AltReturnAddress3> (use this tag for the city)
          • <AltReturnAddress4> (use this tag for the 2-digit state abbreviation)
          • <AltReturnAddress5> (use this tag for the 5-digit ZIP Code)
          • <AltReturnAddress6> <RedirectCity> (use this tag for the +4 portion of the ZIP Code)
          • <AltReturnCountry> (must be United States)
        • The response label image for items destined to APO/FPO/DPO and PTFAS ZIP Codes will be a single ply 4×6” 2976B, 2976A or 2976 customs form with optional continuation page following the format guidelines at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
          • See Appendix A for customs form image sample

2.2.4      Priority Mail Express Hold For Pickup (HoldForPickupExpress)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Elimination of Priority Mail Express Flat Rate Box
      • “FLAT RATE BOX” will no longer be valid <Container> enumeration
        • An error response will be returned

2.2.5      Priority Mail Hold For Pickup (HoldForPickupPriority)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices

2.2.6      Merchandise Return Service (MerchandiseReturnServiceV4)

  1. Rebranding of LOR to Ground LOR (LOR=Limited Overland Route):
    • Limited Overland Route markings on the label image will be changed from “LOR” to “Ground LOR”

2.3      International Rate API Updates

2.3.1      IntlRateV2 January Price Change Updates

  1. Price and mailing restrictions updates
    • Price to price updates only; no request or response schema updates
    • Reference http://pe.usps.gov/ for updated prices
  2. Updated prohibitions, restrictions and mailing conditions for Bonaire, Sint Eustatius and Saba (no request or response schema updates)
  3. Priority Mail International (PMI) Insurance Changes
    • Summary: $200 of insurance will be included for PMI merchandise items and $100 of insurance will be included for non-negotiable documents (Note: This excludes the PMI Small Flat Rate Boxes and Flat Rate Envelopes; insurance will not be available or included for those items).
      • New <ContentType> enumerations: “Documents” or “NonnegotiableDocument” (these enumerations both refer to shippable/mailable non-negotiable documents)
      • When “Documents” or “NonnegotiableDocument” not provided, the contents will be will be considered Merchandise and include $200 of baked-in Insurance
    • Additional Insurance cannot be purchased for non-negotiable documents
    • Insurance for non-negotiable documents will not be returned in the response as an extra service service, though all non-negotiable documents are covered up to $100
    • <ParcelIndemnityCoverage> will no longer be returned. Automatic indemnity coverage has been replace by the baked-in Insurance amounts of $200 or $100
  4. Elimination of Priority Mail Express Flat Rate Box
    • The Priority Mail Express Flat Rate Boxes (Service ID=”26”) will no longer be returned for any request
  5. Expand Electronic USPS Delivery Confirmation International (eDelCon) to the following additional countries: Slovak Republic, Lebanon, Norway, Turkey
    • “Electronic USPS Delivery Confirmation International” (ServiceID=9) will be returned as an available extra service for First Class Package International Service (Service ID=”15”) to the following countries: Slovak Republic, Lebanon, Norway and Turkey

2.4      International Label and Customs Forms API Updates

2.4.1      Priority Mail Express International (ExpressMailIntl and eVSI-ExpressMailIntl)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Elimination of Priority Mail Express International Flat Rate Box
      • FLATRATEBOX will no longer be valid <Container> enumeration
        • An error response will be returned
      • Updated prohibitions, restrictions and mailing conditions for Bonaire, Sint Eustatius and Saba (no request or response schema updates)
      • Priority Mail Express International Insurance Changes
        • Summary: $200 of insurance will be included for PMEI merchandise items and $100 of insurance will be included for non-negotiable documents
          • Existing <ContentType> enumerations will be used to distinguish between merchandise and non-negotiable documents for insurance purposes
            • “Documents” = non-negotiable documents
            • All other <ContentType> values are considered merchandise
          • Additional Insurance cannot be purchased for non-negotiable documents
          • Insurance for non-negotiable documents will not be returned in the response as an extra service service, though all non-negotiable documents are covered up to $100
          • Label / customs forms image changes:
            • When no additional insurance is purchased, the Insured Value field will show either “up to $200” or “up to $100” depending on Merchandise v. Non-negotiable Documents
            • When additional insurance is purchased, the Insured Value field will show the total amount of insurance coverage (e.g. “$350”)
            • When no additional insurance is purchased, the Insurance Fees field will show “$0.00”
            • When additional insurance is purchased, the Insurance Fees field will show the amount paid for the additional insurance (e.g. “$20.50”)
  1. Single-ply customs forms updates: Effective January 2016, all Priority Mail Express International labels / customs forms destined to Canada, Australia and Costa Rica will contain only a single copy
    • When <ToCountry>=”Canada”, “Australia”. or “Costa Rica” only <LabelImage> will be populated
      • <Page2Image>, <Page3Image>, <Page4Image>, <Page5Image>, <Page6Image> will be empty
      • When a continuation page applies, the encoded image will be in the <Page2Image> response tag
  1. Customs forms / shipping label image updates
    • Effective January 2016, the Priority Mail Express International label / customs form will be redesigned to match 2976B specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • All image footprints will be approximately 4×6”; the 5×8” versions will no longer be supported
      • See Appendix A for customs form image sample

2.4.2      Priority Mail International (PriorityMailIntl and eVSI-PriorityMailIntl)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Updated prohibitions, restrictions and mailing conditions for Bonaire, Sint Eustatius and Saba (no request or response schema updates)
    • Priority Mail International Insurance Changes
      • Summary: $200 of insurance will be included for PMI merchandise items and $100 of insurance will be included for non-negotiable documents (Note: This excludes the PMI Small Flat Rate Boxes and Flat Rate Envelopes; insurance will not be available or included for those items).
        • Existing <ContentType> enumerations will be used to distinguish between merchandise and non-negotiable documents for insurance purposes
          • “Documents” = non-negotiable documents
          • All other <ContentType> values are considered merchandise
        • Insurance for non-negotiable documents will not be returned in the response as an extra service service, though all non-negotiable documents are covered up to $100
        • Additional Insurance cannot be purchased for non-negotiable documents
        • <ParcelIndemnityCoverage> will contain no value. Automatic indemnity coverage has been replace by the baked-in Insurance amounts of $200 or $100
        • Label / customs forms image changes:
          • When no additional insurance is purchased, the Insured Value field will show either “up to $200” or “up to $100” depending on Merchandise v. Non-negotiable Documents
          • When additional insurance is purchased, the Insured Value field will show the total amount of insurance coverage (e.g. “$350”)
          • When no additional insurance is purchased, the Insurance Fees field will show “$0.00”
          • When additional insurance is purchased, the Insurance Fees field will show the amount paid for the additional insurance (e.g. “$20.50”)
        • Eliminate Priority Mail International Regional Rate Box C (eVSI-PriorityMailIntl only)
          • “REGIONALRATEBOXC” will no longer be valid <Container> enumeration
            • Rate Engine will return an error response
          • Expand Electronic USPS Delivery Confirmation International (eDelCon) to the following additional countries: Slovak Republic, Lebanon, Norway, Turkey
            • eDelCon is only available when <Container>=”SMFLATRATEBOX”, “LGVIDEOBOX”, “DVDBOX”, “FLATRATEENV”, “LEGALFLATRATEENV”, “PADDEDFLATRATEENV”, “WINDOWFLATRATEENV”, “SMFLATRATEENV”, “GIFTCARDFLATRATEENV”
            • “Electronic USPS Delivery Confirmation International” (ServiceID=9) will be a valid <ExtraService> enumeration in requests to the following countries: Slovak Republic, Lebanon, Norway, and Turkey
            • The label will have the following:
              • Expres logo
              • L series barcode prefix
              • Receipt language: “USPS Tracking is available for this package.”
  1. Priority Mail International 2976A label / customs forms changes (when <Container>=”VARIABLE”, “RECTANGULAR”, “NONRECTANGULAR”, “LGFLATRATEBOX”, “MDFLATRATEBOX”, “FLATRATEBOX”)
    • Single-ply customs forms updates: Effective January 2016, all Priority Mail International labels / customs forms destined to Canada, Australia and Costa Rica will contain only a single copy
      • When <ToCountry>=”Canada”, “Australia”. or “Costa Rica” only <LabelImage> will be populated
        • <Page2Image>, <Page3Image>, <Page4Image>, <Page5Image>, <Page6Image> will be empty
        • When a continuation page applies, the encoded image will be in the <Page2Image> response tag
  • Customs forms / shipping label image updates
    • Effective January 2016, the Priority Mail International label / customs form will be redesigned to match 2976A specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • All image footprints will be approximately 4×6”; the 5×8” versions will no longer be supported
      • See Appendix A for customs form image sample
  1. Priority Mail International 2976 label / customs forms changes (when <Container>=”SMFLATRATEBOX”, “LGVIDEOBOX”, “DVDBOX”, “FLATRATEENV”, “LEGALFLATRATEENV”, “PADDEDFLATRATEENV”, “WINDOWFLATRATEENV”, “SMFLATRATEENV”, “GIFTCARDFLATRATEENV”)
    • Customs forms / shipping label image updates
      • Effective January 2016 the 4×6” version of the Priority Mail International 2976 label / customs form will be redesigned to match 2976 specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • See Appendix A for customs form image sample

2.4.3      First Class Mail International (FirstClassMailIntl and eVSI-FirstClassMailIntl)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices
    • Updated prohibitions, restrictions and mailing conditions for Bonaire, Sint Eustatius and Saba (no request or response schema updates)
    • Expand Electronic USPS Delivery Confirmation International (eDelCon) to the following additional countries: Slovak Republic, Lebanon, Norway, Turkey
      • “Electronic USPS Delivery Confirmation International” (ServiceID=9) will be a valid <ExtraService> enumeration in requests to the following countries: Slovak Republic, Lebanon, Norway, and Turkey
      • The label will have the following:
        • Expres logo
        • L series barcode prefix
        • Receipt language: “USPS Tracking is available for this package.”
  1. First Class Mail International (FCMI) / First Class Package International Service (FCPIS) 2976 label / customs forms changes
    • Customs forms / shipping label image updates
      • Effective January 2016, the 4×6” version of the FCMI / FCPIS 2976 label / customs form will be redesigned to match 2976 specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • See Appendix A for customs form image sample

2.4.4      Global Express Guaranteed (GXGGetLabel and eVSI-GXGGetLabel)

  1. January Price Change Updates
    • Price updates
      • Price to price updates only; no request or response schema updates
      • Reference http://pe.usps.gov/ for updated prices

2.4.5      Customs Form 2976A/CP72 (CustomsCP72V3)

  1. Single-ply customs forms updates: Effective January 2016, all 2976A customs forms destined to Canada, Australia and Costa Rica will contain only a single copy when <ImageParameter>=”4BY6LABEL”
    • When <ToCountry>=”Canada”, “Australia”. or “Costa Rica” only <LabelImage> will be populated
      • <Page2Image>, <Page3Image>, <Page4Image>, <Page5Image>, <Page6Image> will be empty
      • When a continuation page applies, the encoded image will be in the <Page2Image> response tag
  1. Customs forms / shipping label image updates
    • Effective January 2016, the 4×6” version of the Customs Form 2976A will be redesigned to match 2976A specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • All image footprints will be approximately 4×6”; the 5×8” versions will no longer be supported
      • See Appendix A for customs form image sample

2.4.6      Customs Forms 2976/CN22 (CustomsCN22V2)

  1. Customs Form 2976 changes
    • Customs forms / shipping label image updates
      • Effective January 2016, all 2976 customs forms will be redesigned to match 2976 specifications within the Guidelines for Privately Printed Customs Declaration Forms at https://ribbs.usps.gov/index.cfm?page=intcustomsforms
      • See Appendix A for customs form image sample

2.5      Other API Updates

2.5.1      Free Shipping Supplies (OrderSupplies)

  1. Elimination of Priority Mail Express Flat Rate Box
    • The following <SuppliesType>  enumerations are no longer valid when <Service> = ” EXPRESS”
      • EMFRB1
      • EMFRB1X
      • EMFRB2
      • EMFRB2X
  1. Elimination of Priority Mail Regional Rate Box C
    • The following <SuppliesType> enumeration will no longer be valid: “RRBC”

2.5.2      Package Tracking (Track, TrackV2)

  1. TBD

2.5.3      Package Pickup (CarrierPickupSchedule, CarrierPickupChange) *Deployment date to be determined

  1. Summary:
    • Updates to allow free, next-delivery day package pickup on city routes for shipments with only Ground mail classes.
    • Updates to restrict free, next-delivery day package pickup on rural routes to shipments that contain at least one of the following: Priority Mail Express, Priority Mail, Returns, International.
  2. XML request / response details:
    • CarrierPickupSchedule and CarrierPickupChange requests for pickup on city routes can be made when only “OtherPackages”, “FirstClass” or “ParcelSelect” are present (e.g. <ServiceType>=”OtherPackages” and <Count> is greater than “0”)
    • CarrierPickupSchedule and CarrierPickupChange requests for pickup on rural routes must contain at least one of either “PriorityMailExpress”, “PriorityMail”, “Returns” or “International” <ServiceType>

2.6      New and Recently Released APIs

Contact webtools@usps.gov for registration and detailed specifications for the following new APIs

2.6.1      Prices and Fees API

  1. Summary: Web Tools will create a new API that supports various discounts, fees, and surcharges

2.6.2      eVS International Label APIs

  1. Summary: Support for the following International Mail Classes was added to the USPS eVS label API offering in 2015:
    • Priority Mail Express International
    • Priority Mail International
    • First Class Mail International

2.6.3      Redelivery and Delivery Instructions APIs

  1. Summary: APIs are available to USPS partners that wish to offer Redelivery and Delivery Instructions capabilities within their ecommerce customer experience or USPS shipping fulfillment. Specific agreements with USPS are required.

2.6.4      Prepaid Forever Flat Rate Packaging API

  1. Summary: APIs are available to USPS partners that wish to offer Prepaid Forever Flat Rate Packaging to their customers. Specific agreements with USPS are required.

2.6.5      Package Intercept API

  1. Summary: APIs are available that allow initiation of a Package Intercept request and query for the status of a Package Intercept request. Specific agreements with USPS are required.

3. Appendices

3.1      Appendix A – Customs Forms / Label Images

3.1.1      eVS sample label / customs forms to military (APO/FPO) destination

eVS sample label / customs forms to military (APO/FPO) destination

Notes:

– The above format applies also to US Possessions, Territories and Freely Associated States

– The following APIs will have similar customs forms image outputs for military, diplomatic and Possessions, Territories and Freely Associated States: DeliveryConfirmationV4, SignatureConfirmationV4 and ExpressMailLabel API image outputs

– The image outputs will be a 2976B, 2976A or 2976 based on mail class; all will have the same dimensional footprint


3.1.2      International Customs Forms Label Images (PriorityMailIntl)

International Customs Forms Label Images (PriorityMailIntl)

Notes:

– All customs forms image outputs will be approximately 4×6 inches

– The following APIs will have similar customs forms image outputs: ExpressMailIntl, FirstClassMailIntl, CustomsCN22V2, CustomsCP72V3

– The image outputs will be a 2976B, 2976A or 2976 based on mail class; all will have the same dimensional footprint


3.2      Appendix B – Sample XML Requests

This section provides sample XML requests to the CAT/staging environment that demonstrate some of the changes implemented to our APIs in this release. These requests are provided as a reference to aid in your understanding of the changes and in your integration with our updated APIs. You should still complete all your usual testing and verification processes to ensure that your system is communicating properly with the most updated version of Web Tools.

Please note that you must place your valid USERID into the request. Sample responses are provided below the sample requests to illustrate the changes that will occur to the XML schema. Please note that the data within the tags may differ depending on inputs provided. Areas of note are highlighted.

RateV4 Sample Request (Section 2.1.1)

The response to this sample request illustrates some of the changes outlined in section 2.1.1, specifically the Standard Post name change.

http://stg-production.shippingapis.com/ShippingAPI.dll?API=RateV4&XML=<RateV4Request USERID=”xxxx”>

<Revision>2</Revision>

<Package ID=”0″>

<Service>Online</Service>

<FirstClassMailType> </FirstClassMailType>

<ZipOrigination>22201</ZipOrigination>

<ZipDestination>90210</ZipDestination>

<Pounds>8</Pounds>

<Ounces>2</Ounces>

<Container />

<Size>Regular</Size>

<Width>10</Width>

<Length>10</Length>

<Height>4</Height>

<Girth></Girth>

<Value>40</Value>

<SpecialServices>

<SpecialService></SpecialService>

</SpecialServices>

<Machinable>FALSE</Machinable>

</Package>

</RateV4Request>

 

RateV4 Response Updates

Standard Post name change highlighted.

<RateV4Response>

<Package ID=”0″>

<ZipOrigination>22201</ZipOrigination>

<ZipDestination>90210</ZipDestination>

<Pounds>8</Pounds>

<Ounces>2</Ounces>

<Container>VARIABLE</Container>

<Size>REGULAR</Size>

<Machinable>FALSE</Machinable>

<Zone>8</Zone>

<Postage CLASSID=”4″>

<MailService>USPS Retail Ground&lt;sup&gt;&#8482;&lt;/sup&gt;</MailService>

<Rate>31.16</Rate>

<SpecialServices>

<SpecialService>

<ServiceID>104</ServiceID>

<ServiceName>Certificate of Mailing (Form 3817)</ServiceName>

<Available>true</Available>

<Price>1.35</Price>

</SpecialService>

………………….

</Postage>

</Package>

</RateV4Response>

 

DeliveryConfirmationV4 Sample Request (Section 2.1.1)

This request illustrates the new customs data inputs required for military and diplomatic destinations and possessions, territories and freely associated states. The response schema will not be altered, however, a new label/customs form image will be returned (see Appendix A). These changes also apply to the following APIs: ExpressMailLabel, SignatureConfirmationV4, eVS

https://stg-secure.shippingapis.com/shippingapi.dll?API=DeliveryConfirmationV4&XML=<DeliveryConfirmationV4.0Request USERID=”xxxx”>

<Option>1</Option>

<Revision>2</Revision>

<ImageParameters />

<FromName>Samuel L Chafin</FromName>

<FromFirm />

<FromAddress1 />

<FromAddress2>901 D ST SW</FromAddress2>

<FromCity>WASHINGTON</FromCity>

<FromState>DC</FromState>

<FromZip5>20024</FromZip5>

<FromZip4>2169</FromZip4>

<ToName>Joseph Morgan</ToName>

<ToFirm>US ARMY</ToFirm>

<ToAddress1>UNIT 15345</ToAddress1>

<ToAddress2>61ST MAINT CO</ToAddress2>

<ToCity>APO</ToCity>

<ToState>AP</ToState>

<ToZip5>96258</ToZip5>

<ToZip4></ToZip4>

<WeightInOunces>10</WeightInOunces>

<ServiceType>Priority</ServiceType>

<InsuredAmount></InsuredAmount>

<WaiverOfSignature>False</WaiverOfSignature>

<SeparateReceiptPage>False</SeparateReceiptPage>

<POZipCode />

<ImageType>PDF</ImageType>

<CustomerRefNo>44</CustomerRefNo>

<AddressServiceRequested>True</AddressServiceRequested>

<SenderName />

<SenderEMail />

<RecipientName />

<RecipientEMail />

<AllowNonCleansedDestAddr>Y</AllowNonCleansedDestAddr>

<HoldForManifest>N</HoldForManifest>

<Container></Container>

<Size>Regular</Size>

<Width />

<Length />

<Height />

<Girth />

<Machinable>True</Machinable>

<CommercialPrice>true</CommercialPrice>

<ExtraServices>

<ExtraService>

</ExtraService></ExtraServices>

<ShippingContents>

<ItemDetail>

<Description>Description 1</Description>

<Quantity>9999</Quantity>

<Value>1.11</Value>

<NetPounds></NetPounds>

<NetOunces>1</NetOunces>

<HSTariffNumber>234567</HSTariffNumber>

<CountryOfOrigin>Australia</CountryOfOrigin>

</ItemDetail>

</ShippingContents>

<FromPhone>7175551212</FromPhone>

<SenderMID>123456789</SenderMID>

<ToPhone>5705551212</ToPhone>

<CustomsContentType>sample</CustomsContentType>

<ContentComments>Testing</ContentComments>

<RestrictionType>Phytosanitary Inspection</RestrictionType>

<RestrictionComments>Testing</RestrictionComments>

<AESITN>30.37a</AESITN>

<ImportersReference>IR-12345</ImportersReference>

<ImportersContact>j.morgan87@usps.gov</ImportersContact>

<ExportersReference>ER-12345</ExportersReference>

<ExportersContact>j.morgan87@usps.gov</ExportersContact>

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

</DeliveryConfirmationV4.0Request>

 

IntlRateV2 Response Updates (Section 2.3.1)

The response to this sample request illustrates some of the changes outlined in section 2.3.1, specifically the Insurance and Parcel Indemnity Coverage updates.

http://stg-production.shippingapis.com/ShippingApi.dll?API=IntlRateV2&XML=<IntlRateV2Request USERID=”xxxx”>

<Revision>2</Revision>

<Package ID=”0″>

<Pounds>2</Pounds>

<Ounces>0</Ounces>

<Machinable>False</Machinable>

<MailType>all</MailType>

<ValueOfContents>202</ValueOfContents>

<Country>Canada</Country>

<Container></Container>

<Size>REGULAR</Size>

<Width>4</Width>

<Length>10</Length>

<Height>8</Height>

<Girth></Girth>

<OriginZip>22201</OriginZip>

<CommercialFlag>Y</CommercialFlag>

<AcceptanceDateTime>2015-12-17T10:00:00-06:00</AcceptanceDateTime>

<DestinationPostalCode>A1A 1A1</DestinationPostalCode>

</Package>

</IntlRateV2Request>