Skip to main content
POST
← Invoices API Create one or many invoices of mains water supplied to a facility. Their emissions (the emissions of supplying that water) are calculated in the background. This route only takes the fields this kind of invoice has; every other kind has its own route (see which route for which consumption). The invoices are the ones v1 stores with type: water, so every /v1/invoices read and edit sees them. The request checks every record and writes them all at once, then answers 202 Accepted with an ingest job that calculates them (see how bulk ingestion works). Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

How it works

  1. Every record is checked. If any is invalid the whole request is rejected with 422 and nothing is written (all or nothing): rejected is the number of invalid records and errors lists them (up to 100).
  2. The invoices are written at once, with status loading. An invoice of several facilities (facility_percentages) becomes one invoice per facility, each with its share of quantity and total_spend.
  3. The job calculates their emissions in the background, in chunks. Each invoice ends active, or error when it could not be calculated: its job item is then failed with CALCULATION_FAILED.
  4. When every chunk is done the job is completed (or completed_with_errors) and, for a job submitted with an API key, ingest_job.finished is sent to the webhook endpoints of the organization in x-organization-id.

Request

Headers

string
required
Your API key (see Authentication).
string
required
The organization the invoices are sent for. Valid destinations are the facilities of its perimeter (this organization and the ones under it that you can write to) and, beyond it, those of any organization where the API key’s user is an enabled member.
string
required
1 to 255 characters, one per batch, looked up per organization across every v2 bulk route. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true) instead of creating the invoices again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free, and a request with it is a new one. See The Idempotency-Key.

Query Parameters

boolean
default:"false"
Check only: the same 422 for invalid records, nothing written, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every record is valid. The Idempotency-Key header is still required, but a dry run does not check or store it.

Body Parameters

array[object]
required
The invoices to create, 1 to 5,000.

Response

202 Accepted with the job (entity_type: invoices, operation: create) and a Location header to it. To read the result:
  • GET /v2/ingest-jobs/{id}/items has one item per record, in the order sent. Its entity_id is the invoice’s id; for an invoice split across facilities, the id of its first facility’s invoice (the others share it as source_invoice_id). A failed item carries its error_code.
  • List Invoices returns the invoices with their status and emissions (co2e).
If chunks_done stops moving, see A job that does not finish: never resend the batch with a new Idempotency-Key, because its invoices are already stored.

Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED: Request-level errors: 401 for a missing or invalid API key, 403 LOGGED_USER_NOT_MEMBER when the key’s user is not a member of the organization, 422 REQUEST_VALIDATION_FAILED for a malformed body (no records, more than 5,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

Limits

Invoices API

Which route for which consumption

Delete Invoices (v2)

Delete invoices of any category

Get Ingest Job

Follow the calculation

List Job Items

The invoice id and outcome of each record

List Invoices

The invoices and their emissions

List Units

Unit and currency ids