USPS Automated Package Verification — Global Ecommerce APIs documentation (2024)

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 parcel. USPS uses technologies that capture parcel 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 parcel is shipped to issue an adjustment. Most adjustments occur within a few days of the parcel being shipped. APV applies only to domestic parcels and does not apply to letters and envelopes. To learn more about APV, go to https://www.usps.com/business/verify-postage.htm.

To test APV transactions in the Sandbox environment, please contact Client Support at [email protected].

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 parcel.

How can a merchant ensure postage is calculated accurately when printing a label?¶

Merchants should ensure they have the correct weight, dimensions, services, and packaging by following the USPS instructions at https://www.usps.com/business/verify-postage.htm.

To calculate whether dimensional (DIM) weight applies, merchants can use the Pitney Bowes DIM-weight calculator at https://www.pitneybowes.com/us/dimcalculator.html.

How do merchants know if there have been APV adjustments?¶

To check whether your merchants have received 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 transaction returned for an APV adjustment for incorrect weight. Not all the transaction’s fields are shown. For a complete example of an APV transaction, see Sample APV Adjustment at the end of this page.

{ "transactionId": "12345678_86bd33", "transactionDateTime": "2020-07-08T22:30:22.026+0000", "transactionType": "APV-POSTAGE UNDERPAID", ..., "developerRateAmount": 5.14, ..., "merchantRate": 5.14, ..., "parcelTrackingNumber": "940550989841491959942", "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. The amount is the difference between the original charge and the recalculated charge. The amount has been either added or subtracted from the postage account.

  See Also

  Shipping Calculator - Compare Shipping Rates USPS, UPS, FedEx

• The externalId is the USPS Revenue Assurance ID. Use this if there is a dispute of the APV adjustment.

• The adjustmentReason indicates why the adjustment was made. The reason can be any of the following:

  • Incorrect weight, dimensions, or parcel type.

  • Incorrect sender or induction postal code.

  • The shipment used a label that had already been used.

  • The shipment used a label that had been submitted for refund.

  In this case the adjustment is for incorrect weight, and the weightInOunces field 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 amount debited is more than the postage balance, an auto refill is triggered to replenish the account balance.

How does a merchant dispute an APV adjustment?¶

If a merchant believes an APV adjustment to be in error, the merchant can dispute the adjustment. The merchant should send an email with the reason for the dispute to USPS at [email protected]. The email should include the following:

• IMpb (Tracking) Number.

• Revenue Assurance ID. This is the externalId in the Transaction Reports API response.

• Detailed reason for the dispute.

• Contact information (name and email).

To view the status of the dispute, see How does a merchant view the status of an APV dispute?

How does a merchant view the status of an APV dispute?¶

If a merchant has disputed an APV adjustment, you can return the status of the dispute through the Transaction Reports API. The API returns a transaction when:

• USPS reports to Pitney Bowes that a merchant has filed an APV dispute.

• USPS reports the resolution of the APV dispute.

A transaction for an APV dispute has the following values for the following fields:

• The content.transactionType is set to APV-DISPUTE ADJUSTMENT.

• The content.status reports the status of the dispute:

  • REQUESTED: The merchant has filed the dispute, and the dispute is pending.

  • ACCEPTED: USPS has resolved in favor of the dispute. Pitney Bowes will credit the underpayment amount to the postage balance.

  • DENIED. USPS has resolved against the dispute.

• content.adjustmentReason reports the reason for a resolved dispute.

The following is an example of a transaction returned for a pending dispute:

{ "transactionId": "24458850-904673", "transactionType": "APV-DISPUTE ADJUSTMENT", ..., "adjustmentReason": "pending dispute adjustment", "status": "REQUESTED", ...}

The following is an example of a transaction returned for a resolved dispute:

{ "transactionId": "24458850-904673", "transactionType": "APV-DISPUTE ADJUSTMENT", ..., "adjustmentReason": "approved dispute adjustment", "status": "ACCEPTED", ...}

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.

{ "transactionId": "12345678_024a5d", "transactionDateTime": "2020-07-01T14:30:22.026+0000", "transactionType": "POSTAGE PRINT", "developerName": "ABC", "developerId": "12345678", "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, "shipmentId": "USPS1100572858248722", "refundRequestor": null, "externalId": null, "adjustmentReason": null}

{ "transactionId": "12345678_024a5d", "transactionDateTime": "2020-07-08T08:02:18.012+0000", "transactionType": "APV-POSTAGE UNDERPAID", "developerName": "ABC", "developerId": "12345678", "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, "shipmentId": "USPS1100572858248722", "refundRequestor": null, "externalId": "000001393103414", "adjustmentReason": "weight"}