---
# @generated by sylphx-gen 0.1.0 from contracts@e664fe65409be842d8cfe92158f1f0e2a807b853c23c59c21071742348bcaf56. Do not edit.
title: "Batch ingest on an usage event"
description: "`money.usage_events.batch_ingest` (POST /v1/{parent}/usage_events:batchIngest): Records a batch of already-incurred usage from the merchant's own servers (Stripe's meter-event model): the caller is a key of the merchant's own org holding…"
type: reference
product: payments
summary: "Records a batch of already-incurred usage from the merchant's own servers (Stripe's meter-event model): the caller is a key of the…"
updated: 2026-09-28
nav: false
---

Records a batch of already-incurred usage from the merchant's own servers (Stripe's meter-event model): the caller is a key of the merchant's own org holding the exact grant `billing:metering:ingest`, which no wildcard covers, and each event names its subject with no subject proof. Each event is keyed by its project, meter, meter version and event id: a replay is a no-op (`duplicate`), and the same key with different content is a `conflict` and never counted. One result per event, in request order.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_events:batchIngest`
- **Scope** `billing:metering:ingest`
- **Effect** `write` — a successful call changes state.
- **Collection** [usage_events](/docs/api/usage_events)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `parent` | `string` | The environment to record in. Required. |
| `usage_events` | `IngestedUsageEvent[]` | 1 to 500 events. Required. |

### IngestedUsageEvent

| Field | Type | What it is |
| --- | --- | --- |
| `event_id` | `string` | The emitter's id of this event, 1 to 128 characters of `[A-Za-z0-9._:-]`; with the meter and its version, the dedupe key. Required. |
| `meter` | `string` | The meter. Required. |
| `meter_version` | `int32` | The emitter's version of the meter's definition, 1 or more. Required. |
| `subject` | `Subject` | Who used it, as attributed by the emitter. Required. |
| `quantity` | `int64` | How much, 1 to 2^40. Required. |
| `occurred_time` | `timestamp` | When it happened. Required. |

### Subject

| Field | Type | What it is |
| --- | --- | --- |
| `end_user` | `string` | An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the `kind` group. |
| `customer_organization` | `string` | A customer organization's id. One of the `kind` group. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `results` | `IngestedUsageEventResult[]` | One per event, in request order. |

### IngestedUsageEventResult

| Field | Type | What it is |
| --- | --- | --- |
| `event_id` | `string` | The event's `event_id`. |
| `outcome` | `string` | `accepted` (recorded now), `duplicate` (already recorded with the same content: a no-op), `conflict` (its key was recorded with other content; this one is never counted) or `rejected` (refused; see `reason`). |
| `reason` | `string` | For `rejected`: `invalid` (a field is out of range), `unpriced` (no active meter with a price in force at `occurred_time`) or `reservation_required` (the meter records only through a reservation); empty otherwise. |
| `usage_event` | `string` | The UsageEvent that counts this usage, for `accepted` and `duplicate`. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.
- [`UNKNOWN_FIELD`](/docs/api/errors/UNKNOWN_FIELD) — The request has a field the schema does not know.
- [`INVALID_STATE`](/docs/api/errors/INVALID_STATE) — The Resource is in a state that forbids the call.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_events:batchIngest" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usage_events":[{"event_id":"…","meter":"…","meter_version":1,"occurred_time":{},"quantity":1,"subject":{}}]}'
```

**TypeScript**

```ts
const response = await sylphx.money.usageEvents.batchIngest({ parent: 'orgs/acme/projects/shop/envs/production', usageEvents: [{ eventId: '…', meter: '…', meterVersion: 1, occurredTime: {}, quantity: 1, subject: {} }] })
```

**Rust**

```rust
let mut req = sylphx::money::BatchIngestUsageEventsRequest::default();
req.parent = "orgs/acme/projects/shop/envs/production".to_string();
req.usage_events = vec![Default::default()];
let response = sx.money().usage_events().batch_ingest(req).await?;
```

**CLI**

```bash
sylphx money usage-events batch-ingest orgs/acme/projects/shop/envs/production
```

**MCP**

```json
{ "method_id": "money.usage_events.batch_ingest", "args": {"parent":"orgs/acme/projects/shop/envs/production","usage_events":[{"event_id":"…","meter":"…","meter_version":1,"occurred_time":{},"quantity":1,"subject":{}}]} }
```