Record usage for billing using S3Public preview
Report usage events from your S3 bucket in bulk.
You can send meter usage events to Stripe from your S3 storage bucket. Stripe parses, validates, and transforms the file contents into meter events. After the events from your file are successfully uploaded, 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_
: Payload is a set of columns that contains key names to refer to customer and numerical usage values.columns 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 event (prepend it byvalue payload_
).
Need support for different file format?
Contact us you’re interested in uploading files with a different structure or in a custom format.
Import files from your Amazon S3 bucket![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After your files are prepared, you can set up the S3 connector. The S3 connector automatically polls and processes those files. When you configure your S3 connector, make sure that you select the correct 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.
Handle invalid meter events![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe asynchronously processes meter events and notifies you with a webhook if we find any errors 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.