Record usage for billing using the API

To report usage data to Stripe, create a Meter and send meter events that include the event name configured on the meter, customer ID, numerical value, and, optionally, a timestamp. The frequency at which you submit usage data is flexible; you can report it as it occurs or in batches (for example, every day). Learn more about pricing on usage in the implementation guide.

Stripe processes meter events asynchronously, so usage aggregates in meter event summaries and on upcoming invoices might not immediately reflect recently received meter events.

To create Meter Events:

curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d event_name=alpaca_ai_tokens \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"={{CUSTOMER_ID}}

Idempotency

Use idempotency keys to prevent reporting usage more than one time due to latency or other issues. Every meter event corresponds to an identifier that you can specify in your request (if you don’t specify it, we auto-generate one).

Event timestamps

Make sure that the timestamp falls within the past 35 calendar days and isn’t more than 5 minutes in the future (the 5-minute window accounts for clock drift between your server and Stripe’s systems).

Usage values

The numerical usage value in the payload only accepts whole number values. If the overall cycle usage is negative, Stripe reports the invoice line item usage quantity as 0.

Rate limits

The Meter Events endpoint allows 1000 calls per second in live mode, and one concurrent call per customer per meter. If your service might exceed this limit, you can “bundle” your product into amounts. For example, if you charge per 1000 requests, base your product on “per 1k transactions” and send 1 usage record every 1000 times.

Monitor for 429 status codes and implement a retry mechanism with an exponential back-off schedule to manage request volume.

Also, consider incorporating some randomness into the back-off schedule to avoid a thundering herd effect.

In test and sandbox mode, calls to the meter events and meter event stream endpoint count toward the basic limit.

High-throughput ingestion with higher rate limits

With the API v2, you can send up to 10,000 events per second to Stripe using meter event streams. Contact sales to access sending up to 100,000 events per second.

This endpoint uses stateless authentication sessions. First, use the Meter Event Session API to create a meter event session and receive an authentication token. Then, use the returned authentication token to create your high-throughput meter events with the Meter Event Stream API.

Authentication tokens are only valid for 15 minutes, so you will need to create a new meter event session when your token expires. Here’s an example high-throughput integration:

require 'stripe'
require 'date'

class MeterEventManager
  attr_accessor :api_key
  attr_accessor :meter_event_session

  def initialize(api_key)
    @api_key = api_key
    @meter_event_session = nil
  end

  def refresh_meter_event_session
    if @meter_event_session.nil? || DateTime.parse(@meter_event_session.expires_at) <= DateTime.now
      # Create a new meter event session in case the existing session expired
      client = Stripe::StripeClient.new(api_key)
      @meter_event_session = client.v2.billing.meter_event_session.create
    end
  end

  def send_meter_event(meter_event)
    # Refresh the meter event session if necessary
    refresh_meter_event_session


    # Create a meter event with the current session's authentication token
    client = Stripe::StripeClient.new(meter_event_session.authentication_token)
    client.v2.billing.meter_event_stream.create(
      events: [meter_event]
    )
  end
end

# Send meter events
api_key = "{{API_KEY}}"
customer_id = "{{CUSTOMER_ID}}"

manager = MeterEventManager.new(api_key)
manager.send_meter_event(
  {
    event_name: 'alpaca_ai_tokens',
    payload: {
      "stripe_customer_id" => customer_id,
      "value" => '25'
    }
  }
)

Monitor for 429 status codes and implement a retry mechanism with an exponential back-off schedule to manage request volume.

Also, consider incorporating some randomness into the back-off schedule to avoid a thundering herd effect.

Handle meter errors with webhooks

Stripe asynchronously processes meter events.

If an error is found, Stripe creates one of the following events:

• v1.billing.meter.error_report_triggered: Summarizes recent errors with processing meter events
• v1.billing.meter.no_meter_found: Reports an incorrect meter ID

Stripe supports two payload types for events: thin and snapshot. The v1.billing.meter.error_report_triggered and v1.billing.meter.no_meter_found events only support thin event payloads.

