> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axle.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Site and asset lifecycle

> How sites and assets move through the platform, and how to manage them as your users change

A user owns a **site** — a physical property — and that site holds the **assets** (EV chargers, batteries and heat pumps) Axle can monitor and control. Enrolment, consents and payments all belong to the user via their site, so the operations below act on a **site**, not on individual users.

Over their lifetime, sites move between different states depending on whether they exist on the platform and whether they're enrolled in a [proposition](/workflows/ev-charging/overview#choosing-a-product) — the agreement that lets Axle participate in a market on the user's behalf.

This page describes those states, the API calls that move between them, and how to handle the everyday changes your users will throw at you: adding an asset, swapping a charger, opting out, or moving house.

## Managing sites

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'edgeLabelBackground': '#ffffff', 'fontSize': '14px'}}}%%
flowchart LR
classDef state fill:#ffffff,stroke:#222,stroke-width:1.5px,color:#222,rx:12,ry:12
  A["<b>Unseen / Deleted</b><br/>Inaccessible<br/>No active propositions"]:::state
  B["<b>Inactive</b><br/>Accessible<br/>No active propositions"]:::state
  C["<b>Active</b><br/>Accessible<br/>Active propositions"]:::state

  A -- "/initialise" --> B
  B -- "/enrol" --> C
  A -- "/onboard" --> C

  C -- "/unenrol" --> B
  C -- "/offboard" --> A

  linkStyle 0,1,2 stroke:#00C1FF,stroke-width:2px
  linkStyle 3,4   stroke:#FF3333,stroke-width:2px
