Guides

USPS Claims Guide

Accounts are enrolled in EP Guard by default. EasyPost watches EasyPost-purchased USPS labels. If we already have product value, we file. If we do not, we email a weekly CSV of the claims that can still be filed once you add a product value. Approved money goes to the enrolled merchant’s Wallet after USPS pays.

This guide is USPS-only. Other carriers will be added later. This is not EasyPost Insurance and not for bring-your-own tracking.

Use a User API key for API calls. Full request and response fields are on the UspsClaim API.

1. EP Guard is on by default

USPS claims enrollment is already on. Open Carrier Claims / EP Guard in the EasyPost Dashboard to see claims. No separate enroll step is required.

To rehearse the rest of this guide without a production label, create a test-mode claim. See Try it without a live label.

2. Optionally send product value when you ship

If EasyPost already has a merchandise total of at least $2.00, we can file later without asking. New integrations should send line_items. If the shipment already includes a customs form, EasyPost can use those item values instead. If you skip both, the claim still appears when the label is lost or damaged — you supply the value then.

line_items

Pass line_items when you create the shipment. This is the claims integration. EasyPost keeps line_items internally. They are not sent to USPS, they do not appear on the Shipment response, and they are not used for anything except USPS Claims.

Each object in line_items must include:

  • total_line_value (string): The total value of the line.
  • item_description (string): A brief description of the item.
{
  "line_items": [
    {
      "total_line_value": "129.00",
      "item_description": "Mugs"
    },
    {
      "total_line_value": "45.50",
      "item_description": "T-shirts"
    }
  ]
}

CustomsInfo (when you already send a customs form)

If the shipment includes a CustomsInfo with CustomsItems, EasyPost uses the sum of each item's value. That value is the total USD for the line (quantity already included — do not multiply again). You do not also send line_items when those values are already on the customs form.

CustomsInfo is how you send an international customs form. The same object can be attached on a domestic USPS shipment. Nested create examples live on Create a Shipment and the Customs Guide.

{
  "customs_info": {
    "eel_pfc": "NOEEI 30.37(a)",
    "customs_certify": true,
    "customs_signer": "Steve Brule",
    "contents_type": "merchandise",
    "restriction_type": "none",
    "customs_items": [
      {
        "description": "T-shirts",
        "quantity": 1,
        "weight": 5,
        "value": 10.0,
        "origin_country": "US"
      }
    ]
  }
}

Product value is the value of the package or order. Do not use the shipment's insurance amount.

3. EasyPost files, or EasyPost asks

You can submit evidence any time before 60 days from ship date, including before the USPS filing window opens. EasyPost files during that window (typically 30–60 days from ship date; military destinations start later). Expired claims cannot accept evidence.

Declared product value must be at least $2.00; larger amounts are accepted. USPS pays out up to $100.00 unless additional insurance was purchased. The negotiated EasyPost USPS Claims Fee is charged to the enrolled merchant.

Status
Meaning
action_requiredWe need a product value of at least $2.00.
ready_to_fileWe have what we need. Filing waits for the USPS window.
submittedFiled with USPS.
approvedUSPS approved. Merchant Wallet payout follows USPS payment.
deniedUSPS denied the claim.
expiredPast 60 days from ship date. Evidence is closed.
failedFiling or processing failed.

If we already have product value, you can skip the next step. If we do not, the claim shows up in EP Guard and on needs_info. That is expected. Sending line_items or CustomsInfo at create is an optimization, not the requirement to get paid.

4. When a claim needs you

Find the claims

  1. The weekly email. It attaches a CSV of claims that can still be filed, but only after you add a product value.
  2. GET /v2/carrier_claims/usps_claims/needs_info
  3. Carrier Claims / EP Guard in the Dashboard.

Supply the missing information

Your team has the value

  • Reply to the weekly email with a CSV or XLSX. Each row needs a shipment ID or a tracking number, and product_value (USD, at least $2.00). Set the addresses in EP Guard, separated by commas. EasyPost emails the CSV to every address every Monday at 13:00 UTC. When you save, leave the box unchecked to wait for Monday, or check it to email the current file now.
  • Many claims: POST /v2/carrier_claims/usps_claims/evidence.
  • One claim, or a few: POST /v2/carrier_claims/usps_claims/:id/evidence.

You have a CSM and a spreadsheet

Your CSM will reach out. Send them any spreadsheet that has a tracking number or a shipment ID, and a product value.

See needs_info and evidence.

5. Watch status

Poll:

  • All claims: GET /v2/carrier_claims/usps_claims
  • One claim: GET /v2/carrier_claims/usps_claims/:id
  • Only claims that still need you: GET /v2/carrier_claims/usps_claims/needs_info

When a claim is Approved, payout follows USPS payment, then lands in the EasyPost Wallet.

Try it without a live label

Use a test User API key:

POST /v2/carrier_claims/usps_claims

Pass a tracking code. That creates a mode=test claim you can list and submit evidence for. EasyPost will not file it with USPS. Production claims are created automatically from eligible purchased labels — you cannot POST those.

See Create a test-mode USPS Claim.

Multi-store accounts

Child production keys work when the parent is enrolled. Parent keys do not include child-user claims unless you pass include_children=true on list, needs_info, retrieve, and evidence. The Dashboard always expands children.

Limits

Full field reference: UspsClaim API.

  • Product value minimum $2.00; larger declared values are accepted
  • USPS pays out up to $100.00 unless additional insurance was purchased
  • Approved payouts are subject to the negotiated EasyPost USPS Claims Fee
  • Evidence until 60 days from ship date; EasyPost files in the USPS window

FAQs

Q: Is this EasyPost Insurance?

No. USPS Claims are indemnity claims on EasyPost-purchased USPS labels. EasyPost Insurance is a separate product and API.

Q: Can I try the API without a production USPS label?

Yes. Use a test User API key to POST /v2/carrier_claims/usps_claims with a tracking code. EasyPost will not file that claim with USPS.

Q: Should I send line_items or CustomsInfo?

Send line_items when you are integrating USPS Claims. line_items are only for claims. If the shipment already has CustomsItem values on a CustomsInfo for an international customs form, EasyPost uses those and you do not also send line_items. See the Customs Guide.

Q: Will line_items appear in the shipment API response?

No. line_items are retained internally for claims and are not returned on the Shipment object. customs_info is a normal Shipment field and is returned.

Q: Can I send evidence before day 30?

Yes. Submit any time before day 60. Filing waits until the USPS window.

Q: Can EasyPost email me the claims that still need a product value?

Yes. Set the addresses in EP Guard, separated by commas. EasyPost emails the CSV to every address every Monday at 13:00 UTC. When you save, leave the box unchecked to wait for Monday, or check it to email the current file now. Reply with a CSV or XLSX that has a shipment ID or tracking number, and product_value.

Q: Can a parent API key list child-user claims?

Yes. Pass include_children=true. The default is that key's user only. Child production keys already work when the parent is enrolled. The Dashboard always expands children.

Additional Resources