# 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.

## The subscription model

- `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)

## List subscriptions

`GET /subscriptions` · scope `subscriptions:read`

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.

### 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.

### Request

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

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

```python
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()
```

```php
$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

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

```json
{
  "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
}
```

## Assign subscription

`PUT /units/{unit}/subscription` · scope `subscriptions:write`

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.

### Path parameters

- `unit` (string (uuid), required): The ID of the unit.

### Body (JSON)

- `subscription_id` (string (uuid)): An unassigned subscription of the organisation's.

### Request

```bash
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"
  }'
```

```javascript
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();
```

```python
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()
```

```php
$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

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

```json
{
  "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"
}
```

## Unassign subscription

`DELETE /units/{unit}/subscription` · scope `subscriptions:write`

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.

### Path parameters

- `unit` (string (uuid), required): The ID of the unit.

### Request

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

```javascript
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();
```

```python
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()
```

```php
$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

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

```json
{
  "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"
}
```