Claims

File Shipping Claim

Changed on

Files a shipping claim.

Claims for wholesale orders shipped without a shipping label (e.g. LTL) cannot be filed via this endpoint; file them in the ShipMonk app instead.

Several fields are conditionally required depending on initialResolution and category; see the field descriptions on FileShippingClaimInput for the exact conditions. A structurally valid request can still be rejected if those conditions are not met.

To help us process the claim quickly, include any relevant supporting documents in the documents field. If they are omitted, we may need to request them later, which can delay processing of the claim.

Initial Resolution and Reship Fields

initialResolution governs which reship-related fields are permitted.

ValuereshippedOrdernewReshipOrderPreferencesNotes
already_reshippedRequiredForbiddenOrder was already reshipped elsewhere.
reship_requestedForbiddenRequiredCustomer asked for a reship; the reship order is created immediately, or at submitAt if provided.
reship_when_approvedForbiddenRequiredReship pending approval; the reship order is not created until approved, so submitAt must be null.
reship_not_requestedForbiddenForbiddenNo reship involved.
reship_or_refundForbiddenForbiddenReserved, only valid when MonkProtect is enabled.

Category Values

Describes the type of shipping issue being claimed.

ValueDescription
nullDefault
lost_in_transitThe shipment was lost while in transit and never delivered.
damaged_in_transitThe shipment's packaging or contents were damaged while in transit. Requires at least one document with documentType = damage_photo_packaging.
post/v1/integrations/claims/shipping

Request

  • Base URL: https://api.shipmonk.com
  • URL: https://api.shipmonk.com/v1/integrations/claims/shipping
  • Auth: API key in header Api-Key

Request body

store_idinteger required

Must belong to the authenticated account. Resolved jointly with orderKey.

order_keystring required

Resolved within the given storeId, not globally. Must identify an existing order.

initial_resolution'already_reshipped' | 'reship_requested' | 'reship_when_approved' | 'reship_not_requested' | 'reship_or_refund' required
customer_notestring nullable

Free-form note providing additional context about the claim for the claims processing team to review.

category'lost_in_transit' | 'damaged_in_transit'

Example request

{
  "store_id": 123456,
  "order_key": "327b5abd-017a-4504-a50d-54f1cea80269",
  "reshipped_order": {
    "store_id": 123456,
    "order_key": "327b5abd-017a-4504-a50d-54f1cea80269"
  },
  "new_reship_order_preferences": {
    "store_id": 123456,
    "submit_at": "2025-07-24 14:53:00"
  }
}

Response

Success

statusinteger required

Changes