Create a claim

post

https://api.protectplus.io/claims

Create a protection claim for an order in one call. All business
checks run server-side: order lookup, duplicate claim, Protect+ coverage,
refund eligibility, returns overlap, Shopify reship stock, and exclusion
policy.

store_id comes from the JWT — do not send it. Identify the order with
order_reference (human order number). Customer name and email are
taken from the order — do not send them.

Images are required when claim_reason is Damaged or
Tracking Not Updated (same as the return portal). Upload each file
with POST /claims/uploads, then pass the returned https URLs on
claims_items[].claimed_images (or top-level claimed_images for a
full-order claim). Other reasons may omit photos.

Idempotency-Key (UUID) is required.

Failures use RFC 7807 Problem Details (CLAIM_EXISTS, NOT_PROTECTED,
REFUND_NOT_ELIGIBLE, RETURNS_OVERLAP, STOCK_INSUFFICIENT,
VALIDATION_ERROR, EVIDENCE_REQUIRED, CLAIM_CREATE_FAILED).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

order_reference

string

required

Human order number (store or Protect+ number).

claimed_type

string

enum

required

Allowed:

claims_full_order

boolean

required

true = entire order (claims_items may be omitted). false = selected lines; each item needs line_id and quantity. Damaged and Tracking Not Updated require photos: upload via POST /claims/uploads and pass the returned https URLs as claimed_images. Other reasons may omit photos.

claim_reason

string

enum

Exact text to send — not a reason id. Must match one of: Lost, Stolen, Damaged, Wrong Product, Tracking Not Updated.

Allowed:

additional_comment

string

Portal "More details". One note for the whole claim. Copied onto every line unless a line sends its own additional_comment.

claimed_images

array of uris

https URLs from POST /claims/uploads. Required on full-order Damaged / Tracking Not Updated. Copied onto every expanded line when a line has no own photos.

claimed_images

shipping_address

object

claims_items

array of objects

Required unless claims_full_order is true.

claims_items

Headers

Idempotency-Key

uuid

required

UUID. Same key + body within 24h returns the cached response.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201Claim created.

401Missing, invalid, expired, or revoked JWT.

404Order not found for this store.

409A claim for this order already exists.

422Validation or business-rule failure.