Creating and managing Claims

A claim is what you file with us when a shipment goes wrong, either it never showed up (LOST) or it arrived broken (DAMAGED). You send us the shipment info and what you’re claiming, and Opereit takes it from there: preparing documentation and running the claim through the carrier’s process. This page walks through the practical stuff: what you need before you call the API, what the fields actually mean, and a few things that’ll trip you up if you don’t know about them. For the full field-by-field breakdown, see the API Reference.

Before you start

You’ll need:

An API key (see Authentication if you don’t have one yet).
The shipment’s tracking number and carrier.
The destination address the parcel was headed to.
What’s being claimed: item(s), quantity, price, and the total amount you’re claiming.

Creating a claim

curl -X POST "https://api.opereit.ai/v1/claims" \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment": {
      "tracking_number": "1Z999AA1234567890",
      "carrier": "UPS",
      "line_items": [
        { "description": "Electronic Component", "quantity": 2, "unit_price": 15000, "currency": "EUR" }
      ],
      "origin": { "postcode": "28001", "country": "ES" },
      "destination": {
        "postcode": "08001",
        "country": "ES",
        "city": "Barcelona",
        "address": "Passeig de Gràcia, 5",
        "customer_name": "John Doe",
        "customer_phone": "+34987654321"
      }
    },
    "incidence": {
      "type": "DAMAGED",
      "description": "Items arrived with cracked casing.",
      "claimed_amount": 30000,
      "currency": "EUR"
    }
  }'

A few things worth knowing about the fields:

Amounts are always in the smallest unit of the currency, not decimals, so unit_price: 15000 and claimed_amount: 30000 above mean €150.00 and €300.00 (EUR has 2 decimal places, so the minor unit is 1/100). That conversion isn’t the same for every currency, e.g. JPY has no decimal places at all, so 150 JPY is sent as 150, not 15000. Check the ISO 4217 minor unit for whatever currency you’re sending before assuming ×100.
claimed_amount is independent of line_items. We don’t sum the line items for you, whatever you put in incidence.claimed_amount is the amount that gets claimed. Line items are there to document what was in the shipment, not to calculate the total.
destination.city, address, and customer_name are all required. customer_phone is optional, but if you send one it needs to be 6 to 20 characters.
carrier has to be one of the values below. Anything else gets rejected with a 400 before we even touch the shipment.

Supported carriers


`BPOST`	`BRT`	`CHRONOPOST`	`CORREOS`
`CORREOS_EXPRESS`	`CTT`	`DPD`	`EVRI`
`FEDEX`	`GLS`	`INPOST`	`MAERSK`
`PAACK`	`PC_COMPONENTES`	`POSTAG`	`SEUR`
`UPS`

If your carrier isn’t on this list, get in touch, we’re adding more regularly.

The `provider` field

provider is optional and only relevant if you booked the shipment through a multi-carrier platform or aggregator rather than directly with the carrier. Most integrations can just leave it out. Known values:


`BPOST`	`BRT`	`CHRONOPOST`	`CORREOS`
`CORREOS_EXPRESS`	`CTT`	`DPD`	`EVRI`
`FEDEX`	`GLS`	`INPOST`	`MAERSK`
`PAACK`	`PC_COMPONENTES`	`POSTAG`	`SENDCLOUD`
`SEUR`	`UPS`	`WING`

Filing more than one claim for the same tracking number

You can only have one open claim per tracking number at a time, if one’s already open, a second POST for the same tracking_number gets a 409. A claim counts as closed (not open) when it’s:

REJECTED, for any reason, or
CANCELED with a status reason of CREATED_INCORRECTLY or SHIPMENT_NOT_CLAIMABLE_YET (see Status reasons below).

Any other status, including a CANCELED claim with a different reason, still counts as open.

Once a shipment’s tracking number has been used for a claim before, sending it again reuses the shipment record we already have on file. That means the origin and destination you send only actually get saved the first time a claim is filed for that tracking number. If you file a second claim later (say, the first one got resolved and now something else went wrong with the same parcel), the origin/destination in the response will reflect what was originally submitted, not whatever you sent this time around. If an address genuinely changed, that’s a case for support rather than the API.

DAMAGED vs LOST

There isn’t much nuance here. LOST means the parcel never arrived. DAMAGED means it did arrive, but something inside was broken, missing, or otherwise not right. Use incidence.description to say what actually happened, it helps a lot when the claim gets reviewed and when we’re building the paperwork for the carrier.

What happens after you create a claim

Every claim starts at CREATED. From there it moves through review with the carrier, and eventually lands somewhere final. Here’s the full list:

Status	Meaning
`CREATED`	Just filed, hasn’t been reviewed yet.
`UNDER_REVIEW`	The carrier is looking at it.
`PENDING_ACTION`	We need to do something on our end before it can move forward.
`PENDING_REFUND`	A refund is coming, but the amount isn’t confirmed yet.
`PENDING_REFUND_AMOUNT_CONFIRMED`	The refund amount is confirmed, just hasn’t been paid out yet.
`RESOLVED`	Done, resolved in your favor.
`CANCELED`	The claim was withdrawn. Closed if the reason was `CREATED_INCORRECTLY` or `SHIPMENT_NOT_CLAIMABLE_YET`, open otherwise, see above.
`REJECTED`	The carrier rejected it. Always closed, regardless of the reason.
`CLOSED`	Closed out, for reasons other than the above.

Status reasons

PENDING_ACTION, CANCELED, and REJECTED also come with a status_reason, extra detail on specifically why the claim landed there. Every other status leaves status_reason as null.

PENDING_ACTION

