Deduct program XP

POST /v1/xp/program/deduct · requires xp:program:deduct

Program XP belongs to one program, such as an ambassador or creator program. It is separate from the member's server XP and level: deducting it changes neither.

Body parameters

List programs gives you each program's programId.

Who it can be taken from

The call is rejected unless both of these conditions are met:

• The program is active. A program that is a draft, paused or archived returns 409 with the code program_not_active.
• The member is in the program with the status Accepted or Active. A member with another status (such as Applied, Graduated or Removed) returns 409 with the code member_status_not_allowed, and a member who is not in the program returns 404 with the code member_not_enrolled.

Deducting more than the member has leaves their program XP at zero: xpDeducted reports what was actually removed.

Returns

The response also includes the original field names. They contain the same values, and remain for as long as version 1 exists.

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/xp/program/deduct \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": 3,
    "discordId": "409876543210987654",
    "amount": 50,
    "reason": "Reversed a duplicate award",
    "idempotencyKey": "reversal-10444"
  }'

The TypeScript example uses ceejay.xp.program.deduct from the TypeScript SDK. It returns the data of the response below.

{
  "success": true,
  "data": {
    "programId": 3,
    "programName": "Ambassadors",
    "discordId": "409876543210987654",
    "previousXP": 500,
    "xpDeducted": 50,
    "totalXP": 450,
    "reason": "Reversed a duplicate award",
    "auditId": "10445",
    "programXp": 450,
    "previousProgramXp": 500,
    "duplicate": false
  }
}

What a deduction does

• Deducts the XP from the member's program XP, which shows in the program's Members tab. Concurrent changes are all counted.
• Logs the change in the program's activity log, marked as made through the API with the key that made it, and writes an audit entry (auditId). The XP, the activity log line and the idempotency key are committed in a single transaction.
• Does not send a webhook event, does not count toward season XP and does not trigger level rewards.
• There is no request that reads program XP. Each change returns the new total.

Retrying safely

Send an idempotencyKey with every call you might need to retry, such as after a timeout. It is a string of 1 to 128 characters that you choose, sent in the JSON body: an Idempotency-Key header is not read.

• Retrying with the same key returns the original response. When the same request is sent again with its key, CEEJAY returns the original response, with duplicate: true and the header Idempotent-Replayed: true.
• Each key is tied to one request payload. The same request means the same program, member, amount and reason. Two requests for one event need two keys, for example match-9:coins and match-9:xp. A key that was used for a different request, here or on any other request of the API, returns 409 with the code idempotency_key_reused, and nothing is changed.
• A rejected request does not use up the key. A call that was rejected can be retried with the same key once the cause is fixed.
• A key belongs to the API key that sent it. Another API key of your community can send the same text, and it is a different key.
• Keys are retained for 30 days. Use a value you can regenerate after a crash, such as an order ID or a match ID.
• On an instance that does not support idempotency keys yet, a call that sends one returns 503 with the code idempotency_unavailable, and nothing is changed. Community details reports whether keys are supported, under features.retryKeys. idempotency_key is not accepted on this endpoint; use idempotencyKey.
• Without a key, a retried call is a new call.

Errors

{
  "error": "Program is not active",
  "code": "program_not_active",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "programStatus": "draft"
}

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request shares (401, 403, 405, 429, 500) are on the Errors page.