Create Wallet Adjustment

Adds a signed amount to a wallet's Balance to record a payment, credit, refund or charge.

Adds a signed amount to a wallet's Balance to record a payment, credit, refund or offline charge. It is the only way to change the Balance by hand.

  • A negative Amount lowers the Balance and gives the wallet more room: a payment or a credit.
  • A positive Amount raises the Balance and uses room up: a charge that did not come from delivery.

An inactive wallet accepts adjustments.

API syntax

POST https://api.kevel.co/v1/wallet/{WalletID}/adjustment

Examples

To recordAmount
A payment of 10,000-10000
A 250 credit to the Advertiser-250
An offline charge of 1,2001200

Idempotency

Send a new UUID in X-Idempotency-Key for every adjustment and keep it with your payment record. If a request fails or times out, retry it right away with the same key and body. Kevel recognizes a repeated key on the same wallet for a limited time. A repeat returns 204 and the adjustment is applied once, so treat 201 and 204 as success. The same key with a different body on the same wallet returns 409. For an older payment, check List Wallet Adjustments before you resend, and put your payment reference in Memo.

Errors

StatusMessageWhat to do
400Amount must have at most 3 decimal places. / Amount magnitude must not exceed 4294967295.999.Fix the Amount.
400A message naming the field, or Bad request.Send a valid UUID in X-Idempotency-Key. Fix or remove any field of the wrong type or not recognized.
404Wallet {id} not found.Use one of your wallet IDs.
409idempotency key reused with different request payloadUse a new UUID for a new adjustment, or resend the original body.
500Balance adjustment service unavailable.Retry with the same key.
501Wallet adjustment is not configured in this environment.Contact your Kevel representative.
502Upstream authentication failure. / Unexpected response from upstream balance adjustment service.Not confirmed. Retry with the same key. If it continues, contact Kevel.
Path Params
integer
required

The wallet's ID.

Body Params
number
required

The signed amount to add to the Balance, with up to 3 decimal places and a size of at most 4,294,967,295.999. Negative lowers the Balance. Positive raises it.

string | null

A note kept with the adjustment and shown in the adjustment list.

Properties
object | null

Optional string-to-string metadata, such as an invoice ID. It is returned in this response.

Headers
uuid
required

A new random (version 4) UUID for each adjustment. Repeating the same key and body on the same wallet shortly afterwards does not apply it twice.

Responses

204

The same key and body were already applied. Nothing changed and there is no response body.

Language
Credentials
Header
LoadingLoading…
Response
Choose an example:
application/json