View an example payload for each event type below:

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {
          "code": "meter_event_no_customer_defined",
          "error_count": 1,
          "sample_errors": [
            {
              "error_message": "Customer mapping key stripe_customer_id not found in payload.",
              "request": {
                "id": "",
                "idempotency_key": "37c741d8-1f7e-4adc-af16-afdca1d73b37"
              }
            }
          ]
        }
      ]
    },
    "validation_end": "2024-08-28T20:54:10.000Z",
    "validation_start": "2024-08-28T20:54:00.000Z"
  },
  "reason": null,
  "related_object": {
    "id": "mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61R2GlpFXJ4R3L5DN41Fb82guyGVEUmO"
  },
  "type": "v1.billing.meter.error_report_triggered"
}

The data attribute gives you fields about the context of the failure, helping you fix the validation errors and reprocess your invalid meter events.

• developer_message_summary: Provides a summarized report of all the validation errors identified.
• validation_start: Provides the start time bound when the validation error was triggered.
• validation_end: provides the end time bound when the validation error was triggered.
• reason: Provides an array of attributes explaining why the validation error was triggered.
• reason.error_count: Provides the total number of validation errors triggered.
• reason.error_types: Provides an array of different categories of validation errors triggered.
• reason.error_types.code: Provides the error categorization that was triggered. Possible error codes are the following:
  • meter_event_customer_not_found
  • meter_event_no_customer_defined
  • meter_event_dimension_count_too_high
  • archived_meter
  • timestamp_too_far_in_past
  • timestamp_in_future
  • meter_event_value_not_found
  • meter_event_invalid_value
  • no_meter: Only supported for the v1.billing.meter.no_meter_found event type.
• reason.error_types.error_count: Provides the total number of validation errors of a given error type.
• sample_errors: Provides an array of individual error messages triggered.
• sample_errors.error_message: Provides a sample error message explaining the specific error triggered.
• sample_errors.request.identifier: Provides the identifier of the meter event, allowing you to make adjustments to the erroneous meter event.

To programmatically listen to these events, set up an event destination by following these steps:

1. Open the Event destinations tab in Workbench, then click Create new destination. Alternatively, use this template to configure a new destination in Workbench with these two event types pre-selected.

2. Click Show advanced options, then select the Thin payload style.

3. Select v1.billing.meter.error_report_triggered and v1.billing.meter.no_meter_found from the list of events.

4. Create a handler to process the event. For example:

   Python

   import os
   from stripe import StripeClient
   from stripe.events import V1BillingMeterErrorReportTriggeredEvent
   
   from flask import Flask, request, jsonify
   
   app = Flask(__name__)
   api_key = os.environ.get('STRIPE_API_KEY')
   webhook_secret = os.environ.get('WEBHOOK_SECRET')
   
   client = StripeClient(api_key)
   
   @app.route('/webhook', methods=['POST'])
   def webhook():
       webhook_body = request.data
       sig_header = request.headers.get('Stripe-Signature')
   
   try:
       thin_event = client.parse_thin_event(webhook_body, sig_header, webhook_secret)
   
       # Fetch the event data to understand the failure
       event = client.v2.core.events.retrieve(thin_event.id)
       if isinstance(event, V1BillingMeterErrorReportTriggeredEvent):
           meter = event.fetch_related_object()
           meter_id = meter.id
   
           # Record the failures and alert your team
           # Add your logic here
   
       return jsonify(success=True), 200
   except Exception as e:
       return jsonify(error=str(e)), 400
   
   if __name__ == '__main__':
       app.run(port=4242)

5. Test your handler. Configure a local listener with the Stripe CLI to send events to your local machine for testing before deploying the handler to production. Use the --forward-thin-to flag to specify which URL to forward the thin events to and the --thin-events flag to specify which thin events to forward. You can forward all thin events with an asterisk (*), or a subset of thin events to your application.

   $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"
   

6. Trigger test events to your handler. Use the trigger function to run the following commands, which simulates the respective events in your account for testing:

   $ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
   $ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>
   

7. If you’re processing events with a webhook endpoint, verify the webhook signatures to secure your endpoint and validate all requests are from Stripe.

8. Correct and resend invalid events for re-processing.

Best practices

Usage data is crucial for accurate user billing. Make your system resilient to network failures. For example, use a reliable queue such as Amazon SQS to push data to Stripe so you can retry if necessary.