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

# File Fulfillment Claim

`POST /v1/integrations/claims/fulfillment`

## Request

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

Files a fulfillment 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`; see the field descriptions on `FileFulfillmentClaimInput` 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. |

## Not Followed Instructions Types Values
Describes which special instruction given for the order was not followed.
| Value | Description |
|------|-------------|
| `custom_packaging` | Custom packaging was specified for the order and was not used or was used incorrectly. |
| `special_packing_instructions` | Special packing instructions were provided for the order and were not followed. |
| `fragile` | The order contained fragile items requiring special handling that was not followed. |
| `gift_message` | A gift message was requested to be printed and was printed incorrectly or not included in the package. |
| `packing_note` | A packing note was specified for the order and was not followed. |
| `additional_documents` | Additional documents were requested to be included in the package and were missing or incorrect. |
| `missing_packlist` | A ShipMonk packing list was expected to be included in the package and was missing. |

## Request body

- ShipMonkClaimsClaimInputPublicApiFileFulfillmentClaimInput
  - `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
  - `return_requested` boolean, required: When true, a return (RMA) is created for the claim's wrong or overshipped products, and for the return-to-vendor product if extra unknown products are claimed.
  - `products` ShipMonkClaimsClaimInputPublicApiFulfillmentClaimProductInput[], required: Each (productSku, type) pair must be unique; a duplicate pair is rejected. The same productSku may appear with differing type values.
    - `product_sku` string, required: The SKU of a product that was shipped on the resolved order.
    - `quantity` integer, required: The quantity of the product being claimed. Must be a positive integer no greater than the quantity of this SKU shipped on the order, excluding any quantity of it added as packaging or an inserted item.
    - `type` 'missing' | 'damaged' | 'wrong' | 'overshipped', required
  - `documents` ShipMonkClaimsClaimInputPublicApiClaimDocumentInput[], required: Supporting documentation for the claim, e.g. photos, invoices, or other evidence. 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
  - `customer_note` string, nullable: Free-form note providing additional context about the claim for the claims processing team to review.
  - `extra_unknown_products_description` string, nullable: Describes extra products received that were not part of the order. A non-null value marks the claim as having extra unknown products; use null if none were received.
  - `not_followed_instructions` ShipMonkClaimsClaimInputPublicApiFulfillmentClaimDisobeyedInstructionsInput
    - `types` ShipMonkClaimsClaimEnumNotFollowedInstructionsType[], required
    - `comment` string, nullable
  - `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.

## 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/fulfillment/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)