Skip to main content
A claim is what you send a supplier when they have charged too much. It collects alerts from one agreement, tracks the claim from start to finish, and records the money you get back.

​
Create a claim

Create the claim and add alerts in the same request. This example claims every pending alert in one topic:
You can also list the alerts by alert_ids. Pending alerts you add become claimed. An alert can only be in one claim at a time.

​
Add and remove alerts

  • POST /v1/claims/{id}/alerts adds alerts.
  • POST /v1/claims/{id}/alerts/remove takes them out again. Claimed alerts go back to pending.
  • Set move_from_open_claims: true when adding to move alerts from pending or in-progress claims in the same transaction. Completed and cancelled source claims are excluded.
Each takes alert_ids or a filter, just like creating a claim. To see what’s in a claim, list alerts with GET /v1/alerts?claim_ids=$CLAIM_ID.

​
Follow a claim through

A claim is pending, in_progress, completed or cancelled. Change it with PATCH /v1/claims/{id}:
  • Once a claim is completed, its alerts can’t be changed. Reopen it first if you need to.
  • Cancelling a claim dismisses its pending and claimed alerts. Credited alerts stay credited.
The claim’s summary shows the number of alerts and their impact by status. Use summary.claimed for the amount you are claiming. Amounts are per currency and are never converted.

​
Send it to the supplier

GET /v1/claims/{id}/export?format=pdf returns a claim document you can send to the supplier. Use format=xlsx or format=csv for every alert as a row. Claimed alerts are always included; add include_pending=true or include_credited=true to include those too.
GET /v1/claims/{id}/documents lists the invoice files behind the claim, if you want to send them along.

​
Record what you get back

When the supplier pays back or credits money, record it as a refund with POST /v1/claims/{id}/refunds, giving the amount and currency. The claim’s refund_summary adds up the refunds per currency. To see what was recovered in a period, such as this year, call GET /v1/claims/metrics with refunded_from and refunded_through: its refund_summary then counts only refunds recorded in that period. If the supplier sends a credit note, attach it with POST /v1/claims/{id}/credit-notes. Set "create_refund": true to record a refund for the credit note’s amount at the same time. A credit note on its own is just evidence: only refunds count as money received.

​
Delete a claim

DELETE /v1/claims/{id}?alert_outcome=pending removes a claim for good. Choose with the query parameter alert_outcome whether its claimed alerts go back to pending or are dismissed. To keep a record of the claim, cancel it instead.