Claims

File Fulfillment Claim

Changed on

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.

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.

Not Followed Instructions Types Values

Describes which special instruction given for the order was not followed.

ValueDescription
custom_packagingCustom packaging was specified for the order and was not used or was used incorrectly.
special_packing_instructionsSpecial packing instructions were provided for the order and were not followed.
fragileThe order contained fragile items requiring special handling that was not followed.
gift_messageA gift message was requested to be printed and was printed incorrectly or not included in the package.
packing_noteA packing note was specified for the order and was not followed.
additional_documentsAdditional documents were requested to be included in the package and were missing or incorrect.
missing_packlistA ShipMonk packing list was expected to be included in the package and was missing.
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

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
return_requestedboolean 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.

customer_notestring nullable

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

extra_unknown_products_descriptionstring 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.

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