METER_NOT_FOUND error when recording usage
I'm implementing metered billing and getting an error when trying to record usage.
Working endpoints:
- GET /api/v1/user?id={userId}&expand=billing ✅
- GET /api/v1/billing/agreements?customer_id={customerId} ✅
Failing endpoint:
- POST /api/v1/billing/meter_usage ❌
Error response:
{
"errors": [{
"code": "METER_NOT_FOUND",
"message": "Meter corresponding to entitlement not found"
}]
}
Request payload structure:
{
"customer_agreementid": "agreement[redacted]",
"billing_feature_code": "[feature_code]",
"meter_value": "1",
"meter_type_code": "delta"
}
The user has:
- Valid customer_id
- Active agreement with the feature entitlement
- The feature appears in their entitlements list
But when trying to record usage via the meter_usage endpoint, it returns 400 with
METER_NOT_FOUND. Is there additional configuration needed for the meter to be
associated with the billing feature?
20 Replies
Hi @EJ., thanks for sharing those details.
To help us troubleshoot the
METER_NOT_FOUND error when calling the POST /api/v1/billing/meter_usage endpoint, could you please provide the following:
- Are you using user or organization plans?
- Could you share a screenshot of the plan in the Kinde Admin dashboard?
- In Stripe, what do you see under the customer’s record or subscription related to this plan?
These details will help us pinpoint the issue more accurately.
Let me know if you need help locating any of this info!Hey,
- User plan
- Shared
- It's empty - entitlements are empty
Maybe it matters that it's a free user? It doesn't create an entitlement in stripe if it's a free user?
Hi @EJ. , thanks for confirming that it’s a user plan and that the entitlements are empty in Stripe for the free user.
We believe this might be related to usage not being tracked when the user is on a free plan. That said, our expected behaviour is that usage should still be supported even for free users so we’re currently looking into this on our side and trying to replicate the issue.
We’ll let you know as soon as we have more to share. Thanks for your patience in the meantime!
Do you think there is some way for me to track it in the meanwhile? Should I create a new property for the user and work with that or what else would you suggest?
Hi @EJ., yes, creating a custom property for the user and using that to track usage sounds like a solid workaround for now.
We’re still investigating the expected behaviour around metering on free plans and will keep you posted once we have a clearer answer or a fix in place.
Appreciate your patience, let us know if you’d like help setting up that custom tracking in the meantime!
Hey, any updates on this?
Or in general, approaches of how clients implement Free tier for billing with capped access.
Hi @EJ. , thanks for checking in.
We're still actively investigating the metering issue on free plans. In the meantime, your earlier workaround (using a custom user property to track usage) is a solid approach and totally fine to continue with for now.
We’ll keep you updated as soon as we have more clarity or a fix in place. Appreciate your patience!
Hi @EJ., thanks again for your patience.
Just a quick update, metered usage only works if the plan has a fixed charge greater than $0. On free plans, usage isn’t sent to Stripe, and you’ll see the
METER_NOT_FOUND error if the feature’s pricing model is set to none.
For now, using a custom property to track usage is still the best workaround for free users.
Our team is working on improving this, and I’ll keep you posted as soon as we have any updates. Really appreciate your patience in the meantime!Hey! Any updates on this?
Hey EJ.,
Just jumping in here.
To give you more detail: Kinde does store all metering data, and we are the source of truth for it. The current limitation comes from our dependency on Stripe - if a feature doesn’t have a fixed charge or chargeable unit attached, Stripe won’t create the meter, which is why you’re seeing the
I’ll keep you posted on progress as we ship the enhancement. Really appreciate you hanging in there while we close this gap.
Just jumping in here.
To give you more detail: Kinde does store all metering data, and we are the source of truth for it. The current limitation comes from our dependency on Stripe - if a feature doesn’t have a fixed charge or chargeable unit attached, Stripe won’t create the meter, which is why you’re seeing the
METER_NOT_FOUND error.
We know this isn’t ideal, and we’re making a big enhancement so that metering works regardless of whether there’s a fixed charge. That work is already in our current development cycle, so you can expect this behaviour to improve.
For now, the best workaround on free plans is still to track usage through a custom property.I’ll keep you posted on progress as we ship the enhancement. Really appreciate you hanging in there while we close this gap.
so in this marketing promotional case, how would you currently track the 3gb / month or 10 transfers per month for the free plan?
Hi @EJ., for now, we’d suggest using custom properties to track usage limits for free plans and resetting them each month to manage access.
Ok. On monthly subscriptions - are the meters reset every month? Say for example I give 1 API call for 1 USD / month. I create a metered feature that is capped at 1, but then will it be reset after the next billing cycle?
Next month, after the user pays 1 USD, will this meter reset? Or do I need to play with settings in Kinde/in Stripe?
Hi @EJ., yes, for plans with a base price greater than $0, the metering resets automatically at the end of each billing cycle. The billing cycle is monthly and starts on the day the user signs up, so usage limits will refresh each month without needing any manual changes in Kinde or Stripe.
So even if the fixed price is above 0, the entitlement is still not created automatically and there is a METER_NOT_FOUND error
Hi @EJ., great catch.
Even if the plan has a fixed price above 0, metering will only work if the feature also has a charge set. If the feature has no charge, Stripe won’t create the meter, and you’ll see the
METER_NOT_FOUND error.
This is a known gap, and we’re working on improving it so metering works regardless of pricing.
Really appreciate you hanging in there while we close this gap.What if the charge is set at 0?
In essence, how do I create plans, where
1. For x amount you can do 1 action a month
2. For y amount you can do 5 actions a month
and track the consumption of these actions?
Hi @EJ., good questions.
If you set the feature’s price to $0, metering won’t work - Stripe won’t create the meter, and you’ll get the same METER_NOT_FOUND error.
Also, just to check - are you looking to:
- Charge a fixed amount per month and include a set number of actions?
- Or charge based on how many actions the user actually does (pay-as-you-go)?
Let me know, and I can guide you through the best setup!
First option "Charge a fixed amount per month and include a set number of actions?"
Hi @EJ. - great, thanks for confirming.
In that case, you can create a plan with a base price (e.g. $X/month), and track the number of actions using a custom user property. You’d then check this value on your side to enforce limits, and reset it each billing cycle.
Let me know if you’d like help setting that up!