---
title: "File Shipping Claim"
method: POST
path: "/v1/integrations/claims/shipping"
tags: ["Claims"]
---

# File Shipping Claim

`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`

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.
| Value | reshippedOrder | newReshipOrderPreferences | Notes |
|------|------|------|------|
| `already_reshipped` | Required | Forbidden | Order was already reshipped elsewhere. |
| `reship_requested` | Forbidden | Required | Customer asked for a reship; the reship order is created immediately, or at `submitAt` if provided. |
| `reship_when_approved` | Forbidden | Required | Reship pending approval; the reship order is not created until approved, so `submitAt` must be null. |
| `reship_not_requested` | Forbidden | Forbidden | No reship involved. |
| `reship_or_refund` | Forbidden | Forbidden | Reserved, only valid when MonkProtect is enabled. |

## Category Values
Describes the type of shipping issue being claimed.
| Value | Description |
|------|-------------|
| `null` | Default |
| `lost_in_transit` | The shipment was lost while in transit and never delivered. |
| `damaged_in_transit` | The shipment's packaging or contents were damaged while in transit. Requires at least one document with documentType = damage_photo_packaging. |

## Request body

- ShipMonkClaimsClaimInputPublicApiFileShippingClaimInput
  - `store_id` integer, required: Must belong to the authenticated account. Resolved jointly with orderKey.
  - `order_key` string, 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_note` string, nullable: Free-form note providing additional context about the claim for the claims processing team to review.
  - `category` 'lost_in_transit' | 'damaged_in_transit'
  - `reshipped_order` ShipMonkClaimsClaimInputPublicApiClaimReshippedOrderInput
    - `store_id` integer, required: The store the reshipped order belongs to. Found as store_id in order API shapes (e.g. Get Order, webhooks), or in the ShipMonk app by clicking the store name shown on the order.
    - `order_key` string, required: Must match the order_key of the order that fulfilled the reship, found in order API shapes.
  - `new_reship_order_preferences` ShipMonkClaimsClaimInputPublicApiNewReshipOrderPreferencesInput
    - `store_id` integer, required: The store the reship order will be created in. This should generally be the original order's store id; use a different store only if the reship needs to be created elsewhere.
    - `submit_at` string, date-time, nullable: reship_requested claims ship the reship order immediately by default. Use this field to set a future date for the order to be submitted for fulfillment instead — must be a future timestamp. For reship_when_approved claims, this field has no effect: the reship order is not created until ShipMonk approves the claim, at which point it ships immediately.
  - `documents` ShipMonkClaimsClaimInputPublicApiClaimDocumentInput[], nullable: For category = damaged_in_transit, at least one entry with documentType = damage_photo_packaging is required. Only PDF and images are supported mime types.
    - `data` string, required: Base64-encoded contents of the file.
    - `name` string, required
    - `mime` 'application/pdf' | 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | 'application/zpl' | 'application/zip' | 'text/csv' | 'image/svg+xml' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain' | 'application/gzip' | 'text/html' | 'application/octet-stream', required
    - `document_type` 'product_po' | 'order_invoice' | 'email_screenshot' | 'damage_photo' | 'damage_photo_packaging' | 'damage_photo_items' | 'affidavit' | 'police_report' | 'shipping_label' | 'extra_item_barcode' | 'package_contents' | 'other', required

## Response `200`

Success

- object
  - `status` integer, required
  - `data` ShipMonkClaimsClaimOutputPublicApiFileClaimOutput, required
    - `id` integer, required: The ID of the claim filed.

## Changes

- **2026-09-04** `57f53b6abc83`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shipmonk/apis/shipmonk-api/changes/v1/integrations/claims/shipping/post.md)

---

[API](https://skmtc.dev/shipmonk/apis/shipmonk-api.md) - [All operations](https://skmtc.dev/shipmonk/apis/shipmonk-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shipmonk/apis/shipmonk-api/revisions/947a4a29ffbf?raw)