In this section, we discuss the EasyPost shipment invoice, what it means with various carriers including USPS automated package verification (APV), and how it affects your USPS shipping label, USPS rate quote, and how to get the shipment invoice report from the EasyPost API.
What is a Shipment Invoice?
What is USPS Automated Package Verification?
What's in the Shipment Invoice Report?
Additional Columns
Additional Columns for ZIP info
Additional Columns for Disputes
Webhook Events
Related API Documentation
What is a Shipment Invoice?
EasyPost has a few products that get billed asynchronously. To help keep our customers informed about this billing activity, EasyPost provides a shipment invoice report and a shipment invoice webhook event.
The EasyPost Shipment Invoice is a report of any postage fee adjustments to your EasyPost account balance created within a specific date range. The shipment invoice report will list shipments created within a date range and includes any adjustments (such as USPS APV) sent to EasyPost from the carrier.
Whenever there are adjustments from the carrier, we’ll automatically send you a webhook event for each shipment to notify you that adjustments have been made to your EasyPost account balance. You can also generate a shipment invoice report at your convenience via an API call or the EasyPost Webhooks Dashboard which will contain all the adjustments during the timeframe you specified.
What is USPS Automated Package Verification (APV)?
When you create a USPS shipping label within EasyPost, the USPS sends a USPS quote for the rate you want to purchase the label for. Sometimes when you make a USPS shipping label, you might accidentally underpay for the shipment. When this happens, the USPS quote for the rate will no longer be valid, and an adjustment will be made to your account balance within EasyPost to deduct the incorrect amount paid for the shipping label and its postage. This is what USPS Automated Package Verification is, and is a good example of what is contained in the shipment invoice report from a given carrier. We recommend reading this article about the USPS APV process for more information.
What's in the Shipment Invoice Report?
You can access the Shipment Invoice Report in a .csv format through our Reports Object, which you can learn more about here.
Records are added to the report if the label_date (created date) of the shipment is within the date range specified by the user.
For example, if you request an adjustment report for January 2023, then adjustments associated with January shipping labels will be represented in the final file, regardless of the transaction date of the adjustment.
The .csv file contains the fields listed below with their definitions.
| Field | Definition or Sample Data |
|---|---|
| invoice_date | The date the User balance was adjusted |
| shipment_id | shp_…. |
| label_date | 2020-03-13T14:16:44Z |
| carrier_account_id | ca_... |
| carrier | Name of the carrier |
| tracking_code | 94001293405... |
| carrier_invoice_id | Nullable… invoice reference if provided by the carrier |
| package_dispute_id | Value to be referenced if you need to file a dispute |
| status | “processed” or “disputed” |
| quoted_currency | The currency associated with the shipment[selected_rate][rate] |
| initially_paid_amount | The postage fee that was incurred at the time of label creation |
| quoted_amount | shipment[selected_rate][rate] |
| claimed_length | shipment[parcel][length] |
| claimed_width | shipment[parcel][width] |
| claimed_height | shipment[parcel][height] |
| claimed_package | shipment[parcel][predefined_package] |
| claimed_service | shipment[selected_rate][service] |
| final_invoice_amount | The total amount that is due for the shipment |
| captured_length | The length of the package captured by the carrier upon processing the shipment. |
| captured_width | The width of the package captured by the carrier upon processing the shipment. |
| captured_height | The height of the package captured by the carrier upon processing the shipment. |
| captured_weight | The weight of the package captured by the carrier upon processing the shipment. This weight will be in ounces. |
| captured_package | The package type captured by the carrier upon processing the shipment. |
| captured_service | The service level determined by the carrier upon processing the shipment (ie - Service changed to Priority instead of First Class due to weight discrepancy) |
| captured_currency | The currency associated with the final invoice amount |
| adjustment_amount | The difference between the initially_paid_amount and the final_invoice_amount |
| adjustment_reason | The standardized reason for the adjustment |
| initially_paid_payment_log | The payment log associated with the initial payment |
| refund_payment_log | The payment log associated with the initial refund, if there is one |
| clawback_payment_log | The payment log associated with the initial payment, if invoiced |
| invoice_payment_log | The payment log associated with the adjustment_amount |
| user_id | user_... |
| user_parent_id | user_... |
Additional Columns
Additional Columns for ZIP Code Information
| Field | Definition or Sample Data |
|---|---|
| claimed_origin_zip | shipment[from_address][zip] |
| claimed_destination_zip | shipment[to_address][zip] |
| captured_origin_zip | The origin zip code of the package captured by the carrier upon processing the shipment. |
| captured_destination_zip | The destination zip code of the package captured by the carrier upon processing the shipment. |
Additional Columns for Disputes
You can request additional columns in your Shipment Invoice report that are helpful if you dispute any adjustments with the carrier.
| Field | Definition or Sample Data |
|---|---|
| dispute_received_at | When the carrier received your dispute, if applicable |
| dispute_status | Current dispute status ("pending", "approved", "denied"), if applicable |
| dispute_resolution_date | When the final dispute status (approved/denied) was determined, if applicable |
| dispute_resolution_payment_log | The payment log if the dispute was approved (only available for resolutions after April 1, 2022) |
Webhook Events
If you have a webhook associated with your EasyPost account, EasyPost will send you a webhook event whenever a shipment is audited and your balance is adjusted.
Example:
{
"result": {
"id": "ppshp_...",
"object": "ShipmentInvoice",
"mode": "production",
"status": "processed",
"user_id": "user_...",
"order_id": null,
"shipment_id": "shp_...",
"tracking_code": "94001...",
"label_date": "2022-02-10T21:02:42Z",
"quoted_amount": "4.83",
"quoted_currency": "USD",
"initially_paid_amount": "4.83000",
"initially_paid_currency": "US5",
"initially_paid_payment_log": "paylog_...",
"adjustment_reason": "Weight",
"adjustment_amount": "1.60000",
"invoice_date": "2022-02-16T00:40:03Z",
"invoice_type": "adjustment",
"invoice_amount": "1.60000",
"invoice_currency": "US5",
"invoice_payment_log": "paylog_...",
"total_cost": "6.43000",
"carrier_account": "ca_...",
"carrier": "USPS",
"claimed_details": {
"from_address": {
"zip": "15017-1590",
"state": "PA",
"country": "US"
},
"to_address": {
"zip": "59301-3140",
"state": "MT",
"country": "US"
},
"parcel": {
"length": null,
"width": null,
"height": null,
"weight": 10.0,
"predefined_package": null
},
"service": "First",
"carrier": "USPS"
},
"captured_details": {
"from_address": {
"zip": "15017-1590",
"state": "PA",
"country": "US"
},
"to_address": {
"zip": "59301-3140",
"state": "MT",
"country": "US"
},
"parcel": {
"length": null,
"width": null,
"height": null,
"weight": 12.48,
"predefined_package": "PARCEL"
},
"service": "First",
"carrier": "USPS"
},
"package_dispute_id": "123..."
},
"description": "shipment.invoice.created",
"mode": "production",
"previous_attributes": null,
"completed_urls": null,
"user_id": "user_...",
"status": "pending",
"object": "Event",
"id": "evt_..."
}