# Claims Canonical URL: https://api-docs.test-printeers.com/guides/claims Learn how to file and manage claims for shipment issues such as missing packages, damaged items, or print defects. ## Overview When something goes wrong with a shipment (a package never arrives, an item is damaged, or a print is misaligned), you can file a claim through the API. Printeers reviews each claim and decides on a replacement, refund, or rejection. The claims flow looks like this: ``` Package missing? Item issues? │ │ │ Upload evidence (JPEG/PNG) │ POST /evidence │ │ │ ▼ │ Evidence_xxx │ │ ▼ ▼ POST /claim-package-missing POST /claim-item-issues │ │ └───────────────┬────────────────┘ │ ▼ Claim_xxx │ ▼ ┌─────────── pending ──┬─────────┐ │ │ │ ▼ ▼ ▼ retracted resolved rejected ``` ## Evidence Most item-issues claims must carry evidence: photos that show the problem. Whether evidence is required depends on the claim category — categories where there is usually nothing to photograph, such as "Item missing", accept claimlines without evidence (see `evidenceRequired` in [Claim Categories](#claim-categories)). Evidence is optional for package-missing claims. Upload each file as a `POST /evidence` request with the raw image bytes in the body. ```bash curl -X POST https://api.printeers.com/v2/evidence \ -H "X-Printeers-Secret-Key: $KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary @photo.jpg ``` ```json { "evidence": { "reference": "Evidence_0fa7gephpy70zt0qanfja9hvqt" } } ``` Accepted formats are JPEG and PNG. Each item in an item-issues claim accepts up to 3 evidence references; at least 1 is required when the item's claim category has `evidenceRequired: true`. Package-missing claims accept 0-3 evidence references. Unused evidence is automatically deleted after 1 day, so upload evidence right before creating the claim. Evidence uploads count against the `uploads` rate-limit bucket; see the [Rate Limiting](https://api-docs.test-printeers.com/guides/rate-limiting.md) guide. ## Claim Categories Item-issues claims require a claim category for each claimed item. Retrieve the current list of valid categories from `GET /claimcategories`: ```bash curl https://api.printeers.com/v2/claimcategories \ -H "X-Printeers-Secret-Key: $KEY" ``` ```json { "claimcategories": [ { "reference": "Claimcategory_zt7cdqy06zecmwh2shry4cpq04", "name": "Damage (broken)", "evidenceRequired": true }, { "reference": "Claimcategory_yvtazxbe3m9nrp409a96x9bxh4", "name": "Item missing", "evidenceRequired": false }, ... ] } ``` `evidenceRequired` tells you whether claimlines in that category must carry at least one evidence reference. Always fetch these dynamically rather than hardcoding them; the list may change. > **Note:** "Package missing" is not a valid claim category for item-issues claims (error code `package_missing_category_not_allowed`). If an entire package never arrived, use `POST /claim-package-missing` instead. ## Creating a Claim There are two types of claims, depending on the situation. ### Package Missing Use `POST /claim-package-missing` when an entire package never arrived. This automatically claims all items in the shipment. ```bash curl -X POST https://api.printeers.com/v2/claim-package-missing \ -H "X-Printeers-Secret-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{ "claim": { "shipmentReference": "Shipment_9jmn3dewwvy13rv12k7aannqzy", "evidenceReferences": [] } }' ``` ```json { "claim": { "reference": "Claim_216kraceftv49wpzsdvp4wyv8n" } } ``` Requirements: - The promised delivery window for the shipment's destination and shipping level must have passed (never earlier than two calendar days after the ship day). The `shipment_too_recent` error message states the date from which the claim can be filed. - The shipment must be within the 100-day warranty period. - There must be no existing claims on the shipment. - The order must not already have a replacement. ### Item Issues Use `POST /claim-item-issues` when specific items have problems (damage, print defects, wrong product, etc.). ```bash curl -X POST https://api.printeers.com/v2/claim-item-issues \ -H "X-Printeers-Secret-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{ "claim": { "shipmentReference": "Shipment_cxb6287xjnt5726d1dnpnqg6mc", "orderReference": "Order_5jcavdegg8n9pvgxq887jq0zbc", "comment": "Two cases arrived with visible scratches on the print.", "claimlines": [ { "orderlineIndex": 1, "quantity": 2, "claimcategoryReference": "Claimcategory_8k2m4p6r9t1w3y5z7b9d1f3h5j", "evidenceReferences": [ "Evidence_sq3bkad1t0hq3q83s7897bs8cg", "Evidence_8jssahgpgx4qafb6c8aebreja2" ] } ] } }' ``` ```json { "claim": { "reference": "Claim_9czkfrkk0kww2f7wsfsnmk8g2j" } } ``` Requirements: - The shipment must be within the 100-day warranty period. - Every `orderlineIndex` must be an item of the order that was shipped in the shipment (error codes `order_not_in_shipment` and `orderline_not_in_shipment` otherwise). - The claimed quantity per item must not exceed the shipped quantity (existing open claims count toward this). - Each item accepts up to 3 evidence references; at least 1 is required when its claim category has `evidenceRequired: true` (error code `evidence_required` otherwise). - The `comment` field is optional (max 1000 characters). ## Claim Status Every claim has one of four statuses: | Status | Meaning | |---|---| | `pending` | Claim is being reviewed by support. | | `resolved` | At least one item was awarded a replacement or refund. | | `rejected` | The claim was reviewed and denied. | | `retracted` | The claim was canceled by you before a decision was made. | ## Listing Claims `GET /claims` returns all open claims and recently closed claims for your organization. By default, closed claims from the last 14 days are included. Use `closedAfter` to change this window. ```bash curl "https://api.printeers.com/v2/claims" \ -H "X-Printeers-Secret-Key: $KEY" ``` ```json { "claims": [ { "reference": "Claim_9czkfrkk0kww2f7wsfsnmk8g2j", "orderReference": "Order_j2rznt7qr6ra78zb0aq2hsp3fd", "status": "pending", "claimcategories": [ { "reference": "Claimcategory_8k2m4p6r9t1w3y5z7b9d1f3h5j", "name": "Damage (scratches)" } ], "created": "2025-12-15T10:30:00Z", "retracted": null, "decided": null } ], "nextCursor": null } ``` Results are paginated. See the [Pagination](https://api-docs.test-printeers.com/guides/pagination.md) guide for how to iterate through pages using `cursor`. ## Getting Claim Details Use `GET /claims/{claimReference}` to see full details, including individual claimlines and the resolution per item. ```bash curl "https://api.printeers.com/v2/claims/Claim_7zx1f95d90k54ymatsa45tz5dj" \ -H "X-Printeers-Secret-Key: $KEY" ``` ```json { "claim": { "reference": "Claim_7zx1f95d90k54ymatsa45tz5dj", "orderReference": "Order_gegcgtb3a8d349nsp7x0vyntd1", "status": "resolved", "comment": "Two cases arrived with visible scratches on the print.", "createdBy": "user@example.com", "created": "2025-12-15T10:30:00Z", "retracted": null, "decision": { "decided": "2025-12-16T14:00:00Z", "refundShippingCosts": true, "comment": "Confirmed print defect. Replacement issued for 1, refund for 1." }, "shipmentReference": "Shipment_03t8w1hfbfdh6vfy7wz67kqy6v", "evidenceUrls": [], "claimlines": [ { "productReference": "Product_4j8k2m5n7p9q1r3s6t8v0w2x4y", "orderlineIndex": 1, "quantity": 2, "imageReference": "Image_78h3pwhvn2gnnsks3a92nww5zn", "claimcategory": { "reference": "Claimcategory_8k2m4p6r9t1w3y5z7b9d1f3h5j", "name": "Damage (scratches)" }, "decision": { "replacementQuantity": 1, "refundQuantity": 1, "rejectionQuantity": 0, "comment": "" }, "evidenceUrls": [ "https://files.printeers.com/evidence/Evidence_sq3bkad1t0hq3q83s7897bs8cg.jpeg", "https://files.printeers.com/evidence/Evidence_8jssahgpgx4qafb6c8aebreja2.jpeg" ] } ] } } ``` The `claim.status` field reflects the current claim status (see [Claim Status](#claim-status) above). The `decision` fields on both the claim and each claimline are `null` while the claim is still `pending`. Once a decision is made, the claim-level `decision` contains `decided`, `refundShippingCosts`, and `comment`, while each claimline's `decision` contains `replacementQuantity`, `refundQuantity`, `rejectionQuantity`, and `comment`. The `evidenceUrls` fields list the evidence images that were uploaded when the claim was created. Each claimline carries its own evidence; the claim-level `evidenceUrls` is only populated for package-missing claims. Evidence is stored for a limited time: roughly four months after a claim is decided or retracted the images are purged, the lists become empty, and previously returned URLs stop working — download the images in time if you want to keep them. ## Retracting a Claim If you created a claim by mistake, you can retract it as long as it is still `pending`: ```bash curl -X POST "https://api.printeers.com/v2/claims/Claim_5ecs3774nnk11rr07y4da2dm51/retract" \ -H "X-Printeers-Secret-Key: $KEY" ``` A successful retraction returns `204 No Content` (empty body). Retraction cannot be undone; once retracted, the claim is permanently closed. ## Typical Integration A typical claims integration follows these steps: 1. **Fetch claim categories**: call `GET /claimcategories` and present them to your user. 2. **Collect evidence**: have the user upload photos when the chosen category has `evidenceRequired: true` (or whenever photos are available). Send each to `POST /evidence`. 3. **Create the claim**: call `POST /claim-package-missing` or `POST /claim-item-issues` depending on the situation. 4. **Poll for resolution**: periodically call `GET /claims` or `GET /claims/{claimReference}` to check the status. 5. **Handle the outcome**: once the claim's `decision` is set, inspect it for overall details and each claimline's `decision` to determine what was replaced, refunded, or rejected.