Claims

The Claims API allows shippers to automate submitting and managing insurance claims for lost, damaged, or stolen packages. This endpoint streamlines claim submissions and provides an automated experience. Claims can be submitted via the EasyPost Dashboard, a Claim Submission Form, or the Claims API.

For USPS carrier indemnity claims on EasyPost-purchased labels (EP Guard), use the USPS Claims API instead. Do not send those through /claims.

Endpoints

POST

/claim_payout_reports/:month

Functionality

The Claims endpoint offers the following functionalities:

Claims Creation: Accepts necessary information to create a claim.
Claims Validation: Ensures claims meet specific criteria before processing.
Claims Storage: Stores claim details and attachments.
Claims Responses: Provides automated responses for successful and unsuccessful claims.
Claim Messages: Delivers follow-ups to your system and accepts replies with attachments. See the Claim Messages Guide.

Claims process

Claim Submission: The claim is submitted via the EasyPost Dashboard, a Claim Submission Form, or Claims API endpoint.
Claim Validation: The system validates the claim to ensure it meets the necessary criteria (e.g., valid tracking code, proper claim type, sufficient evidence for the type of claim).
Claim Storage: Once validated, the claim details and attachments are stored.
Claim Review: The claim undergoes a review process, which may involve manual review by the support team to verify the claim’s validity and completeness.
Claim Updates: The status of the claim is updated based on the outcome of the review. Possible statuses include:
1. submitted
2. in_review
3. approved
4. approved_partial
5. rejected
6. cancelled
7. needs_action
Automated Response: An automated response is sent to the user with the current status of the claim.
Notifications: Webhooks report follow-ups, replies, approval, and denial. See the Claim Messages Guide. Send replies with Create a Claim Message.
Claim Resolution: Approved claims are paid. approved_amount is the amount. Rejected claims put the denial reason in status_detail.

Claim object

string

Unique identifier for the claim.

object

string

Type of object, which is 'Claim'

mode

string

Indicates whether the claim is in test or production mode.

insurance_id

string

Identifier for the associated insurance.

shipment_id

string

Identifier for the associated shipment.

reference

string

The reference for this Claim, if any

tracking_code

string

Tracking code for the shipment.

status

enum

submitted in_review approved rejected approved_partial cancelled needs_action

status_detail

string

Reason for the current status. On a rejected claim, show this sentence. It names the missing or unclear proof when EasyPost knows which file that was.

status_timestamp

datetime

Timestamp for when the status changed (could differ from the updated_at field, which is specific to the Claim object).

type

enum

Type of claim being filed: loss, theft, damage

history

ClaimHistoryEntry array

History of status changes for the Claim.

insurance_amount

string

Amount of insurance coverage.

requested_amount

string

Amount of the claim. When the submitted amount is above the purchased insurance coverage, this is that coverage amount.

approved_amount

string

Amount approved for reimbursement.

salvage_value

string

Salvage value of the damaged item.

description

string

Detailed description of of the claim.

attachments

array

A list of links to supporting evidence attachments.

recipient_name

string

The name of the entity to be paid from EasyPost for this Insurance Claim.

contact_email

string

The email of the entity to be paid from EasyPost for this Insurance Claim.

payment_method

enum

Method of payment for the claim reimbursement: mailed_check easypost_wallet

check_delivery_address

string

Address where the check should be mailed, if applicable.

created_at

datetime

Timestamp for when the claim was created.

updated_at

datetime

Timestamp for the last update to the claim.

Claim Object

{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/a915d0e238074fff9729afa1bfb87a0e.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/3020f31a57374dc3ace477f7a4ec860d.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/88aada9e505f4e77bd6060710d78e497.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2025-05-12T19:08:04Z",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2025-05-12T19:08:04Z"
    }
  ],
  "id": "clm_09d89e88a0c943d59018bc26b041c41c",
  "insurance_amount": "100.00",
  "insurance_id": "ins_da31156b6335407da23ee06fa2fe8a28",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_531f76e4a4de491183f5cabb738cb828",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2025-05-12T19:08:04Z",
  "tracking_code": "9405500208303109888319",
  "type": "damage",
  "updated_at": "2025-05-12T19:08:04Z"
}

ClaimHistoryEntry Object

status

enum

submitted, in_review, approved, rejected, approved_partial, cancelled, needs_action

status_detail

string

Reason recorded for that status. On rejected, this is the denial sentence.

status_timestamp

datetime

Timestamp for when the status changed (could differ from the updated_at field, which is specific to the Claim object).

ClaimHistoryEntry Object

