Skip to content

Create a claim

Request

Files a claim for a shipment, a return or a restocking shipment, under the same rules as the claim form in the Hive app:

  • The carrier's claim settings decide which issue types can be claimed for the subject and which documents are required for each.
  • Claims on a shipment must be filed before the submission deadline: 4 business days after delivery for damaged, 20 business days after shipping for delivered_not_received and tracking_not_updated. Business days skip weekends and the public holidays of the warehouse's country.
  • A tracking_not_updated claim can be refused while the carrier's tracking was updated too recently.
  • For damaged, missing_items and wrong_items claims on a B2C shipment, items must name the affected shipment items (from GET /shipments) and the claimed quantity of each, at most the shipped quantity. SKUs that are not eligible for reimbursement cannot be chosen. For any other claim, items must be empty.
  • Documents are sent as base64 data URIs, one for each document type the carrier requires, and no other types.

GET /claims/requirements returns these rules for one subject before you file: the issue types, required documents, deadlines and claimable items.

A refused claim returns 422 with the reasons keyed by request field (subject, issue_type, items, documents) or base, and nothing is created. A claim refused for its deadline names the last day it could be filed.

Security
BearerAuth
Bodyapplication/jsonrequired
documentsArray of objects, <= 12 items(ClaimCreateDocument)

Documents for the claim, one per document type the carrier requires for the issue type. Other document types are refused.

issue_typestring(ClaimIssueType)required

The problem a new claim is about. Possible values:

  • 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
Enum:"damaged""delivered_not_received""missing_items""tracking_not_updated""wrong_items"
itemsArray of objects(ClaimCreateItem)

The affected shipment items, required for damaged, missing_items and wrong_items claims on a B2C shipment and not accepted for any other claim

merchant_descriptionstring or null

Your description of the problem

subjectobject(ClaimCreateSubject)required

What the new claim is filed for

curl -i -X POST \
  https://developers.hive.app/_mock/merchant-api-v2/mapi_v2_oas31/claims \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documents": [
      {
        "document_data_uri": "data:application/pdf;base64,JVBERi0xLjQK...",
        "document_type": "order_invoice",
        "name": "invoice-1042.pdf"
      },
      {
        "document_data_uri": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
        "document_type": "picture_of_damaged_goods",
        "name": "damage.jpg"
      }
    ],
    "issue_type": "damaged",
    "items": [
      {
        "quantity": 1,
        "shipment_item_id": 9876543
      }
    ],
    "merchant_description": "The bottle arrived broken.",
    "subject": {
      "id": 5551234,
      "type": "Shipment"
    }
  }'

Responses

The claim was filed

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"
}