API Docs
USPS Claims

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.

Endpoints
GET
/carrier_claims/usps_claims
POST
/carrier_claims/usps_claims
GET
/carrier_claims/usps_claims/needs_info
GET
/carrier_claims/usps_claims/:id
POST
/carrier_claims/usps_claims/:id/evidence
POST
/carrier_claims/usps_claims/evidence

UspsClaim object

id
string
Unique identifier, begins with "usc_"
object
string
"UspsClaim"
mode
string
"test" or "production". Matches the User API key used. Test claims are never filed with USPS.
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.
UspsClaim Object
{
  "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

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.
UspsClaimRecipient Object
{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "company": null
}

Retrieve all USPS Claims

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.

Request Parameters

status
i.e. action_required
Optional public status filter.
claim_type
i.e. lost
Optional lost or damaged filter
tracking_code
i.e. 9400111899223344556677
Optional tracking code filter
shipment_id
i.e. shp_...
Optional EasyPost Shipment id filter
include_children
i.e. false
Also include claims owned by child users. Defaults to false. Child keys still only see that child's claims. The Dashboard already expands children.
page_size
i.e. 20
Number of records to return. Maximum 100, default 20.
after_id
i.e. usc_...
Cursor: only records after this id. Do not combine with before_id.
before_id
i.e. usc_...
Cursor: only records before this id. Do not combine with after_id.
GET /carrier_claims/usps_claims
1curl -X GET https://api.easypost.com/v2/carrier_claims/usps_claims \
2  -u $EASYPOST_API_KEY:
Response
1{
2  "usps_claims": [
3    {
4      "id": "usc_...",
5      "object": "UspsClaim",
6      "mode": "production",
7      "tracking_code": "9400111899223344556677",
8      "shipment_id": "shp_...",
9      "claim_type": "lost",
10      "status": "action_required",
11      "product_value": null,
12      "claimable_amount": null,
13      "description": null,
14      "recipient": {
15        "first_name": "Ada",
16        "last_name": "Lovelace",
17        "company": null
18      },
19      "shipment_date": "2026-08-01",
20      "filing_window_closes_at": "2026-09-30",
21      "missing": ["product_value"],
22      "submitted_at": null,
23      "approved_at": null
24    }
25  ],
26  "has_more": false
27}

Create a test-mode USPS Claim

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.

Request Parameters

tracking_code
i.e. EZ1000000001
Required. Any tracking code for this rehearsal claim.
claim_type
i.e. lost
Optional. "lost" (default) or "damaged".
shipment_id
i.e. shp_...
Optional EasyPost Shipment id to store on the claim.
POST /carrier_claims/usps_claims
1curl -X POST https://api.easypost.com/v2/carrier_claims/usps_claims \
2  -u $EASYPOST_TEST_API_KEY: \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "tracking_code": "EZ1000000001",
6    "claim_type": "lost"
7  }'
Response
1{
2  "id": "usc_...",
3  "object": "UspsClaim",
4  "mode": "test",
5  "tracking_code": "EZ1000000001",
6  "shipment_id": "shp_test_...",
7  "claim_type": "lost",
8  "status": "action_required",
9  "product_value": null,
10  "claimable_amount": null,
11  "missing": ["product_value"]
12}

Retrieve USPS Claims that need additional info

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.

Request Parameters

include_children
i.e. false
Also include claims owned by child users. Defaults to false. Child keys still only see that child's claims. The Dashboard already expands children.
page_size
i.e. 20
Number of records to return. Maximum 100, default 20.
after_id
i.e. usc_...
Cursor: only records after this id. Do not combine with before_id.
before_id
i.e. usc_...
Cursor: only records before this id. Do not combine with after_id.
GET /carrier_claims/usps_claims/needs_info
1curl -X GET https://api.easypost.com/v2/carrier_claims/usps_claims/needs_info?include_children=true \
2  -u $EASYPOST_API_KEY:
Response
1{
2  "usps_claims": [
3    {
4      "id": "usc_...",
5      "object": "UspsClaim",
6      "mode": "production",
7      "tracking_code": "9400111899223344556677",
8      "shipment_id": "shp_...",
9      "claim_type": "lost",
10      "status": "action_required",
11      "product_value": null,
12      "claimable_amount": null,
13      "description": null,
14      "recipient": {
15        "first_name": "Ada",
16        "last_name": "Lovelace",
17        "company": null
18      },
19      "shipment_date": "2026-08-01",
20      "filing_window_closes_at": "2026-09-30",
21      "missing": ["product_value"],
22      "submitted_at": null,
23      "approved_at": null
24    }
25  ],
26  "has_more": false
27}

