# 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](#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. ```json { "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. ```json { "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_required | We need a product value of at least $2.00. | | ready_to_file | We have what we need. Filing waits for the USPS window. | | submitted | Filed with USPS. | | approved | USPS approved. Merchant Wallet payout follows USPS payment. | | denied | USPS denied the claim. | | expired | Past 60 days from ship date. Evidence is closed. | | failed | Filing 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 `value`s 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 Related: - [CustomsInfo](https://docs.easypost.com/docs/carrier-claims/usps-claims) - [CustomsItem](https://docs.easypost.com/docs/customs-infos) - [Customs Guide](https://docs.easypost.com/docs/customs-items) - [Create a Shipment](https://docs.easypost.com/guides/customs-guide) - [Trackers (BYO labels are not this API)](https://docs.easypost.com/docs/shipments#create-a-shipment)