USPS Automated Package Verification

What is USPS® Automated Package Verification (APV)?

Automated Package Verification (APV) is the process by which USPS automatically verifies if accurate postage has been applied to a package. USPS uses technologies that capture package properties, including weight and dimension, and then calculates the correct postage amount. If the calculated postage differs from the postage paid, USPS notifies Pitney Bowes of the discrepancy, and Pitney Bowes applies the adjustment to the postage account. USPS has up to 30 days after a package is shipped to issue an adjustment. Most adjustments occur within a few days of the package being shipped. A label can have only one adjustment.

APV applies only to domestic packages and does not apply to letters and envelopes. You can learn more about APV at https://www.usps.com/business/verify-postage.htm.

To test APV transactions in the sandbox environment, please contact the Shipping API Support team at ShippingAPISupport@pb.com.

What are the benefits of APV over manual postage due?

By eliminating the need to manually collect additional postage through the postage-due process, APV eliminates shipment delays and the need for collection upon delivery from recipients, which allows USPS to maintain competitive and economical shipping prices for their customers.

How can I ensure postage is calculated accurately when I print a label?

Ensure you have the correct weight, dimensions, service, and packaging for your shipment by following the USPS instructions at https://www.usps.com/business/verify-postage.htm. To calculate whether dimensional (DIM) weight applies, use the USPS DIM weight calculator at https://www.usps.com/dimensionalweight/.

How will I know if there has been an APV adjustment?

To check for APV adjustments, use the Transaction Reports API. Each APV adjustment is reported as a separate transaction, with the transactionType field set to either APV-POSTAGE OVERPAID or APV-POSTAGE UNDERPAID. The transaction includes the corrected shipment information and the amount credited or debited from the postage account.

To return only APV adjustments, set the transactionType query parameter to one of the following when making the API call:

  • APV-POSTAGE ALL: All APV adjustments
  • APV-POSTAGE OVERPAID: Overpays only
  • APV-POSTAGE UNDERPAID: Underpays only

To return adjustments for a particular merchant, use the merchantId query parameter. If you manage merchant postage through a Bulk Postage Account, you can use the Transaction Reports API to determine the adjustments to apply to each merchant. If a merchant closes an account, Pitney Bowes recommends that you hold the merchant’s account balance for at least a month in order to cover any underpays.

The following is an example request to retrieve all APV adjustments posted in the last 31 days:

curl -X GET .../v4/ledger/developers/<id>/transactions/reports?transactionType=APV-POSTAGE%20ALL \
-H "Authorization: Bearer <oauth_token>"

The following is an example adjustment. Not all fields are shown. See also this example at the end of the page.

{
    "transactionId": "44397664_86bd33",
    "transactionDateTime": "<timestamp>",
    "transactionType": "APV-POSTAGE UNDERPAID",
    ...,
    "developerRateAmount": 5.14,
    ...,
    "merchantRate": 5.14,
    ...,
    "parcelTrackingNumber": "<tracking_number>",
    "weightInOunces": 18,
    ...,
    "externalId": "000001065208938",
    "adjustmentReason": "Weight"
}
  • The transactionId and parcelTrackingNumber are the values from the original shipment.
  • The transactionDateTime is the timestamp of the adjustment.
  • The developerRateAmount and merchantRate are the amount of the adjustment, which is the difference between the original charge and the recalculated charge. The amount has been either added or subtracted from the postage account.
  • The externalId is the USPS Revenue Assurance ID for use in case of a dispute.
  • The adjustmentReason can be for weight, dimensions, package type, or zone. In this case it is weight, and weightInOunces gives the adjusted weight.

Does the Merchant Portal display APV adjustments?

Yes. Merchants with their own Pitney Bowes-managed postage accounts can view APV adjustments by logging into the Merchant Portal and navigating to the Transaction History page. They can use search filters to retrieve APV adjustments and can expand adjustments to view details, including adjustment amount, reason for adjustment, and adjustment ID.

What happens if the postage account does not have sufficient funds?

If the postage amount being debited is more than the postage balance, an auto refill is triggered to replenish the account balance. The adjustment transaction then debits the adjustment amount from the postage balance.

Does APV take into account my discounted rates?

Yes. APV takes into account your specific discounted rates when recalculating the postage amount that should have been paid for a package.

