Meters

6 operations under /v1/meters (GET POST): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET `/v1/meters`

GEThttps://api.codespar.dev/v1/meters

List the project's meters with their cycle figures

Oldest first. period (YYYY-MM) reads a past cycle; the default is the current Sao Paulo month.

Query parameters

Name	Type	Required	Description
`period`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request.

Response 200

Field	Type	Required	Description
`data`	array of object	yes	—
`object`	`"list"`	yes	—
`period`	`string`	yes	—

Example request

curl -X GET https://api.codespar.dev/v1/meters \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/meters HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/meters",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/meters");

Example response 200

application/json

{
  "object": "list",
  "period": "string",
  "data": [
    {
      "id": "obj_0000000000000000",
      "object": "meter",
      "environment": "live",
      "event_name": "Example",
      "aggregation": "count",
      "price": "string",
      "currency": "BRL",
      "per_units": 1,
      "unit_label": "Example",
      "description": "string",
      "channel": "invoice",
      "status": "active",
      "created_at": "string",
      "updated_at": "string",
      "cycle": {
        "period": "string",
        "usage": "string",
        "customers": 0,
        "amount_to_date": "1000",
        "amount_to_date_minor": 1000,
        "amount_projected": "1000",
        "amount_projected_minor": 1000,
        "projected_usage": "string",
        "last_event_at": "string"
      },
      "spark": [
        {
          "day": "string",
          "usage": "string"
        }
      ]
    }
  ]
}

POST `/v1/meters`

POSThttps://api.codespar.dev/v1/meters

Define a meter on a usage event

Creates a meter in the caller's project. event_name is what the tenant's code sends as event on each usage event, unique in the project. aggregation says how a cycle is summed per customer: count (each event is 1), sum (of value), max (the largest value) or last (the latest value by event time). price is BRL per per_units (1 or 1000) units.

channel declares how the usage will be charged. It is stored and shown; nothing is issued from it, and no route here moves money.

Request body

Field	Type	Required	Description
`aggregation`	`"count"` \| `"sum"` \| `"max"` \| `"last"`	yes	—
`channel`	`"invoice"` \| `"collect"` \| `"gate"`	yes	—
`description`	`string`	no	—
`event_name`	`string`	yes	—
`per_units`	`1` \| `1000`	no	—
`price`	`number` \| `string`	yes	—
`unit_label`	`string`	no	—

Responses

Status	Body	Description
`201`	object	OK
`400`	object	Bad Request.
`409`	object	The project already has a meter for that event name.

Response 201

Field	Type	Required	Description
`aggregation`	`"count"` \| `"sum"` \| `"max"` \| `"last"`	yes	—
`channel`	`"invoice"` \| `"collect"` \| `"gate"`	yes	The charge channel the tenant declared: monthly invoice, Collect link or 402 on the Gate. A declaration only: no invoice, link or paywall is created from it.
`created_at`	`string`	yes	—
`currency`	`"BRL"`	yes	—
`cycle`	object	yes	—
`description`	`string,null`	yes	—
`environment`	`"live"` \| `"test"`	yes	The project's environment.
`event_name`	`string`	yes	The `event` each usage event names. Unique in the project.
`id`	`string`	yes	`mtr_` + 128 random bits, minted by the server.
`object`	`"meter"`	yes	—
`per_units`	`1` \| `1000`	yes	—
`price`	`string`	yes	BRL per `per_units` units, up to six decimals.
`status`	`"active"`	yes	—
`unit_label`	`string,null`	yes	—
`updated_at`	`string`	yes	—

Example request

curl -X POST https://api.codespar.dev/v1/meters \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "event_name": "Example",
       "aggregation": "count",
       "price": 0,
       "per_units": 1,
       "unit_label": "Example",
       "description": "string",
       "channel": "invoice"
     }'

POST /v1/meters HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "event_name": "Example",
  "aggregation": "count",
  "price": 0,
  "per_units": 1,
  "unit_label": "Example",
  "description": "string",
  "channel": "invoice"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/meters",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "event_name": "Example",
      "aggregation": "count",
      "price": 0,
      "per_units": 1,
      "unit_label": "Example",
      "description": "string",
      "channel": "invoice"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "event_name": "Example",
    "aggregation": "count",
    "price": 0,
    "per_units": 1,
    "unit_label": "Example",
    "description": "string",
    "channel": "invoice"
  }),
});