```

| State                | Exists on platform? | Enrolled in a proposition? | What it means                                                                                                                                   |
| -------------------- | :-----------------: | :------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Unseen / Deleted** |          No         |             No             | We don't know about this site, or we've removed it.                                                                                             |
| **Inactive**         |         Yes         |             No             | The site and its assets exist — you can look them up, update them, and add or remove assets — but they're not participating in any proposition. |
| **Active**           |         Yes         |             Yes            | The site is enrolled and participating. Schedules, dispatches and rewards are all live.                                                         |

### Site transitions

Each arrow in the diagram is a single API call.

| Endpoint                                                      | From → To         | Use it when                                                                                                                                                  |
| ------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`onboard`](/workflows/flex-lite/api-reference/onboard)       | Unseen → Active   | **Preferred** — the common path for opting-in. Creates the site and assets **and** enrols them in one call; reach for it by default.                         |
| [`initialise`](/workflows/flex-lite/api-reference/initialise) | Unseen → Inactive | You want to create the site and assets, but do work before committing.                                                                                       |
| [`enrol`](/workflows/flex-lite/api-reference/enrol)           | Inactive → Active | The commitment point after `initialise` — this begins participation in a proposition (scheduling, readings, rewards).                                        |
| [`unenrol`](/workflows/flex-lite/api-reference/unenrol)       | Active → Inactive | **Preferred** — the common path for opting-out. The user is leaving a proposition but staying on the platform. Easily reversible; payments still accessible. |
| [`offboard`](/workflows/flex-lite/api-reference/offboard)     | Active → Deleted  | The user is leaving entirely. Removes the site and its assets.                                                                                               |

### Opting in

Most integrations sign a user up with a single [`onboard`](/workflows/flex-lite/api-reference/onboard) call, which creates the site and its assets **and** enrols them in one go.

Split it into [`initialise`](/workflows/flex-lite/api-reference/initialise) + [`enrol`](/workflows/flex-lite/api-reference/enrol) only when you need to do work between creating the site and committing it to a proposition — see [Advanced Onboarding](/workflows/flex-lite/advanced-integration) for details.

### Opting out

A user can stop participating in two ways: [`unenrol`](/workflows/flex-lite/api-reference/unenrol) and [`offboard`](/workflows/flex-lite/api-reference/offboard)

In most cases, **unenrol** is the best way for a user to opt-out, and should be the default for a user-initiated opt-out action. It cleanly stops participation — no more readings, scheduling, or rewards — while leaving the site and its assets in place. Because the user remains on the platform, their [payments](/workflows/payments/overview) remain accessible, and you can switch participation back on at any time by re-enrolling the same site.

<Note>
  This is especially relevant when a site is participating in another proposition, like the **Capacity Market**. Unenrol only stops the proposition you name, so unenrolling Flex Lite leaves their Capacity Market participation untouched.
</Note>

**Offboard** is the heavy option, for when the user is gone for good: they've moved out, or your support team is removing them. It removes the site and its assets entirely, ends every proposition, and cuts off the user's access — including the payments portal.

|                                               | Unenrol    | Offboard |
| --------------------------------------------- | ---------- | -------- |
| Participation (scheduling, readings, rewards) | Stopped    | Stopped  |
| Other propositions (CM, etc.)                 | Unchanged  | Stopped  |
| Site & assets                                 | Accessible | Removed  |
| Payments                                      | Accessible | Cut off  |

<Tip>
  Always prompt users to withdraw their outstanding balance before you offboard them — once a site is offboarded, the user can no longer reach the payments portal.
</Tip>

## Managing assets within a site

The lifecycle above acts on the **site**. But a site can gain or lose assets without changing state — a user might add a battery to a property that already has a charger, or replace a charger that's been swapped out.

These are asset-level operations that leave the site enrolled and untouched:

<CardGroup cols={2}>
  <Card title="Create asset" icon="plus" href="/api-reference/entities/asset/post">
    Add an asset to an existing site
  </Card>

  <Card title="Delete asset" icon="trash" href="/api-reference/entities/asset/delete">
    Remove a single asset from a site
  </Card>
</CardGroup>

## Common scenarios

<AccordionGroup>
  <Accordion title="A user adds an asset (e.g. they install a second charger)" icon="plus">
    Use [Create asset](/api-reference/entities/asset/post) against the existing `site_id`. The site stays enrolled, and the new asset starts participating once it's eligible. There's no need to re-onboard or re-enrol the site.

    Save the returned `asset_id` — you'll need it to send events for that asset.
  </Accordion>

  <Accordion title="A user removes an asset (e.g. they sell their EV)" icon="minus">
    Use [Delete asset](/api-reference/entities/asset/delete) with the `asset_id`. The rest of the site is unaffected.

    If the user is removing their *only* asset and won't be participating any more, consider whether you want to [unenrol](/workflows/flex-lite/api-reference/unenrol) the site instead — or [offboard](/workflows/flex-lite/api-reference/offboard) it if they're leaving for good. See [opting out](#opting-out) for which to reach for.
  </Accordion>

  <Accordion title="A user replaces or upgrades an asset (e.g. they swap out their charger)" icon="arrows-rotate">
    Treat it as a create followed by a delete: [Create](/api-reference/entities/asset/post) the replacement asset first, then [Delete](/api-reference/entities/asset/delete) the old one. Use a fresh `external_id` for the new asset so your records line up with ours.

    The site stays enrolled throughout, so there's no gap in participation for its other assets.
  </Accordion>

  <Accordion title="A user updates their email" icon="envelope">
    Update the email against the existing `site_id` with the [site `PATCH` endpoint](/api-reference/entities/site/update). Their site, assets, consents and payments all stay intact.
  </Accordion>

  <Accordion title="A user opts out" icon="pause">
    See [Opting out](#opting-out) for the full guidance on choosing between unenrolling and offboarding a site, and on handling any outstanding payment balance.
  </Accordion>

  <Accordion title="A user wants to come back after opting out" icon="rotate-left">
    If you unenrolled the site, it's sitting in the **Inactive** state — the site and assets still exist. Call [enrol](/workflows/flex-lite/api-reference/enrol) with the existing `site_id` to bring it back to **Active**. No need to onboard again.

    If you offboarded instead, the site was deleted, so you'll need to [onboard](/workflows/flex-lite/api-reference/onboard) the user again.
  </Accordion>

  <Accordion title="A user moves house" icon="truck">
    A site is tied to a physical property (and its MPAN), so a move is really two separate users at two properties:

    1. **Offboard the old site.** The user no longer controls the assets at their previous address, so [offboard](/workflows/flex-lite/api-reference/offboard) it.

    <Tip>
      Always prompt users to withdraw their outstanding balance before you offboard them — once a site is offboarded, the user can no longer reach the payments portal.
    </Tip>

    2. **Onboard them at the new property** as a fresh site, if they're taking eligible assets with them or the new home already has them.
  </Accordion>

  <Accordion title="Someone moves into a property that was previously enrolled" icon="house">
    The previous occupant should have been [offboarded](/workflows/flex-lite/api-reference/offboard) when they left. The new occupant is a different user, so [onboard](/workflows/flex-lite/api-reference/onboard) them as a new site against the same MPAN. Don't re-use the old site — its consents and payments belong to the previous user, and it stays linked to their account.
  </Accordion>
</AccordionGroup>

## Where next?

<CardGroup cols={2}>
  <Card title="Flex Lite" icon="pause" href="/workflows/flex-lite/overview">
    Insert pauses into existing charging schedules with a light integration
  </Card>

  <Card title="Smart Charging" icon="bolt" href="/workflows/smart-charging/overview">
    Hand full charge-plan control to Axle for maximum flexibility revenue
  </Card>

  <Card title="Advanced Onboarding" icon="sliders" href="/workflows/flex-lite/advanced-integration">
    Split onboarding into initialise + enrol
  </Card>

  <Card title="API Reference" icon="server" href="/api-reference/entities/site/onboard">
    Full request and response specs for every endpoint
  </Card>
</CardGroup>