Writes one customer_credits row and its customer_payments row of type credit (method referral-credit or store-credit, the negative amount), then customer-credit.created and the legacy credit-added. Kentro services only (403 otherwise). Idempotent per customer by externalId: onDuplicate error (default) is 409 duplicate; skip answers the existing credit (200, outcome skipped) when its type, amount, currency and referred customer equal the request, else 409. An inactive customer is 422 inactive_customer; a currency other than the channel currency is 400; an orderId or referredCustomerId outside the tenant is 422 unresolved_reference. Unknown fields are refused (400).

Scope: customers:write, channel:write or admin.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.