# USPS Claims

USPS Claims are for **USPS labels bought through EasyPost**. Accounts are enrolled in EP Guard by default.
EasyPost files eligible labels when product value is on file.
Send `line_items` at shipment create so EasyPost has product value before a claim needs action. `line_items` are claims-only. If the shipment already has a CustomsInfo for a customs form, EasyPost uses each CustomsItem `value` instead.
See the USPS Claims Guide, Create a Shipment, and the Customs Guide.
Use this API when a claim still needs product value, or to follow claim status.

Authenticate with a **User API key** through `api.easypost.com`. Test keys see only `mode=test` claims. Production keys see only `mode=production` claims. Each key can only list, retrieve, and update claims owned by that key's user. Child production keys work when the parent is enrolled. Parent keys do not include child-user claims unless you pass `include_children=true` (the Dashboard already expands children).

This is **not** EasyPost Insurance `/claims`.
This is **not** for bring-your-own labels or standalone Tracker registrations.

Unenrolled accounts receive `422`. To rehearse without production labels, create a test-mode claim with a **test** User API key. Test claims are never filed with USPS.

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. Approved payouts are subject to the negotiated EasyPost USPS Claims Fee. EasyPost pays out the enrolled merchant via EasyPost Wallet once the claim is approved and paid out by USPS.

Submit evidence any time before the claim expires (60 days from ship date). EasyPost files with USPS during the USPS filing window.

Step-by-step onboarding: USPS Claims Guide.
Check status with `needs_info` or by listing claims.

---

## UspsClaim object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique identifier, begins with "usc_" |
| object | string | "UspsClaim" |
| tracking_code | string | USPS tracking code for the EasyPost-purchased label |
| shipment_id | string | EasyPost Shipment id (shp_...) |
| claim_type | string | "lost" or "damaged" |
| status | string | Public status: "action_required", "ready_to_file", "submitted", "approved", "denied", "expired", or "failed". Internal pipeline states are not returned. |
| product_value | string | Declared goods value in USD. Minimum $2.00; larger amounts are accepted. Optional until the claim needs action. Send line_items at shipment create. If the shipment already has nested CustomsItem value on a CustomsInfo, EasyPost uses that sum instead. |
| claimable_amount | string | Amount EasyPost will file with USPS. USPS pays out up to $100.00 unless additional insurance was purchased. |
| description | string | Merchandise description already stored on the claim. Not accepted on evidence submit. |
| recipient | UspsClaimRecipient | Recipient already on the shipment. Not accepted on evidence submit. |
| shipment_date | date | Ship date used to compute expiry (60 days) and the USPS filing window |
| filing_window_closes_at | date | Last day EasyPost can file this claim with USPS (60 days from ship date) |
| missing | string[] | "product_value" when a value of at least $2.00 is still required before filing |
| submitted_at | datetime | When the claim was filed with USPS. Null until it is filed. |
| approved_at | datetime | When USPS paid the claim. Null unless status is approved. |

Example Object:

```json
{
  "id": "usc_...",
  "object": "UspsClaim",
  "mode": "production",
  "tracking_code": "9400111899223344556677",
  "status": "ready_to_file",
  "product_value": "25.00",
  "claimable_amount": "25.00",
  "description": "Ceramic mug",
  "recipient": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "company": null
  },
  "missing": [],
  "submitted_at": null,
  "approved_at": null
}
```

---

## UspsClaimRecipient object

| Property | Type | Description |
|----------|------|-------------|
| first_name | string | Recipient first name already on the shipment. Null when it was not provided. |
| last_name | string | Recipient last name already on the shipment. Null when it was not provided. |
| company | string | Recipient company already on the shipment. Null when it was not provided. |

Example Object:

```json
{
  "id": "usc_...",
  "object": "UspsClaim",
  "mode": "production",
  "tracking_code": "9400111899223344556677",
  "status": "ready_to_file",
  "product_value": "25.00",
  "claimable_amount": "25.00",
  "description": "Ceramic mug",
  "recipient": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "company": null
  },
  "missing": [],
  "submitted_at": null,
  "approved_at": null
}
```

---

## Retrieve all USPS Claims

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Cursor-paginated (`after_id` / `before_id` / `page_size`). Filter with `status`, `claim_type`, `tracking_code`, or `shipment_id`. Pass `include_children=true` on a parent User API key to include child-user claims.

See Pagination for cursor details.

---

## Create a test-mode USPS Claim

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

**Test mode only.** Use a test User API key to create a rehearsal claim so you can exercise `needs_info` and evidence submit without a production USPS label.

Production keys receive `422`. Production claims are created automatically from eligible EasyPost-purchased labels.

Test claims are never filed with USPS.

---

## Retrieve USPS Claims that need additional info

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Returns unexpired claims (`status` is `action_required`, still within 60 days of ship date) that still need product value.

Use this instead of listing every claim when you only need to collect product value.

Cursor-paginated (`after_id` / `before_id` / `page_size`). Pass `include_children=true` on a parent User API key to include child-user claims.

---

## Retrieve a USPS Claim

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Retrieve one `UspsClaim` by its `usc_` id. Pass `include_children=true` on a parent User API key to retrieve a child-user claim.

---

## Submit USPS Claim evidence

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Submit `product_value` only. Sending the request is consent under the EasyPost terms of service.

Evidence may be submitted any time before the claim expires, including before the USPS filing window opens. EasyPost files during the filing window.
Evidence may be replaced until the claim is `submitted`. Pass `include_children=true` on a parent User API key to update a child-user claim.

---

## Submit USPS Claim evidence in bulk

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

JSON batch for merchants building their own collector. Each item needs an `id` (`usc_...`) and `product_value`.
Partial success returns `207` with `failed_claims`. Pass `include_children=true` on a parent User API key to update child-user claims.