Refund a Commission

Use this endpoint when a customer is refunded for a payment that was originally attributed to an affiliate. Anderro will locate the matching commission and either void it (full refund) or proportionally reduce it (partial refund), and emit a commission.refunded webhook so your systems stay in sync.

Send an idempotency key to safely retry a refund. Without a key, partial refunds are incremental: each request deducts the specified amount again. A commission that has already been fully refunded returns 409.

Identifying the payment

You must provide exactly one identifier strategy. Pick the strongest one you have:

Email + payment_amount_cents searches live payments newest first after trimming and lowercasing the email. It uses the newest matching payment only when the match is unique; several matches return 409 ambiguous_payment. Use external_id or commission_id to resolve ambiguity.

Optional parameters

Keys are scoped to your product and retained for 30 days. Reusing a key with the same JSON body returns the original response body and status without applying another refund. Reusing it with a different body returns 409. JSON field order does not matter, and the key can move between the body and header. If both are supplied, they must match. After 30 days, the key can be used for a new refund. Validation errors do not reserve a key.

Example requests

Full refund via commission id (recommended):

curl -X POST https://anderro.com/api/v1/refunds \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_secret_key" \
  -d '{
    "commission_id": "comm_abc123",
    "reason": "Customer requested refund within trial period"
  }'

Full refund via Stripe charge id:

curl -X POST https://anderro.com/api/v1/refunds \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_secret_key" \
  -d '{
    "external_id": "ch_3NqLm12abcdef",
    "reason": "Chargeback"
  }'

Partial refund:

curl -X POST https://anderro.com/api/v1/refunds \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_secret_key" \
  -d '{
    "external_id": "ch_3NqLm12abcdef",
    "refund_amount_cents": 1500,
    "idempotency_key": "refund_order_123_partial_1",
    "reason": "Pro-rata refund for canceled mid-month"
  }'

Fallback via email + amount:

curl -X POST https://anderro.com/api/v1/refunds \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_secret_key" \
  -d '{
    "email": "[email protected]",
    "payment_amount_cents": 4900
  }'

Responses

{
  "data": {
    "commission_id": "comm_abc123",
    "partnership_id": "p_xyz789",
    "payment_amount_cents": 4900,
    "refund_amount_cents": 4900,
    "previous_commission_cents": 980,
    "new_commission_cents": 0,
    "status": "refunded",
    "fully_refunded": true
  }
}

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": {},
    "formErrors": ["Provide one of: commission_id, external_id, or (email + payment_amount_cents)"]
  }
}

{
  "error": "No payment matching that identifier was found for this product"
}

{
  "error": "Commission already fully refunded",
  "details": {
    "commission_id": "comm_abc123"
  }
}

{
  "error": "ambiguous_payment",
  "details": {"message": "Provide external_id or commission_id"}
}

{
  "error": "refund_amount_cents must be > 0 and <= the original payment",
  "details": {
    "payment_amount_cents": 4900
  }
}

How refunds affect commissions

The effect of a refund depends on the commission's current status:

Only commissions that were paid create negative refund adjustments. Unapplied adjustments appear as adjustment_cents on payout.created, whose amount_cents is already net of those adjustments. Do not also invoice the affiliate for the clawback: that would recover the same money twice.

Partial refunds proportionally reduce amount_cents but leave the status unchanged. Multiple partial refunds against the same commission accumulate until they sum to the full payment, at which point the commission flips to refunded.