{
  "approved_amount": null,
  "attachments": [
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/a915d0e238074fff9729afa1bfb87a0e.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/3020f31a57374dc3ace477f7a4ec860d.png",
    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/88aada9e505f4e77bd6060710d78e497.png"
  ],
  "check_delivery_address": null,
  "contact_email": "test@example.com",
  "created_at": "2025-05-12T19:08:04Z",
  "description": "Test description",
  "history": [
    {
      "status": "submitted",
      "status_detail": "Claim was created.",
      "timestamp": "2025-05-12T19:08:04Z"
    }
  ],
  "id": "clm_09d89e88a0c943d59018bc26b041c41c",
  "insurance_amount": "100.00",
  "insurance_id": "ins_da31156b6335407da23ee06fa2fe8a28",
  "mode": "test",
  "object": "Claim",
  "payment_method": "easypost_wallet",
  "recipient_name": null,
  "requested_amount": "100.00",
  "salvage_value": null,
  "shipment_id": "shp_531f76e4a4de491183f5cabb738cb828",
  "status": "submitted",
  "status_detail": "Claim was created.",
  "status_timestamp": "2025-05-12T19:08:04Z",
  "tracking_code": "9405500208303109888319",
  "type": "damage",
  "updated_at": "2025-05-12T19:08:04Z"
}

Create a Claim

Create a new claim for a shipment. This endpoint accepts the necessary information to create and validate a claim and store the details.

If amount is greater than the purchased insurance coverage, the claim is accepted and requested_amount is set to that coverage. An approved claim pays only the purchased coverage.

Request Parameters

tracking_code

i.e. 123456789

Tracking code for the shipment.

type

i.e. damage

Type of claim being filed.

amount

i.e. 25.50

Amount being claimed for reimbursement. If this is greater than the purchased insurance coverage, the claim is accepted and requested_amount is that coverage amount.

reference

i.e. external-order-493

An optional value that may be used in place of ID when doing Retrieve calls for this claim.

email_evidence_attachments

i.e. base64 encoded string (TWFueSBoYW5kcyBtYW….)

Attachments providing evidence via email.

invoice_attachments

i.e. base64 encoded string (TWFueSBoYW5kcyBtYW….)

Attachments of invoices as evidence.

supporting_documentation_attachments

i.e. (required if “type” is “theft” or “damage”) i.e., base64 encoded string (TWFueSBoYW5kcyBtYW….) (optional)

Supporting documents for the claim.

description

i.e. My package arrived damaged; the box was crushed.

Detailed description of the claim.

recipient_name

i.e. Carrie Parcel

The name of the entity to be paid from EasyPost for this Insurance Claim.

contact_email

i.e. name@example.com

The email of the entity to be paid from EasyPost for this Insurance Claim.

POST /claims

1curl -X POST https://api.easypost.com/v2/claims \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "type": "damage",
6    "email_evidence_attachments": ["REPLACE_WITH_BASE64_STRING"],
7    "invoice_attachments": ["REPLACE_WITH_BASE64_STRING"],
8    "supporting_documentation_attachments": ["REPLACE_WITH_BASE64_STRING"],
9    "description": "Test description",
10    "contact_email": "test@example.com",
11    "tracking_code": "YOUR_TRACKING_CODE",
12    "amount": "100.00"
13  }'

Response

1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/a915d0e238074fff9729afa1bfb87a0e.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/3020f31a57374dc3ace477f7a4ec860d.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/88aada9e505f4e77bd6060710d78e497.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2025-05-12T19:08:04Z",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "submitted",
15      "status_detail": "Claim was created.",
16      "timestamp": "2025-05-12T19:08:04Z"
17    }
18  ],
19  "id": "clm_09d89e88a0c943d59018bc26b041c41c",
20  "insurance_amount": "100.00",
21  "insurance_id": "ins_da31156b6335407da23ee06fa2fe8a28",
22  "mode": "test",
23  "object": "Claim",
24  "payment_method": "easypost_wallet",
25  "recipient_name": null,
26  "requested_amount": "100.00",
27  "salvage_value": null,
28  "shipment_id": "shp_531f76e4a4de491183f5cabb738cb828",
29  "status": "submitted",
30  "status_detail": "Claim was created.",
31  "status_timestamp": "2025-05-12T19:08:04Z",
32  "tracking_code": "9405500208303109888319",
33  "type": "damage",
34  "updated_at": "2025-05-12T19:08:04Z"
35}

Retrieve all Claims

Retrieve a list of claims.

Request Parameters

type

string

status

string

before_id

i.e. ins_...

Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.

after_id

i.e. ins_...

Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.

start_datetime

i.e. 2016-01-02T00:00:00Z

Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.

end_datetime

i.e. 2016-01-02T00:00:00Z

Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.

page_size

i.e. 30

The number of records to return on each page. The maximum value is 100, and default is 20.

GET /claims

