Challenges, Kudos, Submissions, Redemption

Endpoints for individual challenges, community challenges, peer kudos, the UGC submission queue, and the rewards redemption store. Base URL is /wp-json/wb-gamification/v1/. See REST API Overview for authentication and error formats.

Challenges

Individual, per-member challenges that track progress toward a target action.

Method	Endpoint	Permission
GET	/challenges	Public
POST	/challenges	manage_options
GET	/challenges/{id}	Public
PUT PATCH	/challenges/{id}	manage_options
DELETE	/challenges/{id}	manage_options

POST /challenges

Create a challenge.

Field	Type	Required	Description
title	string	Yes	Challenge title
description	string	No	Description shown to members
action_id	string	Yes	Action that advances the challenge
target	int	No	Number of action occurrences to complete
bonus_points	int	No	Points awarded on completion
starts_at	string	No	ISO start datetime
ends_at	string	No	ISO end datetime

curl -X POST https://example.com/wp-json/wb-gamification/v1/challenges \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "title": "Week of Learning", "action_id": "ld_lesson_complete", "target": 5, "bonus_points": 100 }'

PUT /challenges/{id}

Update a challenge. Accepts title, action_id, target, bonus_points, starts_at, ends_at, status.

Challenge progress is recorded by the engine as members perform the challenge’s action; there is no endpoint to report progress by hand.

Community Challenges

Group-wide challenges where members contribute toward a shared target count.

Method	Endpoint	Permission
GET	/community-challenges	Public
POST	/community-challenges	manage_options
GET	/community-challenges/{id}	Public
PUT PATCH	/community-challenges/{id}	manage_options
DELETE	/community-challenges/{id}	manage_options

POST /community-challenges

Create a community challenge.

Field	Type	Required	Description
title	string	Yes	Challenge title
description	string	No	Description shown to members
target_count	int	Yes	Total contributions needed to complete
target_action	string	No	Action that contributes to the count
bonus_points	int	No	Bonus awarded to participants on completion
starts_at	string	No	ISO start datetime
ends_at	string	No	ISO end datetime
status	string	No	Challenge status

curl -X POST https://example.com/wp-json/wb-gamification/v1/community-challenges \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "title": "1000 Posts Together", "target_count": 1000, "target_action": "publish_post", "bonus_points": 50 }'

Kudos

Peer-to-peer recognition. Kudos always send; a per-user daily limit and a one-hour per-recipient window decide only whether a kudos earns points. A spam ceiling (default 50/day, filter wb_gam_kudos_daily_ceiling) is the only refusal.

Method	Endpoint	Permission
GET	/kudos	Public
POST	/kudos	Must be logged in
GET	/kudos/me	Must be logged in
DELETE	/kudos/{id}	wb_gam_manage_members

GET /kudos

Recent kudos feed.

Parameter	Type	Default	Description
limit	int	20	Max entries (1 to 50)

curl "https://example.com/wp-json/wb-gamification/v1/kudos?limit=20"

POST /kudos

Give kudos to another member. One of receiver_id or recipient_login is required.

Field	Type	Required	Description
receiver_id	int	conditional	User ID of recipient
recipient_login	string	conditional	Added in 1.4.0. Username or profile slug (user nicename) of the recipient, resolved server-side. Email is not accepted. Use this when the giver does not know the recipient’s user ID (e.g. the [wb_gam_give_kudos] shortcode)
message	string	No	Optional message (max 255 chars)

curl -X POST https://example.com/wp-json/wb-gamification/v1/kudos \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "receiver_id": 55, "message": "Great work on the docs!" }'

{ "success": true, "receiver_id": 55, "daily_remaining": 4, "can_send": true }

Returns HTTP 201 on success. daily_remaining is how many more kudos today will earn points; can_send is false once the member reaches the spam ceiling (hide your form then).

Errors: wb_gam_kudos_self and wb_gam_kudos_invalid_user (422), rest_user_invalid (404, recipient not found), wb_gam_kudos_daily_ceiling (429, spam ceiling), wb_gam_kudos_busy (429, another send from this member is in flight). Before 1.6.5 a single wb_gam_kudos_cooldown code covered the daily limit, the per-recipient window and the in-flight case; none of those refuse a kudos any more except the in-flight case.

GET /kudos/me

Current user’s kudos stats: received_total, daily_limit (kudos per day that earn points), sent_today, daily_remaining (points-earning kudos left today), and can_send (false only at the spam ceiling; hide the give-kudos form when false).

curl https://example.com/wp-json/wb-gamification/v1/kudos/me \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..."

DELETE /kudos/{id}

Revoke a kudos: reverses the point awards on both sides, soft-marks the row, and audits the reversal. Admin (or wb_gam_manage_members) only.

Field	Type	Required	Description
reason	string	No	Audit reason recorded on the reversal events