Reason	What it means
`RESTRICTED_ACCOUNT_VIEW`	Restricted account view.
`PENDING_UPLOAD_DOCUMENTS`	We’re waiting on documents to be uploaded.
`UPDATE_ITEMS_INFORMATION`	The item information needs to be updated.
`TRACKING_REVIEW_REQUIRED`	The tracking info needs a review.
`CUSTOMER_ACTION_REQUIRED_DAMAGE_PROOF`	We need proof of the damage from you.
`CUSTOMER_ACTION_REQUIRED_AFFIDAVIT`	We need a signed affidavit from you.
`CUSTOMER_ACTION_REQUIRED_REFUND_CONFIRMATION`	We need you to confirm the refund.

Right now, whatever the reason, the only way to act on a PENDING_ACTION claim (including the three CUSTOMER_ACTION_REQUIRED_* ones above) is to reach out to Opereit support. We’re working on letting you resolve these directly through self-service actions, but that’s not available yet.

CANCELED

Reason	What it means
`TIME_EXCEEDED`	Too much time passed to keep pursuing the claim.
`CLAIM_ALREADY_EXISTS`	A claim already existed for this shipment.
`DELIVERED_BY_CARRIER`	The carrier shows the shipment as delivered.
`CUSTOMS_HOLD_UNKNOWN`	The shipment is held at customs for an unknown reason.
`CUSTOMS_HOLD_AWAITING_PAYMENT`	The shipment is held at customs awaiting duty payment from the receiver.
`SHIPMENT_NOT_CLAIMABLE_YET`	The shipment was sent too recently to be claimable.
`SHIPMENT_NOT_SENT`	The shipment was never sent.
`PACKAGE_AT_ACCESSPOINT`	The package is sitting at an access point.
`CREATED_INCORRECTLY`	The claim was created incorrectly and needs to be recreated.

Of these, CREATED_INCORRECTLY and SHIPMENT_NOT_CLAIMABLE_YET are the two that count as closed, meaning they don’t block a new claim on the same tracking number. See Filing more than one claim for the same tracking number. The rest still count as open.

REJECTED

Reason	What it means
`MISSING_PRODUCT_INFORMATION`	The product information provided wasn’t enough.
`CLAIM_VOIDED_BY_CARRIER`	The carrier voided the claim.
`NOT_ABLE_TO_CONTACT_DESTINATARY`	We weren’t able to reach the recipient.

Any REJECTED reason counts as closed.

Checking on a claim

curl "https://api.opereit.ai/v1/claims/clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ" \
  -u "your_key_id:your_key_secret"

This returns everything about the claim: its status, the shipment, and the incidence (the claim reason and amount). Poll this if you want to watch a specific claim move through review.

Listing your claims

curl "https://api.opereit.ai/v1/claims?limit=25&status=UNDER_REVIEW&carrierId=ups" \
  -u "your_key_id:your_key_secret"

You can filter by status, carrierId, trackingNumber, and a fromDate/toDate range on the claim date. Results are paginated, if pagination.hasMore is true, pass pagination.cursor back as the cursor query param to get the next page.

Handling errors

Every error response looks like this:

{
  "statusCode": 400,
  "statusReasonCode": "INVALID_REQUEST_BODY",
  "error": "Invalid request body",
  "details": { "...": "only present on 400s" }
}

statusReasonCode is the one to branch your code on, it won’t change wording on you the way error might.

statusReasonCode	Status	What it means
`INVALID_REQUEST_BODY`	400	Something in the request body failed validation, e.g. a bad `carrier`, a missing required field, or a non-positive `claimed_amount`. Check `details.fieldErrors`.
`INVALID_QUERY_PARAMETERS`	400	A query param on `GET /v1/claims` is invalid, usually an unrecognized `status` or a `limit` outside 1-100.
`CLAIM_NOT_FOUND`	404	No claim with that ID exists for your organization.
`CLAIM_ALREADY_EXISTS`	409	There’s already an open claim for that tracking number. Contact Opereit support if you need to correct the existing one.
`AUTHENTICATION_REQUIRED` / `INVALID_CREDENTIALS_FORMAT` / `INVALID_CREDENTIALS_ENCODING` / `INVALID_CREDENTIALS`	401	Something’s wrong with your `Authorization` header, missing, malformed, or the credentials themselves aren’t valid.
`INTERNAL_ERROR`	500	Something broke on our end. Safe to retry; if it keeps happening, send us the claim/tracking number.

One thing to watch for on INVALID_REQUEST_BODY: details.fieldErrors is keyed by shipment or incidence, not by the specific nested field. So if both your carrier and your line_items are wrong, they’ll both show up as messages under the single "shipment" key rather than under "shipment.carrier" and "shipment.line_items" separately. Read the message text, not just the key.

Getting started

Claim Management

Integrations

Before you start

Creating a claim

Supported carriers

The `provider` field

Filing more than one claim for the same tracking number

DAMAGED vs LOST

What happens after you create a claim

Status reasons

PENDING_ACTION

CANCELED

REJECTED

Checking on a claim

Listing your claims

Handling errors

​Before you start

​Creating a claim

​Supported carriers

​The provider field

​Filing more than one claim for the same tracking number

​DAMAGED vs LOST

​What happens after you create a claim

​Status reasons

​PENDING_ACTION

​CANCELED

​REJECTED

​Checking on a claim

​Listing your claims

​Handling errors

Before you start

Creating a claim

Supported carriers

The `provider` field

Filing more than one claim for the same tracking number

DAMAGED vs LOST

What happens after you create a claim

Status reasons

PENDING_ACTION

CANCELED

REJECTED

Checking on a claim

Listing your claims

Handling errors