Skip to content

Get the requirements for a claim

Request

Returns what a claim on one of your shipments, returns or restocking shipments may contain, and until when, under the same rules POST /claims applies. It is what the claim form in the Hive app shows before a claim is filed.

A claim built from it is filed:

  • issue_type is one of issue_types. A carrier that accepts no claims lists none.
  • documents holds one document of each required_documents type of the issue type, and no other type. Where a carrier provides a form for a document, its template_urls link to it.
  • The issue type's submission_deadline_passed is false.
  • When the issue type's items_required is true, items names at least one shipment item, and every entry is an item whose claimable_issue_types include the issue type, each item at most once, with a quantity from 1 to the item's quantity. When it is false, items is empty.
  • A tracking_not_updated claim is not filed while tracking_not_updated_eligibility.reason is too_early. Depending on your account, such a claim is refused until opens_at, or filed and later rejected by Hive as too early.

The answer changes over time: deadlines pass, tracking updates and shipments are delivered. Ask again right before filing.

Security
BearerAuth
Query
subject_typestring(ClaimSubjectType)required

Kind of subject the claim would be filed for

Enum:"RestockingShipment""Return""Shipment"
subject_idinteger, (int64)required

ID of the shipment, return or restocking shipment

curl -i -X GET \
  'https://developers.hive.app/_mock/merchant-api-v2/mapi_v2_oas31/claims/requirements?subject_type=RestockingShipment&subject_id=0' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

What a claim on the subject may contain, and until when

Bodyapplication/json
issue_typesArray of objects(ClaimRequirementsIssueType)required

The issue types a claim on the subject can be filed for, with what each requires. They are the ones the subject's carrier accepts, narrowed to damaged once the carrier has disposed of the shipment. Empty when none can be filed.

itemsArray of objects(ClaimRequirementsItem)required

The items of a shipment, with the issue types each can be claimed for. Empty for returns and restocking shipments, whose claims take no items.

tracking_not_updated_eligibilityClaimTrackingNotUpdatedEligibility (object) or nullrequired
Any of:

Whether the carrier's tracking has been silent long enough for a tracking_not_updated claim, as the Hive app computes it

Response
{ "issue_types": [ { … }, { … }, { … } ], "items": [ { … }, { … } ], "tracking_not_updated_eligibility": { "eligible": false, "opens_at": null, "reason": "delivered" } }