Will USPS apply cubic rates when calculating an APV adjustment amount?

No. If USPS detects that a parcel has the wrong mail class and assigns the parcel to Priority Mail, USPS APV will automatically apply weight-based rates and will not check the cubic rates, even if they are available.

How do I dispute an adjustment?

To file a dispute, email USPS at VerifyPostageHelp@usps.gov. Ensure your email contains the following:

  • IMpb (Tracking) Number.
  • Revenue Assurance ID. This is the externalId in the Transaction Reports API response.
  • Detailed reason for the dispute.
  • Your contact information (name and email).

A Pitney Bowes representative will get in touch with you once Pitney Bowes receives information on your dispute status from USPS. You can learn more about APV at https://www.usps.com/business/verify-postage.htm.

How long does it take USPS to review a dispute?

Most responses can be expected within 5 business days, and at most, 15 business days.

Sample APV Adjustment

The following is a side-by-side comparison of two transactions returned by the Transaction Reports API for the same shipment. The first transaction is for the creation of the label; the second is for an APV adjustment.

Print Transaction APV Transaction for Underpayment
{
    "transactionId": "44397664_024a5d",
    "transactionDateTime": "<timestamp>",
    "transactionType": "POSTAGE PRINT",
    "developerName": "ABC",
    "developerId": "44397664",
    "developerPostagePaymentMethod": null,
    "developerRatePlan": "<rate_plan>",
    "developerRateAmount": 6.78,
    "developerPostagePaymentAccountBalance": null,
    "merchantName": "shipper-abc",
    "merchantId": "9024324564",
    "merchantPostageAccountPaymentMethod": "OTHER",
    "merchantRatePlan": null,
    "merchantRate": null,
    "shipperPostagePaymentAccountBalance": 2286.44,
    "labelFee": null,
    "parcelTrackingNumber": "<tracking_number>",
    "weightInOunces": 4,
    "zone": "8",
    "packageLengthInInches": 17,
    "packageWidthInInches": 1,
    "packageHeightInInches": 11,
    "packageTypeIndicator": "NonCubic",
    "packageType": "PKG",
    "mailClass": "Priority Mail",
    "internationalCountryPriceGroup": null,
    "originationAddress": "<address>",
    "originZip": "<zip>",
    "destinationAddress": "<address>",
    "destinationZip": "<zip>",
    "destinationCountry": "US",
    "postageDepositAmount": null,
    "creditCardFee": null,
    "refundStatus": null,
    "refundDenialReason": null,
    "printStatus": null,
    "shipmentId": "USPS1100572858248722",
    "refundRequestor": null,
    "externalId": null,
    "adjustmentReason": null
}
{
    "transactionId": "44397664_024a5d",
    "transactionDateTime": "<timestamp>",
    "transactionType": "APV-POSTAGE UNDERPAID",
    "developerName": "ABC",
    "developerId": "44397664",
    "developerPostagePaymentMethod": null,
    "developerRatePlan": "<rate_plan>",
    "developerRateAmount": 2.66,
    "developerPostagePaymentAccountBalance": null,
    "merchantName": "shipper-abc",
    "merchantId": "9024324564",
    "merchantPostageAccountPaymentMethod": "OTHER",
    "merchantRatePlan": null,
    "merchantRate": null,
    "shipperPostagePaymentAccountBalance": 2835.48,
    "labelFee": null,
    "parcelTrackingNumber": "<tracking_number>",
    "weightInOunces": 26,
    "zone": "8",
    "packageLengthInInches": 17,
    "packageWidthInInches": 1,
    "packageHeightInInches": 11,
    "packageTypeIndicator": null,
    "packageType": "PKG",
    "mailClass": "Priority Mail",
    "internationalCountryPriceGroup": null,
    "originationAddress": null,
    "originZip": "<zip>",
    "destinationAddress": null,
    "destinationZip": null,
    "destinationCountry": "US",
    "postageDepositAmount": null,
    "creditCardFee": null,
    "refundStatus": null,
    "refundDenialReason": null,
    "printStatus": null,
    "shipmentId": "USPS1100572858248722",
    "refundRequestor": null,
    "externalId": "000001393103414",
    "adjustmentReason": "weight"
}