Resources

Subscriptions

The organisation's Maci Service subscriptions. Each is on one unit or unassigned, and the API only reaches units that have one. Subscriptions are bought in the app; the API decides which units have them.

GET/subscriptionsList subscriptions
PUT/units/{unit}/subscriptionAssign subscription
DELETE/units/{unit}/subscriptionUnassign subscription

The subscription model

Properties

id string (uuid)
product string

One of service
status string

cancelling stops at cancel_at; suspended is on hold for an unpaid invoice.

One of active, cancelling, suspended
unit_id string (uuid), nullable

The unit it is on, or null when it is unassigned.
interval string

One of month, year
paid_through string (date-time), nullable
cancel_at string (date-time), nullable
started_at string (date-time), nullable

GET/subscriptions

List subscriptions

The organisation's Maci Service subscriptions.

Each subscription is on one unit (unit_id) or unassigned (unit_id is null). Unassigned subscriptions are paid for like the others. Subscriptions are bought in the app.

Scope: subscriptions:read

Query parameters

unassigned boolean

true for only the unassigned subscriptions, false for only those on a unit.
limit integer

Records per page. At most 100, default 50.
cursor string

The value of next_cursor from the page before.

Response

200 A page of subscriptions. The fields are those of the subscription model.

Request

GET/subscriptions

curl https://api.maci.energy/v1/subscriptions \
  -H "Authorization: Bearer $MACI_API_KEY"

const response = await fetch('https://api.maci.energy/v1/subscriptions', {
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.maci.energy/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.maci.energy/v1/subscriptions', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "data": [
    {
      "id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84",
      "product": "service",
      "status": "active",
      "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
      "interval": "month",
      "paid_through": "2026-11-30T09:15:00Z",
      "cancel_at": null,
      "started_at": "2026-01-30T09:15:00Z"
    }
  ],
  "next_cursor": null
}

PUT/units/{unit}/subscription

Assign subscription

Give the unit Maci Service from an unassigned subscription.

The unit has to be one of the organisation's own units, in use. Without subscription_id the oldest unassigned subscription is used. A unit that already has one answers with it. To move a subscription from another unit, take it off that unit first. 409 when the organisation has no unassigned subscription.

Scope: subscriptions:write

Path parameters

unit string (uuid) required

The ID of the unit.

Body

subscription_id string (uuid)

An unassigned subscription of the organisation's.

Response

200 The subscription, now on the unit. The fields are those of the subscription model.

Request

PUT/units/{unit}/subscription

curl -X PUT https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription \
  -H "Authorization: Bearer $MACI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84"
  }'

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subscription_id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84"
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
    json={
        "subscription_id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84"
    },
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
    'json' => [
        'subscription_id' => '6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84',
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84",
  "product": "service",
  "status": "active",
  "unit_id": "0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11",
  "interval": "month",
  "paid_through": "2026-11-30T09:15:00Z",
  "cancel_at": null,
  "started_at": "2026-01-30T09:15:00Z"
}

DELETE/units/{unit}/subscription

Unassign subscription

Take the unit's subscription off it.

The subscription stays the organisation's, paid as before, and can be given to another unit. The unit's F-gas log can still be read, but nothing can be added to it.

Scope: subscriptions:write

Path parameters

unit string (uuid) required

The ID of the unit.

Response

200 The subscription, now unassigned. The fields are those of the subscription model.

Request

DELETE/units/{unit}/subscription

curl -X DELETE https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription \
  -H "Authorization: Bearer $MACI_API_KEY"

const response = await fetch('https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.MACI_API_KEY}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.delete(
    "https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription",
    headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.maci.energy/v1/units/0b6f4c1e-5a1d-4a57-9f0e-2f6f3f0c9a11/subscription', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
    ],
]);
$data = json_decode($response->getBody(), true);

Response 200

{
  "id": "6f2d9c1a-8b3e-4d70-a5f1-3c2b1a0e9d84",
  "product": "service",
  "status": "active",
  "unit_id": null,
  "interval": "month",
  "paid_through": "2026-11-30T09:15:00Z",
  "cancel_at": null,
  "started_at": "2026-01-30T09:15:00Z"
}