Rewards API
Create, manage, and pay rewards for returned items, generate return certificates, and handle disputes.
The Rewards API lets tag owners offer monetary rewards for returning lost items, confirm returns, process payments, and generate certificates of return. All endpoints require authentication unless noted otherwise.
List Rewards
GET /api/v1/rewards — Required
Create Reward
POST /api/v1/rewards/:tagId — Required
Confirm Return
POST /api/v1/rewards/confirm-return/:tagId — Required
Pay Reward
POST /api/v1/rewards/:id/pay — Required
Return Certificate
GET /api/v1/rewards/certificate/:tagId — Public
Dispute Reward
POST /api/v1/rewards/:id/dispute — Required
List Rewards
Retrieve all rewards created by the authenticated user.
GET /api/v1/rewards — Auth: Required
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
limit | integer | 10 | Items per page |
curl "https://api.qriotag.global/api/v1/rewards?page=1&limit=10" \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": [
{
"id": "rwd_abc123",
"tagId": "tag_abc123",
"tagName": "House Keys",
"amount": 25.00,
"currency": "USD",
"description": "Reward for safe return of my keys",
"status": "ACTIVE",
"createdAt": "2025-06-01T14:00:00.000Z"
}
],
"meta": {
"total": 2,
"page": 1,
"totalPages": 1
}
}Create Reward
Offer a reward for returning a specific tag.
POST /api/v1/rewards/:tagId — Auth: Required
Request body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Reward amount |
currency | string | No | Currency code (default: USD) |
description | string | No | Description of the reward |
curl -X POST https://api.qriotag.global/api/v1/rewards/tag_abc123 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"amount": 25.00,
"currency": "USD",
"description": "Reward for safe return of my keys"
}'Response
{
"success": true,
"data": {
"id": "rwd_abc123",
"tagId": "tag_abc123",
"amount": 25.00,
"currency": "USD",
"description": "Reward for safe return of my keys",
"status": "ACTIVE",
"createdAt": "2025-06-01T14:00:00.000Z"
}
}Delete Reward
Remove a reward offer.
DELETE /api/v1/rewards/:id — Auth: Required
curl -X DELETE https://api.qriotag.global/api/v1/rewards/rwd_abc123 \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": {
"message": "Reward deleted"
}
}Confirm Return
Confirm that a tagged item has been returned by the finder.
POST /api/v1/rewards/confirm-return/:tagId — Auth: Required
curl -X POST https://api.qriotag.global/api/v1/rewards/confirm-return/tag_abc123 \
-H "Authorization: Bearer <token>"Response
{
"success": true,
"data": {
"tagId": "tag_abc123",
"status": "RETURNED",
"message": "Return confirmed. You can now pay the reward."
}
}Pay Reward
Process payment for a reward after the item has been returned.
POST /api/v1/rewards/:id/pay — Auth: Required
Request body
| Field | Type | Required | Description |
|---|---|---|---|
paymentRef | string | No | External payment reference (e.g., Venmo, PayPal transaction ID) |
curl -X POST https://api.qriotag.global/api/v1/rewards/rwd_abc123/pay \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "paymentRef": "venmo_txn_12345" }'Response
{
"success": true,
"data": {
"id": "rwd_abc123",
"status": "PAID",
"paymentRef": "venmo_txn_12345",
"paidAt": "2025-06-02T10:00:00.000Z"
}
}Get Return Certificate
Generate a public certificate of return for a tag. This can be shared as proof that an item was returned.
GET /api/v1/rewards/certificate/:tagId — Auth: None (public)
curl https://api.qriotag.global/api/v1/rewards/certificate/tag_abc123Response
{
"success": true,
"data": {
"tagId": "tag_abc123",
"itemName": "House Keys",
"returnedAt": "2025-06-02T09:30:00.000Z",
"certificateId": "cert_abc123",
"verifyUrl": "https://qriotag.com/verify/cert_abc123"
}
}Dispute Reward
Open a dispute on a reward (e.g., if the item was not actually returned or was damaged).
POST /api/v1/rewards/:id/dispute — Auth: Required
Request body
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | Reason for the dispute |
curl -X POST https://api.qriotag.global/api/v1/rewards/rwd_abc123/dispute \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "reason": "Item was returned damaged and missing the key fob" }'Response
{
"success": true,
"data": {
"id": "rwd_abc123",
"status": "DISPUTED",
"disputeReason": "Item was returned damaged and missing the key fob",
"message": "Dispute opened. Our team will review and respond within 48 hours."
}
}Was this page helpful?