Tracking API
Track Refund
Reverse or reduce the partner commission of a tracked sale when it is refunded, in full or in part. Send one call per refund.
POST /api/v1/track/refund
Reverses the affiliate commission tied to a previously tracked sale. Send one call per refund. Each call's refund_amount_cents is added to what was already refunded on the sale (capped at the sale amount). Once all of the sale is refunded, Affitor reverses the commission (reversed). A partial refund reduces a commission already approved and cancels one still pending (in its hold period, not yet approved); both end refunded. Omitting refund_amount_cents refunds everything that is left. This is the non-Stripe counterpart to the Stripe refund webhook: both use the same underlying reversal logic.
Send refund amounts in the sale's original currency and minor unit, including tax. For a sale with a commission to reverse, a supplied amount must be a positive integer; 0 is rejected with 400 invalid_request. Leave the field out to refund everything that remains. Older sales keep the legacy interpretation described below.
Authentication
All requests must include your program API key as a Bearer token.
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/jsonThe key is scoped to a single program. The refund lookup is restricted to sales that belong to the authenticated program.
Request
Fields
The transaction_id originally passed to POST /api/v1/track/sale. Used to locate the sale record.
For sales recorded from November 5, 2026 (16:00 UTC), this refund's amount is in the sale's original currency and minor unit, tax included. For a sale with a commission to reverse, it must be a positive integer when provided: 0, null, negative values and non-integers return 400 invalid_request with refund_amount_cents must be a positive integer. Omit the field to refund the rest. Send this refund's amount, not the running total refunded so far.
For older sales, the legacy interpretation is unchanged: the amount is read in hundredths of the currency unit the sale was recorded in (cents for a USD sale); omission, 0 or a negative value refunds the rest.
Your own id for this refund (for example the Stripe refund id). Recommended. A refund whose refund_id was already applied is ignored, so retries are safe. Without it, a second call with the same amount for the same sale is treated as a retry and ignored. Ignored for a whole-sale refund: omit the amount for new sales. For older sales, 0 or a negative amount also requests a whole-sale refund. Refunding the rest is already safe to retry.
Human-readable reason for the refund. Recorded on the commission and included in partner/advertiser notifications.
refund or chargeback. Recorded as the reason when refund_reason is not sent or empty.
refundchargebackExample request body
curl -X POST https://api.affitor.com/api/v1/track/refund \
-H "Authorization: Bearer YOUR_PROGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "txn_abc123",
"refund_amount_cents": 5000,
"refund_id": "re_123",
"refund_reason": "Customer requested cancellation"
}'For sales recorded from November 5, 2026 (16:00 UTC), a VND 10,000 refund uses refund_amount_cents: 10000; a JPY 1,000 refund uses 1000; a BHD 1.234 or KWD 1.234 refund uses 1234. Do not convert these amounts to USD or subtract tax before sending them.
Multiple refunds and retries
- Two partial refunds of $30 and $20 on a $100 sale: send
3000then2000(each with its ownrefund_id). A commission already approved is reduced by 50% in total; one stillpending(in its hold period, not yet approved) is cancelled by the first refund. - Retries: resending a call with the same
refund_idreturnsstatus: "skipped"and changes nothing. Withoutrefund_id, the amount is used to detect the retry.
Response
Success: commission reversed or refunded
{
"success": true,
"status": "reversed",
"deductionAmount": 25.00,
"commission_id": 88
}| Field | Type | Description |
|---|---|---|
success | boolean | Always true on a 200 response. |
status | string | "reversed" (sale fully refunded), "refunded" (partially refunded), or "skipped": nothing changed, and reason says why. Usually the refund was already applied or the commission was already reversed. When reason is refund history incomplete (manual review), this refund was not applied: contact support with the transaction_id. |
reason | string | Only with "skipped": why nothing changed. |
deductionAmount | number | The commission share this refund covers, in the commission's currency: the refunded fraction of the commission, or all of what is left once the sale is fully refunded. Taken from the partner's balance only when the commission was already credited (past pending, not a test). A pending commission that is partly refunded is cancelled whole, so for it this number is informational. Present when status is reversed or refunded. |
commission_id | integer | ID of the affected commission record. |
Success: sale has no commission
{
"success": true,
"status": "no_commission",
"message": "Sale has no commission to reverse"
}Already-processed refund (idempotent)
{
"success": true,
"status": "skipped",
"reason": "already reversed",
"commission_id": 88
}Test API key
{
"success": true,
"test": true
}A request with a test API key gets this answer before the body is checked or the sale is looked up. Nothing is refunded, so a test key cannot reverse a real commission.
Errors
Errors use the platform envelope with a stable error.code, except a retired API key and rate limiting, which use the typed envelope.
| Status | error.code | When |
|---|---|---|
| 400 | invalid_request | transaction_id is missing, reason is not refund or chargeback, or a supplied refund amount for a new sale is not a positive integer (including 0). The amount check applies when the sale has a commission to reverse. |
| 401 | unauthorized | Authorization header is missing, malformed, or the API token is invalid. |
| 404 | not_found | No sale record found for the given transaction_id in the authenticated program. |
| 500 | internal_error | Internal error during commission reversal. Retry the same request with the same refund_id: a refund that was already applied is skipped. |
Side Effects
When a commission is reversed or refunded, Affitor:
- transitions the commission to
reversedorrefundedstatus - if the commission was already credited to the partner (any status past
pending, and not a test), deducts the proportional amount from the partner's balance in the same transaction as the status change; the balance can go negative, and open withdrawals are reduced to fit - sends an in-app notification to the partner
- sends a manual-review warning to the advertiser if the commission had already been paid out
The status change and the deduction are applied before the response. The notifications are sent afterwards and never change the response.
Related
- Track Sale: record the original sale
- Payment Tracking: Stripe webhook alternative