Skip to content

Get a claim

Request

Returns a specific claim.

Security
BearerAuth
Path
idinteger, (int64)required

Claim ID, the number shown in the Hive app

curl -i -X GET \
  'https://hive-merchant-api.redocly.app/_mock/merchant-api-v2/mapi_v2_oas31/claims/{id}' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

A claim

Bodyapplication/json
amount_reimbursed_in_centsinteger or nullrequired

Amount Hive reimbursed, in cents of currency. Set when the claim is accepted, null before.

created_atstring, (date-time)required

When the claim was created

currencystring(CurrencyCode)^[A-Z]{3}$required

3-letter ISO 4217 currency code. Examples: EUR, USD, GBP, JPY

documentsArray of objects(ClaimDocument)required

Documents attached to the claim

idinteger, (int64)required

Hive's unique identifier, the claim number shown in the Hive app

issue_typestring or nullrequired

The problem the claim is about:

  • damaged: Goods arrived damaged
  • delivered_not_received: The carrier reports the parcel as delivered, but the recipient did not receive it
  • missing_items: Items are missing from the parcel
  • tracking_not_updated: The carrier's tracking has not been updated for a long time
  • wrong_items: The parcel contains wrong items

Claims filed before February 2024 can carry an older free-text value, or null.

itemsArray of objects(ClaimItem)required

The shipment items the claim is about, with the claimed quantity. Empty when the claim covers the whole subject.

merchant_descriptionstring or nullrequired

The merchant's description of the problem

rationalestring or nullrequired

Hive's explanation of the decision, set when the claim is accepted or rejected

resolved_atstring or null, (date-time)required

When the claim was accepted or rejected, null while it is not resolved

sourceClaimSource (string) or nullrequired
Any of:

Where the claim was filed. Possible values:

  • active_admin: By Hive's support team
  • customer_portal: By the end customer in the customer portal, then submitted by the merchant
  • merchant_api: By the merchant through the Merchant API
  • merchant_app: By the merchant in the Hive app
string(ClaimSource)
Enum:"active_admin""customer_portal""merchant_api""merchant_app"
statusstring(ClaimStatus)required

Status of the claim. Possible values:

  • accepted: Hive accepted the claim and reimbursed amount_reimbursed_in_cents
  • in_carrier_processing: Hive submitted the claim to the carrier and is waiting for its decision
  • open: The claim was filed and Hive is reviewing it
  • rejected: Hive rejected the claim; rationale says why
Enum:"accepted""in_carrier_processing""open""rejected"
subjectobject(ClaimSubject)required

What the claim was filed for

updated_atstring, (date-time)required

When the claim was last updated

Response
{
  "amount_reimbursed_in_cents": 2499,
  "created_at": "2026-09-14T09:12:44.512Z",
  "currency": "EUR",
  "documents": [
    { … },
    { … }
  ],
  "id": 401234,
  "issue_type": "damaged",
  "items": [
    { … }
  ],
  "merchant_description": "The bottle arrived broken.",
  "rationale": "Order damaged due to insufficient packaging. Hive Order Compensation + SKUs Production Cost(s)",
  "resolved_at": "2026-09-20T15:02:10.000Z",
  "source": "merchant_app",
  "status": "accepted",
  "subject": {
    "id": 5551234,
    "order_id": 123456,
    "type": "Shipment"
  },
  "updated_at": "2026-09-20T15:02:10.000Z"
}