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:

                  Upload evidence (JPEG/PNG)
                          POST /evidence
                              │
                              ▼
              ┌────────── Evidence_xxx ────────┐
              │                                │
              ▼                                ▼
      Package missing?                    Item issues?
              │                                │
              ▼                                ▼
POST /claim-package-missing        POST /claim-item-issues
              │                                │
              └───────────────┬────────────────┘
                              │
                              ▼
                          Claim_xxx
                              │
                              ▼
              ┌─────────── pending ──┬─────────┐
              │                      │         │
              ▼                      ▼         ▼
          retracted              resolved   rejected

Evidence

Before creating a claim you must upload evidence — photos that show the problem. Upload each file as a POST /evidence request with the raw image bytes in the body.

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

{
  "evidenceReference": "Evidence_0fa7gephpy70zt0qanfja9hvqt"
}

Accepted formats are JPEG and PNG. Each claim (or each item in an item-issues claim) requires between 1 and 3 evidence references. Unused evidence is automatically deleted after 1 day, so upload evidence right before creating the claim.

Claim Categories

Item-issues claims require a claim category for each claimed item. Retrieve the current list of valid categories from GET /claimcategories:

curl https://api.printeers.com/v2/claimcategories \
  -H "X-Printeers-Secret-Key: $KEY"

{
  "claimcategories": [
    {
      "reference": "Claimcategory_zt7cdqy06zecmwh2shry4cpq04",
      "name": "Damage (broken)"
    },
    {
      "reference": "Claimcategory_8k2m4p6r9t1w3y5z7b9d1f3h5j",
      "name": "Damage (scratches)"
    },
    ...
  ]
}

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

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": [
        "Evidence_x9cpkswmf1b4pzcp6bqradyg7b"
      ]
    }
  }'

{
  "claimReference": "Claim_216kraceftv49wpzsdvp4wyv8n"
}

Requirements:

The shipment must be at least 48 hours old.
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.

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"
          ]
        }
      ]
    }
  }'

{
  "claimReference": "Claim_9czkfrkk0kww2f7wsfsnmk8g2j"
}

Requirements:

The shipment must be within the 100-day warranty period.
The claimed quantity per item must not exceed the shipped quantity (existing open claims count toward this).
Each item needs 1–3 evidence references.
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 cancelled 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.

curl "https://api.printeers.com/v2/claims" \
  -H "X-Printeers-Secret-Key: $KEY"

{
  "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 with 30 items per page. See the Pagination 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.

curl "https://api.printeers.com/v2/claims/Claim_7zx1f95d90k54ymatsa45tz5dj" \
  -H "X-Printeers-Secret-Key: $KEY"

{
  "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",
    "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": ""
        }
      }
    ]
  }
}

The claim.status field reflects the current claim status (see 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.

Retracting a Claim

If you created a claim by mistake, you can retract it as long as it is still pending:

curl -X POST "https://api.printeers.com/v2/claims/Claim_5ecs3774nnk11rr07y4da2dm51/retract" \
  -H "X-Printeers-Secret-Key: $KEY"

{}

This returns 200 OK with an empty object on success. Retraction cannot be undone — once retracted, the claim is permanently closed.

Typical Integration

A typical claims integration follows these steps:

Fetch claim categories — call GET /claimcategories and present them to your user.
Collect evidence — have the user upload photos. Send each to POST /evidence.
Create the claim — call POST /claim-package-missing or POST /claim-item-issues depending on the situation.
Poll for resolution — periodically call GET /claims or GET /claims/{claimReference} to check the status.
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.