curl -X DELETE https://example.com/wp-json/wb-gamification/v1/kudos/99 \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "reason": "Duplicate send" }'

Submissions

The user-generated-content submission queue. Members submit evidence of an achievement; admins approve or reject. Approval routes through the points engine so badges, levels, and totals stay consistent.

Method	Endpoint	Permission
GET	/submissions	manage_options
POST	/submissions	Must be logged in
POST	/submissions/{id}/approve	manage_options
POST	/submissions/{id}/reject	manage_options

POST /submissions

Submit an achievement for review. A daily cap applies per user.

Field	Type	Required	Description
action_id	string	Yes	Action the submission claims
evidence	string	No	Text description of the evidence
evidence_url	string	No	URL pointing to evidence

curl -X POST https://example.com/wp-json/wb-gamification/v1/submissions \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "action_id": "external_talk", "evidence": "Spoke at WordCamp", "evidence_url": "https://..." }'

GET /submissions

List submissions for review.

Parameter	Type	Default	Description
status	string	(all)	Filter by status
per_page	int	50	Rows per page (max 100)

POST /submissions/{id}/approve

Approve a submission. Optional notes field is stored with the decision.

curl -X POST https://example.com/wp-json/wb-gamification/v1/submissions/12/approve \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "notes": "Verified against the conference schedule." }'

POST /submissions/{id}/reject

Reject a submission. Optional notes field is stored with the decision.

curl -X POST https://example.com/wp-json/wb-gamification/v1/submissions/12/reject \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "notes": "Could not verify the claim." }'

Redemption

The rewards store. Members spend points on catalog items; admins manage the catalog.

Method	Endpoint	Permission
GET	/redemptions	wb_gam_manage_rewards
POST	/redemptions	Must be logged in
GET	/redemptions/items	Public
POST	/redemptions/items	manage_options
GET POST PUT PATCH DELETE	/redemptions/items/{id}	manage_options (write), public (read)
GET	/redemptions/me	Must be logged in
POST	/redemptions/{id}/fulfill	wb_gam_manage_rewards
POST	/redemptions/{id}/refund	wb_gam_manage_rewards

GET /redemptions

New in 1.6.5. Every member’s redemptions, newest first, for staff and integrations - the fulfilment queue behind the store. Filterable by status and paginated.

Parameter	Type	Default	Description
status	string	empty (all)	'', pending, pending_fulfillment, fulfilled, or refunded
page	int	1	Page number (min 1)
per_page	int	20	Rows per page (1 to 100)

Response headers: X-WP-Total, X-WP-TotalPages.

curl "https://example.com/wp-json/wb-gamification/v1/redemptions?status=pending&per_page=20" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..."

[
  {
    "id": 7,
    "user_id": 42,
    "item_id": 3,
    "points_cost": 500,
    "status": "pending",
    "coupon_code": "",
    "created_at": "2026-03-18 12:00:00",
    "title": "Sticker Pack",
    "reward_type": "manual"
  }
]

created_at is UTC Y-m-d H:i:s. title and reward_type fall back to “Removed reward” and an empty string if the catalog item was deleted since the redemption was made.

POST /redemptions

Redeem a catalog item with the current user’s points.

Field	Type	Required	Description
item_id	int	Yes	Catalog item to redeem

curl -X POST https://example.com/wp-json/wb-gamification/v1/redemptions \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "item_id": 3 }'

POST /redemptions/items

Create a catalog item.

Field	Type	Required	Description
title	string	Yes	Item title
description	string	No	Item description
points_cost	int	Yes	Points required to redeem
point_type	string	No	Currency slug the cost is charged in
reward_type	string	Yes	Reward fulfilment type
reward_config	object	No	Type-specific reward configuration
stock	int	No	Available stock
is_active	boolean	No	Whether the item is purchasable

curl -X POST https://example.com/wp-json/wb-gamification/v1/redemptions/items \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "title": "Sticker Pack", "points_cost": 500, "reward_type": "manual", "stock": 100 }'

GET /redemptions/me

Current user’s redemption history.

curl https://example.com/wp-json/wb-gamification/v1/redemptions/me \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..."

POST /redemptions/{id}/fulfill

Mark a redemption fulfilled - the reward has been delivered. Returns 404 if the redemption does not exist, 409 if it is not in a state that can be fulfilled.

curl -X POST https://example.com/wp-json/wb-gamification/v1/redemptions/7/fulfill \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..."

POST /redemptions/{id}/refund

Refund a redemption: credits the points back to the member and restores stock. Returns 404 if the redemption does not exist, 409 if it is not in a state that can be refunded.

Field	Type	Required	Description
note	string	No	Reason recorded on the refund

curl -X POST https://example.com/wp-json/wb-gamification/v1/redemptions/7/refund \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  --cookie "wordpress_logged_in_xxx=..." \
  -d '{ "note": "Out of stock, refunding points" }'