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.
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_
: The name of the meter event.name payload columns
: Payload is a set of columns that contains key names to refer to customer and numerical usage values.payload_
: This column contains the stripe_customer_id that the event gets created against.stripe_ customer_ id payload_
: This column represents the numerical usage value of the meter event. By default, the column name isvalue payload_
. However, you can set it to match the field name that you set when creating the meter (prepend it byvalue 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.
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_
, correct the invalid events, and re-upload a file with corrections for re-processing.