Contract management - chargecloud Developer Hub

Register, update, and cancel contracts via the 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 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.

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.

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.

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.

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

1 · Authenticate

POST /api/v1/oauth/token
Content-Type: application/json

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

2 · Register customer & contract

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"
}

201 Created

{
  "contract": {
    "uuid": "c1a2b3c4-...",
    "type": "emobility",
    "status": "active"
  },
  "customer_id": 9876,
  "external_customer_id": "CUST-9876",
  "mail_verification_needed": false,
  "contract_confirmation_needed": false
}

3 · Verify contract

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.

​Customer and contract model

​Contract registration flow

​Additional use cases

Customer and contract model

Contract registration flow

Additional use cases