const data = await res.json();

const result = await cs.api.post("/v1/meters", {
  body: {
    event_name: "Example",
    aggregation: "count",
    price: 0,
    per_units: 1,
    unit_label: "Example",
    description: "string",
    channel: "invoice"
  }
});

Example response 201

application/json

{
  "id": "obj_0000000000000000",
  "object": "meter",
  "environment": "live",
  "event_name": "Example",
  "aggregation": "count",
  "price": "string",
  "currency": "BRL",
  "per_units": 1,
  "unit_label": "Example",
  "description": "string",
  "channel": "invoice",
  "status": "active",
  "created_at": "string",
  "updated_at": "string",
  "cycle": {
    "period": "string",
    "usage": "string",
    "customers": 0,
    "amount_to_date": "1000",
    "amount_to_date_minor": 1000,
    "amount_projected": "1000",
    "amount_projected_minor": 1000,
    "projected_usage": "string",
    "last_event_at": "string"
  }
}

GET `/v1/meters/cycle`

GEThttps://api.codespar.dev/v1/meters/cycle

The meter cycle: progress, totals and totals by channel

The cycle is the Sao Paulo calendar month. day_of_cycle is today's day for the open cycle and days_remaining the days after today until it closes. Totals add each meter's exact amount and round once. Amounts are forecasts of usage times price; nothing has been charged.

Query parameters

Name	Type	Required	Description
`period`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request.

Response 200

Field	Type	Required	Description
`active_meters`	`integer`	yes	—
`by_channel`	object	yes	—
`currency`	`"BRL"`	yes	—
`day_of_cycle`	`integer`	yes	—
`days_in_cycle`	`integer`	yes	—
`days_remaining`	`integer`	yes	—
`end`	`string`	yes	First instant after the cycle.
`object`	`"meter_cycle"`	yes	—
`period`	`string`	yes	—
`start`	`string`	yes	—
`state`	`"open"` \| `"closed"`	yes	—
`totals`	object	yes	—

Example request

curl -X GET https://api.codespar.dev/v1/meters/cycle \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/meters/cycle HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/meters/cycle",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters/cycle", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/meters/cycle");

Example response 200

application/json

{
  "object": "meter_cycle",
  "period": "string",
  "start": "string",
  "end": "string",
  "state": "open",
  "days_in_cycle": 0,
  "day_of_cycle": 0,
  "days_remaining": 0,
  "currency": "BRL",
  "active_meters": 0,
  "totals": {
    "meters": 0,
    "amount_to_date": "1000",
    "amount_to_date_minor": 1000,
    "amount_projected": "1000",
    "amount_projected_minor": 1000
  },
  "by_channel": {
    "invoice": {
      "meters": 0,
      "amount_to_date": "1000",
      "amount_to_date_minor": 1000,
      "amount_projected": "1000",
      "amount_projected_minor": 1000
    },
    "collect": {
      "meters": 0,
      "amount_to_date": "1000",
      "amount_to_date_minor": 1000,
      "amount_projected": "1000",
      "amount_projected_minor": 1000
    },
    "gate": {
      "meters": 0,
      "amount_to_date": "1000",
      "amount_to_date_minor": 1000,
      "amount_projected": "1000",
      "amount_projected_minor": 1000
    }
  }
}

GET `/v1/meters/{meterId}`

GEThttps://api.codespar.dev/v1/meters/{meterId}

Read one meter with its cycle figures

Path parameters

Name	Type	Required	Description
`meterId`	`string`	yes	—

Query parameters

Name	Type	Required	Description
`period`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request.
`404`	object	No meter with that id in this project.

Response 200

Field	Type	Required	Description
`aggregation`	`"count"` \| `"sum"` \| `"max"` \| `"last"`	yes	—
`channel`	`"invoice"` \| `"collect"` \| `"gate"`	yes	The charge channel the tenant declared: monthly invoice, Collect link or 402 on the Gate. A declaration only: no invoice, link or paywall is created from it.
`created_at`	`string`	yes	—
`currency`	`"BRL"`	yes	—
`cycle`	object	yes	—
`description`	`string,null`	yes	—
`environment`	`"live"` \| `"test"`	yes	The project's environment.
`event_name`	`string`	yes	The `event` each usage event names. Unique in the project.
`id`	`string`	yes	`mtr_` + 128 random bits, minted by the server.
`object`	`"meter"`	yes	—
`per_units`	`1` \| `1000`	yes	—
`price`	`string`	yes	BRL per `per_units` units, up to six decimals.
`status`	`"active"`	yes	—
`unit_label`	`string,null`	yes	—
`updated_at`	`string`	yes	—

