Subscriptions and API Access

The App has four tiers. Current prices are on the pricing page; the capability boundaries below determine which documentation applies to an account.

Plan Overview

Cloud Voice works on UltimateSensor V2 with cloud firmware. Settings and usage are under Settings > Cloud Voice; see the voice assistant guide.

Alert limits are documented in Locations and alerts.

Personal API Tokens

Create tokens under Settings > API Tokens. Give every token a clear name. You do not choose abilities: a token gets the abilities of your plan at the moment you create it. Every plan gets price access. Pro and Business also get device, reading, statistics, solar-forecast and export access. After an upgrade, create a new token to use the extra abilities.

Treat a token like a password:

• copy it into the destination once and store it in a password manager;
• never place it in screenshots, public YAML or a Git repository;
• use a separate token for Home Assistant and every external application;
• revoke and replace it immediately when it may have leaked.

API Behaviour

The API is versioned under /api/v1 on https://api.smarthomeshop.io, with a limit of 60 requests per minute per user. Clients should handle authentication errors, validation responses, rate limits and temporary unavailability. Poll at a sensible interval and cache results rather than requesting the same history repeatedly.

Dynamic price endpoints can be used by an authenticated token with the appropriate price ability. The broader Cloud API for devices and measurements is restricted to Pro and Business. A token never grants more than its account plan and assigned abilities permit.

Energy Price Response

GET /api/v1/energy/prices uses the existing bearer-token authentication and prices:read ability. Alongside the existing electricity, gas, summary and tariff fields, it returns safe source and contract metadata:

{
  "pricing": {
    "source": "SmartHomeShop.io",
    "market": "EPEX NL",
    "price_type": "all_in",
    "currency": "EUR",
    "unit": "kWh",
    "timezone": "Europe/Amsterdam"
  },
  "contract": {
    "name": "My home contract",
    "supplier": "Example Energy",
    "provider": "Example Energy",
    "product": "Dynamic Energy Contract",
    "type": "dynamic",
    "location_id": 12,
    "location_name": "Home",
    "location": {
      "id": 12,
      "name": "Home"
    },
    "starts_at": "2026-01-01",
    "ends_at": null,
    "standing_charge_monthly": 7.5,
    "import_markup_per_kwh": 0.021,
    "feed_in_markup_per_kwh": 0.018,
    "currency": "EUR"
  }
}

Use GET /api/v1/energy/prices?location=12 to select the active contract linked to a location, or ?contract=34 to pin an owned contract directly. A location without its own contract uses the contract set to All locations. name is the user-defined contract name, provider is the readable supplier name and location.name is the user-defined location name.

GET /api/v1/energy/contracts returns the backwards-compatible flat contracts list and a locations list. Every location contains its active_contract, or null when that location has no current contract. Only one active contract can cover the same date range per location.

When no applicable contract can be resolved, the price endpoint returns HTTP 422 with code energy_contract_required and does not include electricity, gas or summary prices. Monetary fields are JSON numbers and optional values can be null. Customer numbers and private references are never returned.