Add metered usage for a customer via API

From time to time, you may need to manually add metered usage for an individual customer. You can do this via the Kinde Management API.

This guide covers usage for:

• Recurring metered features on a subscription plan
• Metered one-time purchases the customer has bought or been assigned (for example a credit pack)

Adding usage values requires:

• your customer’s agreement ID
• the feature code you want to record usage against

For metered one-time purchases, the customer must have completed at least one purchase or received an admin assignment (paid or complimentary) of that feature before you can record usage.

Get the agreement ID

Link to this section

• Via API — Include the billing expand parameter in your request to get billing agreements and access the agreement ID.

• Via the Kinde UI — Open the user or organization record in Kinde and select Billing in the menu. The customer agreement shows as part of the subscription details.

  

Get the feature code

Link to this section

1. Open the plan the feature belongs to.
2. Click on the top-right three-dot drop-out menu.
3. Click on “Copy key” and the value of the key is copied to your clipboard OR
4. Edit the feature or one-time charge (to view it) on the plan.
5. Take note of the Key.

For one-time charges, the key is on the one-time charge card under One-time charges.

Submit usage data

Link to this section

POST usage to the Create meter usage record endpoint with the feature code and agreement ID.

{
  "customer_agreement_id": "agreement_0195ac80a14c2ca2cec97d026d864de0",
  "billing_feature_code": "ai_credits",
  "meter_value": 25,
  "meter_type_code": "delta"
}

Running totals

Link to this section

How usage accumulates depends on the feature type and expiry:

Feature type	Running total
Recurring metered feature on a plan	Current billing cycle total. Resets when the cycle rolls.
Metered one-time purchase — Expires with the billing cycle	Current billing cycle total. Resets when the cycle rolls.
Metered one-time purchase — Never expires	Lifetime total for that agreement and feature. Does not reset when the billing cycle rolls.

meter_type_code controls how each record updates the running total:

• absolute (default) — sets the running total to meter_value
• delta — adds meter_value to the last calculated running total

meter_usage_timestamp is stored on the record but does not choose a billing cycle, insert the record in timestamp order, or change the running-total arithmetic.

The response includes a grant snapshot (units_granted, current_usage, and expiration_policy_code when the grant is a one-time purchase) so you can see whether usage has exceeded the purchased allowance without a follow-up request.

Read usage records

Link to this section

Use Get billing meter usage to page usage records for an agreement and feature. By default only records in the current billing cycle are returned. Pass all_cycles=true to include every record.

List one-time purchases

Link to this section

To see what a customer has bought, use Get billing one-time purchases. This returns paid, non-expired purchases on the active agreement. Purchases on a previous agreement (for example after a plan change) are omitted.

See One-time purchases for how customers buy these purchases and how assignments work.