Record usage for billing no-code in DashboardPublic preview

Learn how to report usage events in bulk through the Dashboard.

You can add usage for meters by uploading a file in the Dashboard. Stripe parses, validates, and transforms the file contents into meter events. After processing the events from your file, Stripe displays them on your subscription invoice.

You can upload your meter usage events in CSV, JSON or JSONLINE file formats.

View an example of the CSV file format below.

CSV file format

Include the following fields in your file and make sure that they follow the Meter Event schema.

identifier: A unique identifier for the event. If not provided, Stripe generates one. We recommend using a globally unique identifier for this.
timestamp: The time of the event—measured in seconds since the Unix epoch.
event_name: The name of the meter event.
payload columns: Payload is a set of columns that contains key names to refer to customer and numerical usage values.
- payload_stripe_customer_id: This column contains the stripe_customer_id that the event gets created against.
- payload_value: This column represents the numerical usage value of the meter event. By default, the column name is payload_value. However, you can set it to match the field name that you set when creating the meter (prepend it by payload_).

Need support for different file format?

If you’re interested in uploading files with a different structure or in a custom format, contact us at user-data-acquisition-platform@stripe.com.

Upload files in the Dashboard

After preparing your file, you can upload it in the Dashboard.

Navigate to the Data management page.
Click Import file.
Select Data Template.
- For JSON format files, choose the Billing Meter Event Transaction Template - JSON.
- For JSONLINE format files, choose the Billing Meter Event Transaction Template - JSONLINE.
- For CSV format files, choose the Billing Meter Event Transaction Template - CSV.
Upload your file, then click Import file.
After Stripe successfully processes your file, you can check its status on the Import set list page.

Handle invalid meter events

Stripe asynchronously processes meter events and notifies you with a webhook if there are any errors found in the reported usage.

Stripe creates an Event of type billing.meter.error_report.triggered that summarizes recent errors with processing meter events. You can view these events in the Stripe Dashboard by navigating to the Events page. You can also automatically take action on these events by listening to them with a webhook endpoint.

View an example of the event below.

{
  type: "billing.meter.error_report.triggered",
  data: {
    object: {
      id: "err_123456"
      summary: "There are 2 invalid events",
      validation_start: 1724098690,
      validation_end: 1724098700,
      reason: {
        error_count: 2,
        error_types: [
          {
            error_code: "METER_NOT_FOUND",
            error_count: 2,
            "sample_errors": [
              {
                "error_message": "No meter was found matching event_name invalid_event_name.",
                "request": {
                  "id": "req_123456",
                  "idempotency_key": "idmpk_123456",
                }
              },
              {
                "error_message": "No meter was found matching event_name invalid_event_name.",
                "request": {
                  "id": "req_123457",
                  "idempotency_key": "idmpk_123457"
                }
              }
            ]
          }
        ]
      }
    }
  }
}

Review your uploaded files according to the information in sample_errors, correct the invalid events, and re-upload a file with corrections for re-processing.