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

# Contract management

> Register, update, and cancel customer contracts via the CRM API.

Register, update, and cancel contracts via the [**Core API**](/api/core-api). The CRM endpoints of the Core API give E-Mobility Providers (EMPs) and Charge Point Operators (CPOs) programmatic control over customer and contract registration in the chargecloud OS. A new customer and their contract are registered in a single call, keeping your CRM or app as the leading system while the chargecloud OS stays in sync automatically.

All CRM endpoints require the Core API access token, see the [Authentication](/authentication) page.

***

## Customer and contract model

A customer in the chargecloud OS represents either an EV driver or a business, e.g. employer or location partner. To enable the billing of charging sessions or services, a contract is assigned to the customer. The type of contract determines the business context: e-mobility contract for end customers (B2C) and non-commodity contract for businesses (B2B). Customer and contract are always registered together in a single API call, there is no separate customer endpoint.

<Steps>
  <Step title="Customer (inline)">
    EV driver or business (employee, location partner). Defined by salutation, name, billing address, and the `business` flag (`false` for B2C, `true` for B2B). Sent inline in the `POST /api/v1/crm/contracts` body, there is no separate customer endpoint.

    Identified by `customer_id` and `external_customer_id` in the response.
  </Step>

  <Step title="Contract">
    Determines the business context (e-mobility or non-commodity) and enables billing of services and charging sessions. Identified by `contract.uuid`, which is the handle for every follow-up call (GET, update, cancel, deletion-request).

    Returns `contract.uuid` and `customer_id`.
  </Step>
</Steps>

<Note>
  The read and update endpoints are keyed by the contract `uuid` (`/crm/contracts/{uuid}`), while
  the `cancel` and `deletion-request` endpoints are keyed by the contract id (`/crm/contracts/{id}
      /…`). Use the identifier shown in each example below.
</Note>

***

## Contract registration flow

Authenticate once against the **chargecloud IDP** to obtain a Bearer token, then register the customer and their contract in a single `POST`. Verify the contract with a `GET` to confirm its status before the customer starts using the service. For authentication details, see the [Authentication](/authentication) page.

```http title="1 · Authenticate" theme={null}
POST /api/v1/oauth/token
Content-Type: application/json

{ "username": "...", "password": "...", "tenant": "..." }
```

```http title="2 · Register customer & contract" theme={null}
POST /api/v1/crm/contracts
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "salutation":    "mr",
  "firstname":     "Max",
  "surname":       "Mustermann",
  "email_private": "max@example.com",
  "street":        "Musterstrasse",
  "house_number":  "1",
  "zip":           "50667",
  "city":          "Koeln",
  "country_id":    1,
  "business":      false,
  "ext_contract_id": "CRM-00123",
  "start_date":    "2026-07-09"
}
```

```json title="201 Created" theme={null}
{
  "contract": {
    "uuid": "c1a2b3c4-...",
    "type": "emobility",
    "status": "active"
  },
  "customer_id": 9876,
  "external_customer_id": "CUST-9876",
  "mail_verification_needed": false,
  "contract_confirmation_needed": false
}
```

```http title="3 · Verify contract" theme={null}
GET /api/v1/crm/contracts/{uuid}
Authorization: Bearer <access_token>
```

***

## Additional use cases

* **Add a contract for an existing customer:** Send `external_customer_id` in the `POST` body to link the new contract to an existing customer record instead of creating a new customer.
* **B2B contracts:** Set `business: true` for an employer or service partner. Employer/employee relationships are managed on the contract via `is_employer` (available on update, `PUT /api/v1/crm/contracts/{uuid}`).
* **Update a contract:** Change billing address, customer group, or contact details via `PUT /api/v1/crm/contracts/{uuid}`.
* **Cancel a contract:** End an active contract via `POST /api/v1/crm/contracts/{id}/cancel`. The contract record is preserved for billing reconciliation.
* **Request deletion of a contract:** Initiate a GDPR deletion request via `POST /api/v1/crm/contracts/{id}/deletion-request`.


## Related topics

- [Asset management](/asset-management.md)
- [Retrieves contracts](/api-reference/contracts/retrieves-contracts.md)
- [Creates a contract](/api-reference/contracts/creates-a-contract.md)