1curl -X GET "https://api.easypost.com/v2/claims?page_size=5" \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "claims": [
3    {
4      "approved_amount": null,
5      "attachments": [
6        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/2384384e13a14d2eb6513b6f4fa3e7db.png",
7        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/695260b95d0743a284bf0bf1eea7421c.png",
8        "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/f369b8e2ce894e798c14850684fd16fe.png"
9      ],
10      "check_delivery_address": null,
11      "contact_email": "test@example.com",
12      "created_at": "2025-05-12T19:08:07Z",
13      "description": "Test description",
14      "history": [
15        {
16          "status": "submitted",
17          "status_detail": "Claim was created.",
18          "timestamp": "2025-05-12T19:08:07Z"
19        }
20      ],
21      "id": "clm_09d891bf4d9045b48cb64e0319338f1c",
22      "insurance_amount": "100.00",
23      "insurance_id": "ins_e5d632db2ede497e83de78e0c6cc5a60",
24      "mode": "test",
25      "object": "Claim",
26      "payment_method": "easypost_wallet",
27      "recipient_name": null,
28      "requested_amount": "100.00",
29      "salvage_value": null,
30      "shipment_id": "shp_1152edb694924af2a5ca3c5d4fba45d3",
31      "status": "submitted",
32      "status_detail": "Claim was created.",
33      "status_timestamp": "2025-05-12T19:08:07Z",
34      "tracking_code": "9405500208303109888326",
35      "type": "damage",
36      "updated_at": "2025-05-12T19:08:07Z"
37    }
38  ],
39  "has_more": true
40}

Retrieve a Claim

Retrieve details of a specific claim using the id.

GET /claims/:id

1curl -X GET https://api.easypost.com/v2/claims/clm_... \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/2384384e13a14d2eb6513b6f4fa3e7db.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/695260b95d0743a284bf0bf1eea7421c.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/f369b8e2ce894e798c14850684fd16fe.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2025-05-12T19:08:07Z",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "submitted",
15      "status_detail": "Claim was created.",
16      "timestamp": "2025-05-12T19:08:07Z"
17    }
18  ],
19  "id": "clm_09d891bf4d9045b48cb64e0319338f1c",
20  "insurance_amount": "100.00",
21  "insurance_id": "ins_e5d632db2ede497e83de78e0c6cc5a60",
22  "mode": "test",
23  "object": "Claim",
24  "payment_method": "easypost_wallet",
25  "recipient_name": null,
26  "requested_amount": "100.00",
27  "salvage_value": null,
28  "shipment_id": "shp_1152edb694924af2a5ca3c5d4fba45d3",
29  "status": "submitted",
30  "status_detail": "Claim was created.",
31  "status_timestamp": "2025-05-12T19:08:07Z",
32  "tracking_code": "9405500208303109888326",
33  "type": "damage",
34  "updated_at": "2025-05-12T19:08:07Z"
35}

Cancel a Claim

Cancel an existing claim using the id

POST /claims/:id/cancel

1curl -X POST https://api.easypost.com/v2/claims/clm_.../cancel \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "approved_amount": null,
3  "attachments": [
4    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/e85d5ec7bd2f44bcbfecaddd7b8fbdc9.png",
5    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/dc795c3604cb40e7a6fe37762cbff8de.png",
6    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20250512/01403d1550d44fd3a5dde2fc7e0c5314.png"
7  ],
8  "check_delivery_address": null,
9  "contact_email": "test@example.com",
10  "created_at": "2025-05-12T19:08:10Z",
11  "description": "Test description",
12  "history": [
13    {
14      "status": "cancelled",
15      "status_detail": "Claim cancellation was requested.",
16      "timestamp": "2025-05-12T19:08:11Z"
17    },
18    {
19      "status": "submitted",
20      "status_detail": "Claim was created.",
21      "timestamp": "2025-05-12T19:08:10Z"
22    }
23  ],
24  "id": "clm_09d81405ad494f6ca8bcbf884f207bc4",
25  "insurance_amount": "100.00",
26  "insurance_id": "ins_2f140b24c17d4e66a3223d621ef4beee",
27  "mode": "test",
28  "object": "Claim",
29  "payment_method": "easypost_wallet",
30  "recipient_name": null,
31  "requested_amount": "100.00",
32  "salvage_value": null,
33  "shipment_id": "shp_11f0e96492bd4e03918cb34021d49521",
34  "status": "cancelled",
35  "status_detail": "Claim cancellation was requested.",
36  "status_timestamp": "2025-05-12T19:08:11Z",
37  "tracking_code": "9405500208303109888333",
38  "type": "damage",
39  "updated_at": "2025-05-12T19:08:11Z"
40}

Retrieve a Claim Payout Report

Retrieve the payout snapshot for one closed UTC month, YYYY-MM.

This report is only for accounts on EasyPost's monthly claim payout flow. Any other account receives a 404. A month that has not been closed into a snapshot also returns 404.