Example request

curl -X GET https://api.codespar.dev/v1/meters/{meterId} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/meters/{meterId} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/meters/{meterId}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters/{meterId}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/meters/{meterId}", {
  path: {
    meterId: "meter_0000000000000000"
  }
});

Example response 200

application/json

{
  "id": "obj_0000000000000000",
  "object": "meter",
  "environment": "live",
  "event_name": "Example",
  "aggregation": "count",
  "price": "string",
  "currency": "BRL",
  "per_units": 1,
  "unit_label": "Example",
  "description": "string",
  "channel": "invoice",
  "status": "active",
  "created_at": "string",
  "updated_at": "string",
  "cycle": {
    "period": "string",
    "usage": "string",
    "customers": 0,
    "amount_to_date": "1000",
    "amount_to_date_minor": 1000,
    "amount_projected": "1000",
    "amount_projected_minor": 1000,
    "projected_usage": "string",
    "last_event_at": "string"
  }
}

GET `/v1/meters/{meterId}/events`

GEThttps://api.codespar.dev/v1/meters/{meterId}/events

A meter's latest events

Newest first by arrival, at most limit (1 to 50, default 20).

Path parameters

Name	Type	Required	Description
`meterId`	`string`	yes	—

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request.
`404`	object	No meter with that id in this project.

Response 200

Field	Type	Required	Description
`data`	array of object	yes	—
`object`	`"list"`	yes	—

Example request

curl -X GET https://api.codespar.dev/v1/meters/{meterId}/events \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/meters/{meterId}/events HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/meters/{meterId}/events",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters/{meterId}/events", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/meters/{meterId}/events", {
  path: {
    meterId: "meter_0000000000000000"
  }
});

Example response 200

application/json

{
  "object": "list",
  "data": [
    {
      "object": "meter_event",
      "event_id": "event_0000000000000000",
      "meter_id": "meter_0000000000000000",
      "customer": "string",
      "customer_name": "Example",
      "value": "string",
      "occurred_at": "string",
      "received_at": "string"
    }
  ]
}

GET `/v1/meters/{meterId}/usage`

GEThttps://api.codespar.dev/v1/meters/{meterId}/usage

A meter's usage on each day of the cycle

One point per Sao Paulo day of the cycle, in order. A day after today in the open cycle has usage and amount null; a past day without events has 0. Per day, usage is summed per customer by the meter's aggregation and then across customers.

Path parameters

Name	Type	Required	Description
`meterId`	`string`	yes	—

Query parameters

Name	Type	Required	Description
`period`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request.
`404`	object	No meter with that id in this project.

Response 200

Field	Type	Required	Description
`aggregation`	`"count"` \| `"sum"` \| `"max"` \| `"last"`	yes	—
`days`	array of object	yes	—
`meter_id`	`string`	yes	—
`object`	`"meter_usage"`	yes	—
`period`	`string`	yes	—
`state`	`"open"` \| `"closed"`	yes	—

Example request

curl -X GET https://api.codespar.dev/v1/meters/{meterId}/usage \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/meters/{meterId}/usage HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/meters/{meterId}/usage",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/meters/{meterId}/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/meters/{meterId}/usage", {
  path: {
    meterId: "meter_0000000000000000"
  }
});

Example response 200

application/json

{
  "object": "meter_usage",
  "meter_id": "meter_0000000000000000",
  "aggregation": "count",
  "period": "string",
  "state": "open",
  "days": [
    {
      "day": "string",
      "usage": "string",
      "amount": "1000"
    }
  ]
}

GET /v1/meters

POST /v1/meters

GET /v1/meters/cycle

GET /v1/meters/{meterId}

GET /v1/meters/{meterId}/events

GET /v1/meters/{meterId}/usage

On this page

GET `/v1/meters`

POST `/v1/meters`

GET `/v1/meters/cycle`

GET `/v1/meters/{meterId}`

GET `/v1/meters/{meterId}/events`

GET `/v1/meters/{meterId}/usage`