Retrieve a USPS Claim

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

Request Parameters

include_children
i.e. false
Also include claims owned by child users. Defaults to false. Child keys still only see that child's claims. The Dashboard already expands children.
GET /carrier_claims/usps_claims/:id
1curl -X GET https://api.easypost.com/v2/carrier_claims/usps_claims/usc_...?include_children=true \
2  -u $EASYPOST_API_KEY:
Response
1{
2  "id": "usc_...",
3  "object": "UspsClaim",
4  "mode": "production",
5  "tracking_code": "9400111899223344556677",
6  "status": "ready_to_file",
7  "product_value": "25.00",
8  "claimable_amount": "25.00",
9  "description": "Ceramic mug",
10  "recipient": {
11    "first_name": "Ada",
12    "last_name": "Lovelace",
13    "company": null
14  },
15  "missing": [],
16  "submitted_at": null,
17  "approved_at": null
18}

Submit USPS Claim evidence

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.

Request Parameters

include_children
i.e. false
Also include claims owned by child users. Defaults to false. Child keys still only see that child's claims. The Dashboard already expands children.
product_value
i.e. 25.00
Declared goods value. Minimum $2.00; larger amounts are accepted. USPS pays out up to $100.00 unless additional insurance was purchased.
POST /carrier_claims/usps_claims/:id/evidence
1curl -X POST https://api.easypost.com/v2/carrier_claims/usps_claims/usc_.../evidence?include_children=true \
2  -u $EASYPOST_API_KEY: \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "product_value": "25.00"
6  }'
Response
1{
2  "id": "usc_...",
3  "object": "UspsClaim",
4  "mode": "production",
5  "tracking_code": "9400111899223344556677",
6  "status": "ready_to_file",
7  "product_value": "25.00",
8  "claimable_amount": "25.00",
9  "description": "Ceramic mug",
10  "recipient": {
11    "first_name": "Ada",
12    "last_name": "Lovelace",
13    "company": null
14  },
15  "missing": [],
16  "submitted_at": null,
17  "approved_at": null
18}

Submit USPS Claim evidence in bulk

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.

Request Parameters

include_children
i.e. false
Also include claims owned by child users. Defaults to false. Child keys still only see that child's claims. The Dashboard already expands children.
claims
i.e. [{ "id": "usc_...", "product_value": "25.00" }]
Claims to update. Each object uses the same fields as single evidence submit, plus the claim id.
POST /carrier_claims/usps_claims/evidence
1curl -X POST https://api.easypost.com/v2/carrier_claims/usps_claims/evidence?include_children=true \
2  -u $EASYPOST_API_KEY: \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "claims": [
6      {
7        "id": "usc_...",
8        "product_value": "25.00"
9      }
10    ]
11  }'
Response
1{
2  "summary": { "processed_count": 1, "failed_count": 0 },
3  "usps_claims": [{
4  "id": "usc_...",
5  "object": "UspsClaim",
6  "mode": "production",
7  "tracking_code": "9400111899223344556677",
8  "status": "ready_to_file",
9  "product_value": "25.00",
10  "claimable_amount": "25.00",
11  "description": "Ceramic mug",
12  "recipient": {
13    "first_name": "Ada",
14    "last_name": "Lovelace",
15    "company": null
16  },
17  "missing": [],
18  "submitted_at": null,
19  "approved_at": null
20}
21],
22  "failed_claims": {}
23}