The response is that snapshot. total_amount is the bank payment. Each claims entry is one approved claim, and the payout_amount values sum to total_amount. payout_id is the payment id once the payout has been sent, and is null before then.

Send format=csv or Accept: text/csv for the same snapshot as a spreadsheet. Each row is one claim. charge_amount is the payout for that claim, not the insurance premium, and those amounts sum to the bank payment.

GET /claim_payout_reports/:month

1curl -X GET https://api.easypost.com/v2/claim_payout_reports/2026-08 \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "id": "cps_09d89e88a0c943d59018bc26b041c41c",
3  "object": "ClaimPayoutReport",
4  "mode": "production",
5  "period": "2026-08",
6  "status": "pending_approval",
7  "payout_id": null,
8  "claim_count": 1,
9  "total_amount": "25.00",
10  "claims": [
11    {
12      "claim_id": "clm_09d89e88a0c943d59018bc26b041c41c",
13      "tracking_code": "EZ1000000001",
14      "reference": "order-100",
15      "shipment_id": "shp_09d89e88a0c943d59018bc26b041c41c",
16      "insurance_id": "ins_09d89e88a0c943d59018bc26b041c41c",
17      "type": "loss",
18      "status": "approved",
19      "requested_amount": "25.00",
20      "approved_amount": "25.00",
21      "payout_amount": "25.00"
22    }
23  ]
24}

Retrieve Claim Messages

Retrieve the follow-ups EasyPost has sent for a claim and the replies posted back through the API. Messages are returned oldest first.

Request Parameters

before_id

i.e. cmsg_...

Optional pagination parameter. Only messages created before the given ID will be included. May not be used with after_id.

after_id

i.e. cmsg_...

Optional pagination parameter. Only messages created after the given ID will be included. May not be used with before_id.

page_size

i.e. 20

The number of records to return on each page. The maximum value is 100, and default is 20.

GET /claims/:id/messages

1curl -X GET https://api.easypost.com/v2/claims/clm_.../messages \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "messages": [
3    {
4      "id": "cmsg_8f0c1c2e4b6a4d0a9c1e2f3a4b5c6d7e",
5      "object": "ClaimMessage",
6      "mode": "production",
7      "claim_id": "clm_09d89e88a0c943d59018bc26b041c41c",
8      "direction": "outbound",
9      "body": "This ticket is being handled by our Automated Insurance Claim Assistant.\n\nSend proof of purchase that shows the completed purchase, line items, and total — an invoice, receipt, checkout thank-you screenshot, or order-confirmation email. This is required; the claim may be rejected if you cannot provide it:\n\n- the purchase invoice or receipt — so we can confirm the item and its value — this is required, and the claim may be rejected without it (for example, a checkout thank-you screenshot or order confirmation email that shows the completed purchase, line items, and total)",
10      "attachments": [],
11      "created_at": "2026-09-26T17:04:11Z",
12      "updated_at": "2026-09-26T17:04:11Z"
13    }
14  ],
15  "has_more": false
16}

Create a Claim Message

Reply to a claim follow-up. body is the reply text. attachments are base64-encoded images or PDFs, using the same encoding as claim creation. Send idempotency_key, up to 64 ASCII characters, to make a retry return the original message. A retry sent while the first request is still being delivered returns 409; send it again with the same key.

EasyPost adds the reply to the claim conversation. Later follow-ups arrive as claim.message webhooks. The flow is described in the Claim Messages Guide.

Request Parameters

body

string

Reply text. Required when attachments is empty.

attachments

string array

Base64-encoded images or PDFs. Up to 10 files, each up to 10 MB. Required when body is empty.

idempotency_key

string

Optional key, up to 64 ASCII characters. A repeat request with the same key returns the original message. A repeat sent while the first request is still being delivered returns 409; send it again with the same key.

POST /claims/:id/messages

1curl -X POST https://api.easypost.com/v2/claims/clm_.../messages \
2  -u "EASYPOST_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5    "body": "Here is the order confirmation showing the item and the total.",
6    "attachments": ["REPLACE_WITH_BASE64_STRING"],
7    "idempotency_key": "order-confirmation-1"
8  }'

Response

1{
2  "id": "cmsg_1a2b3c4d5e6f708192a3b4c5d6e7f809",
3  "object": "ClaimMessage",
4  "mode": "production",
5  "claim_id": "clm_09d89e88a0c943d59018bc26b041c41c",
6  "direction": "inbound",
7  "body": "Here is the order confirmation showing the item and the total.",
8  "attachments": [
9    "https://easypost-files.s3-us-west-2.amazonaws.com/insurance/20260926/a915d0e238074fff9729afa1bfb87a0e.jpg"
10  ],
11  "created_at": "2026-09-26T17:12:44Z",
12  "updated_at": "2026-09-26T17:12:44Z"
13}