curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customer_key": "cust-6d11ca90",
"event_id": "evt_12345",
"actual_quantity": 4
}'{
"data": {
"event_id": "evt_12345",
"adjusted": true,
"actual_quantity": 4,
"actual_credit_used": 0,
"refunded_quantity": 1,
"refunded_credit": 0,
"deducted_quantity": 0,
"deducted_credit": 0,
"message": "Usage adjusted"
}
}Adjust a Usage Event
Corrects a usage event you already recorded, by its event_id. Send the actual amount the customer used (not a delta) and Metrifox handles the difference:
- Less than recorded → the difference is refunded.
- More than recorded → the difference is charged.
- Leave both amounts out → the event is undone completely.
Sending the same value again does nothing, so retries are safe.
What an adjustment can do depends on the feature’s aggregation method. SUM accepts any actual_quantity. COUNT and COUNT_UNIQUE ignore the quantity, so actual_quantity can only be 0, which stops the event counting — on COUNT_UNIQUE that also frees the value to be counted again. An adjustment is refused for a COUNT_UNIQUE event that did not count (a repeat of a value already counted, or a release of a value that was not being counted), for an event whose billing period has closed and been invoiced, and for an adjustment event itself. A credit-only adjustment is still accepted after the period closes, since credit returns to the wallet.
curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customer_key": "cust-6d11ca90",
"event_id": "evt_12345",
"actual_quantity": 4
}'{
"data": {
"event_id": "evt_12345",
"adjusted": true,
"actual_quantity": 4,
"actual_credit_used": 0,
"refunded_quantity": 1,
"refunded_credit": 0,
"deducted_quantity": 0,
"deducted_credit": 0,
"message": "Usage adjusted"
}
}Usage endpoints are served from https://api-meter.metrifox.com. Other API calls stay on https://api.metrifox.com.For example, if you recorded 5 image generations but the customer only used 4, send the actual amount and the difference is refunded.
What an adjustment can do depends on the aggregation method
SUM reads the quantity you send, so actual_quantity can be any amount. Send the true total
and the difference is refunded or charged.
COUNT and COUNT_UNIQUE ignore the quantity — an event either counted or it did not — so
actual_quantity can only be 0, which stops the event counting. Any other value is rejected.
To count again, send another event; an adjustment cannot create one.
On a COUNT_UNIQUE feature, adjusting to 0 also frees the value, so the same
account_id (or whichever properties the feature aggregates on) counts again the next time you
send an event carrying it. This is the only way to un-count a value on a per-use feature, where
negative quantities are rejected.
Adjustments that are refused
- A
COUNT_UNIQUEevent that did not count. A repeat of a value already counted records nothing, and so does a release of a value that was not being counted. Neither moved any usage, so there is nothing to take back — adjust the event that counted the value instead. No other aggregation method can produce one of these. - An event whose billing period has closed. The usage has already been invoiced, and reopening the pool would leave it disagreeing with the invoice raised from it. Issue a credit note for the amount instead.
- An adjustment event. Adjustments net into the original, so correct a mistake by adjusting the original event again.
actual_credit_used with no actual_quantity — is still accepted after
the billing period closes, because credit returns to the customer’s wallet rather than to a pool.Authorizations
Body
The unique customer identifier in your application.
The event_id of the original usage event to adjust.
The true quantity the customer used. Omit to leave quantity unchanged. On a COUNT or COUNT_UNIQUE feature the only accepted value is 0, which stops the event counting.
The true credits the customer used (prepaid features). Leave out to keep credits unchanged.
Optional human-readable note stored on the adjustment for audit.
Response
Adjustment applied (or a no-op if already at the requested amount).
Show child attributes
Show child attributes