> ## Documentation Index > Fetch the complete documentation index at: https://chargecloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Contracts / Update > Updates metadata of an existing contract (addresses, external IDs, payment method, attributes, auth flags); lifecycle status changes must use the cancel endpoint instead. Required permission: crm:contracts:update. Available contexts: API Key. ## OpenAPI ````yaml /api/core-api/crmiapi.json put /api/v1/crm/contracts/{uuid} openapi: 3.2.0 info: title: chargecloud - Core API summary: chargecloud Core API. All around CRM, Asset Management and more. version: 1.141.0 description: chargecloud Core API. All around CRM, Asset Management and more. servers: - url: https://api.chargecloud.dev description: Production - chargecloud Core API - url: https://demo.chargecloud.de description: Sandbox/Dev - chargecloud Core API security: [] paths: /api/v1/crm/contracts/{uuid}: put: tags: - Contracts summary: Contracts / Update description: >- Updates metadata of an existing contract (addresses, external IDs, payment method, attributes, auth flags); lifecycle status changes must use the cancel endpoint instead. Required permission: crm:contracts:update. Available contexts: API Key. operationId: /api/v1/crm/contracts/{uuid}_PUT parameters: - name: uuid in: path description: Globally unique identifier of the contract to update. required: true schema: type: string maxLength: 36 description: Globally unique identifier of the contract to update. - name: Accept-Language in: header description: BCP 47 language tag for content negotiation (e.g. en, de-DE). required: false schema: type: string description: BCP 47 language tag for content negotiation (e.g. en, de-DE). example: en requestBody: description: >- Updates metadata of an existing contract (addresses, external IDs, payment method, attributes, auth flags); lifecycle status changes must use the cancel endpoint instead. Required permission: crm:contracts:update. Available contexts: API Key. content: application/json: schema: type: object properties: ext_contract_id: type: string maxLength: 50 description: >- Contract identifier as known by an external CRM. This is the primary field used to match ChargeCloud contracts to records in upstream systems (EDI feeds, partner integrations, migrations). Max 50 chars. external_id: type: string maxLength: 15 description: >- Contract-level external identifier (max 15 chars). Use ext_contract_id for longer references. customer_group_id: type: integer format: int32 description: >- Customer group the customer is assigned to (pricing tier or reporting cohort). Resolved via the customer's group association; not stored on the contract itself. campaign_id: type: integer format: int32 description: >- Optional reference to the acquisition or sales campaign linked to this contract. company_name: type: string maxLength: 255 description: >- Registered company name. Required for business customers (business = true). salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the contract holder. Codes: 1 Mr, 2 Mrs, 3 Family, 4 Mr and Mrs, 5 Mrs and Mrs, 6 Mr and Mr, 7 married couple, 8 Company, 9 none, 10 diverse; 0 is the unset placeholder. New private/business registrations only accept 1, 2, 3 and 8. firstname: type: string maxLength: 70 description: >- First name of the contract holder. Required for private customers. surname: type: string maxLength: 70 description: >- Surname (last name) of the contract holder. Required for private customers. street: type: string maxLength: 255 description: Street name of the contract holder's primary address. house_number: type: string maxLength: 16 description: >- House number of the primary address; may contain letters or suffixes (e.g., "12a"). zip: type: string maxLength: 16 description: >- Postal code of the contract holder's primary address. Length and format are validated against `country_id` — invalid combinations are rejected. city: type: string maxLength: 128 description: City of the primary address. country_id: type: integer format: int32 description: Internal country identifier of the primary address. phone: type: string maxLength: 255 description: >- Aggregated contract-level phone number; detailed numbers live on phone_home, phone_mobile, phone_business. email: type: string maxLength: 255 description: >- Aggregated contract-level email; distinct from email_private and email_business on the customer version. reference_field_1: type: string maxLength: 255 description: >- Free-text client-configurable reference. Common use cases include TecDoc identifiers, HC (Hauptkunde) numbers, cost centres, purchase-order numbers, and project IDs. No semantic enforcement by the system. reference_field_2: type: string maxLength: 255 description: >- Second free-text client-configurable reference, parallel to reference_field_1. Same use cases (TecDoc, HC, cost centres, etc.) — provided as a second slot when one reference is not enough. billing_company: type: string maxLength: 255 description: >- Company name used on invoices when the billing recipient differs from the contract holder. billing_salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the billing recipient. Same codes and meanings as salutation (0-10). billing_title: type: string maxLength: 70 description: >- Academic or honorific title of the billing recipient (Dr., Prof., etc.). billing_firstname: type: string maxLength: 70 description: >- First name of the billing recipient when different from the contract holder. billing_surname: type: string maxLength: 70 description: >- Surname of the billing recipient when different from the contract holder. billing_street: type: string maxLength: 255 description: >- Street name of the billing address when different from the contract address. billing_house_number: type: string maxLength: 16 description: >- House number of the billing address; may contain letters or suffixes (e.g., "12a"). billing_zip: type: string maxLength: 16 description: Postal code of the billing address. billing_city: type: string maxLength: 128 description: City of the billing address. billing_country_id: type: integer format: int32 description: >- Internal country identifier of the billing address. Defaults to country_id when omitted on create. billing_email: type: string maxLength: 128 description: >- Email address to which invoices and billing correspondence are sent. billing_phone: type: string maxLength: 128 description: Phone number of the billing recipient. disabled: type: boolean default: false description: >- True when the contract has been deactivated by an operator; excluded from charging and billing until re-enabled. auth_enabled: type: boolean default: false description: >- True when the contract holder may log into the ChargeCloud customer app. auth_username: type: string maxLength: 255 description: >- Username for the ChargeCloud customer-app login; must be unique per client. is_employer: type: boolean default: false description: >- True when this emobility contract is managed by an employer on behalf of employees; unlocks employee-reimbursement features. payment_method_id: type: integer format: int32 description: >- Payment method used to bill this contract (SEPA mandate, credit card, etc.). attributes: type: string description: >- JSON-encoded map of contract attributes (e.g. `{"attribute_key":"value", ...}`). Keys and value types are configured per client — see the Attributes API for the available set. Unknown keys are rejected; optional attributes fall back to their configured default when omitted. required: true responses: '200': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - contract properties: contract: type: object properties: uuid: type: string maxLength: 36 description: Globally unique identifier of the contract. type: type: string enum: - energy - energy_external - energy_external_lima - emobility - emobility_adhoc - non_commodity description: >- Contract category. Allowed values: energy (electricity or gas supply); energy_external (external energy supplier, SHELL-imported); energy_external_lima (external contract from LIMA); emobility (EV charging with recurring billing); emobility_adhoc (one-off EV charging, no recurring contract); non_commodity (EV charging services without energy commodity). created_at: type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$ description: Timestamp when the contract record was created. ordered_at: type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$ description: >- Timestamp when the customer ordered the contract; may differ from created_at when the order predates data entry. status: type: string enum: - open - cancellation_previous - delivery_net - waiting - active - blocked - terminated - expired - done - cancelled description: >- Contract lifecycle status. Allowed values: open (created, not yet started); cancellation_previous (cancellation sent to previous provider, energy only); delivery_net (registered with distribution network operator, energy only); waiting (approved, awaiting delivery start); active (delivery in progress); blocked (frozen, no state changes); terminated (cancelled, end date set); expired (end date passed); cancelled (annulled before becoming active); done (completed). Not every value applies to every contract type. modification_date: type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$ description: >- Timestamp of the last modification to the contract record. blocked: type: boolean default: false description: >- True when the contract is blocked and cannot transition to new states. disabled: type: boolean default: false description: >- True when the contract has been deactivated by an operator; excluded from charging and billing until re-enabled. billing_blocked: type: boolean default: false description: >- True when automatic billing is currently suspended for this contract. dunning_locked: type: boolean default: false description: >- True when dunning (collection) processes are paused for this contract. ext_contract_id: type: string maxLength: 50 description: >- Contract identifier as known by an external CRM. This is the primary field used to match ChargeCloud contracts to records in upstream systems (EDI feeds, partner integrations, migrations). Max 50 chars. external_id: type: string maxLength: 15 description: >- Contract-level external identifier (max 15 chars). Use ext_contract_id for longer references. customer_group_id: type: integer format: int32 description: >- Customer group the customer is assigned to (pricing tier or reporting cohort). Resolved via the customer's group association; not stored on the contract itself. account_id: type: integer format: int32 description: >- Reference to the financial ledger (accounts) tracking debits, credits, invoices, and payments. Every contract has exactly one account. business: type: boolean default: false description: >- True for B2B customers, false for private individuals. Drives required fields (company_name, VAT/tax code) and lifecycle rules. company_name: type: string maxLength: 255 description: >- Registered company name. Required for business customers (business = true). salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the contract holder. Codes: 1 Mr, 2 Mrs, 3 Family, 4 Mr and Mrs, 5 Mrs and Mrs, 6 Mr and Mr, 7 married couple, 8 Company, 9 none, 10 diverse; 0 is the unset placeholder. New private/business registrations only accept 1, 2, 3 and 8. firstname: type: string maxLength: 70 description: >- First name of the contract holder. Required for private customers. surname: type: string maxLength: 70 description: >- Surname (last name) of the contract holder. Required for private customers. street: type: string maxLength: 255 description: Street name of the contract holder's primary address. house_number: type: string maxLength: 16 description: >- House number of the primary address; may contain letters or suffixes (e.g., "12a"). zip: type: string maxLength: 16 description: >- Postal code of the contract holder's primary address. Length and format are validated against `country_id` — invalid combinations are rejected. city: type: string maxLength: 128 description: City of the primary address. country_id: type: integer format: int32 description: Internal country identifier of the primary address. phone: type: string maxLength: 255 description: >- Aggregated contract-level phone number; detailed numbers live on phone_home, phone_mobile, phone_business. email: type: string maxLength: 255 description: >- Aggregated contract-level email; distinct from email_private and email_business on the customer version. reference_field_1: type: string maxLength: 255 description: >- Free-text client-configurable reference. Common use cases include TecDoc identifiers, HC (Hauptkunde) numbers, cost centres, purchase-order numbers, and project IDs. No semantic enforcement by the system. reference_field_2: type: string maxLength: 255 description: >- Second free-text client-configurable reference, parallel to reference_field_1. Same use cases (TecDoc, HC, cost centres, etc.) — provided as a second slot when one reference is not enough. billing_company: type: string maxLength: 255 description: >- Company name used on invoices when the billing recipient differs from the contract holder. billing_salutation: type: string enum: - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' description: >- Salutation code for the billing recipient. Same codes and meanings as salutation (0-10). billing_title: type: string maxLength: 70 description: >- Academic or honorific title of the billing recipient (Dr., Prof., etc.). billing_firstname: type: string maxLength: 70 description: >- First name of the billing recipient when different from the contract holder. billing_surname: type: string maxLength: 70 description: >- Surname of the billing recipient when different from the contract holder. billing_street: type: string maxLength: 255 description: >- Street name of the billing address when different from the contract address. billing_house_number: type: string maxLength: 16 description: >- House number of the billing address; may contain letters or suffixes (e.g., "12a"). billing_zip: type: string maxLength: 16 description: Postal code of the billing address. billing_city: type: string maxLength: 128 description: City of the billing address. billing_country_id: type: integer format: int32 description: >- Internal country identifier of the billing address. Defaults to country_id when omitted on create. billing_email: type: string maxLength: 128 description: >- Email address to which invoices and billing correspondence are sent. billing_phone: type: string maxLength: 128 description: Phone number of the billing recipient. title: type: string maxLength: 50 description: >- Academic or honorific title prepended to the contract holder's name (Dr., Prof., etc.). tax_code: type: string maxLength: 50 description: >- National tax code (e.g., Italian codice fiscale); alternative to vat_identification_number. Required for B2B contracts when no VAT number is supplied. external_customer_id: type: string maxLength: 15 description: >- Caller-supplied identifier used to link the customer to an external CRM record. Validation rules can differ per customer group (regex / prefix), so the same value may be accepted for one customer group and rejected for another. Max 15 chars. auth_enabled: type: boolean default: false description: >- True when the contract holder may log into the ChargeCloud customer app. auth_username: type: string maxLength: 255 description: >- Username for the ChargeCloud customer-app login; must be unique per client. phone_home: type: string maxLength: 50 description: >- Home phone number of the contract holder, without country or area prefix. phone_home_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_home. phone_mobile: type: string maxLength: 50 description: >- Mobile phone number of the contract holder, without country or area prefix. phone_mobile_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_mobile. phone_business: type: string maxLength: 50 description: >- Business/work phone number of the contract holder, without country or area prefix. phone_business_area_code: type: string maxLength: 10 description: Country or area dialing prefix for phone_business. email_private: type: string maxLength: 255 description: >- Private email address of the contract holder (customer-version field). email_business: type: string maxLength: 255 description: >- Business email address of the contract holder (customer-version field). advertising_agreement_mail: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via postal mail. advertising_agreement_phone: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via phone. advertising_agreement_email: type: boolean default: false description: >- Customer consent flag for receiving marketing communication via email. required: - uuid - type - blocked - disabled - billing_blocked - dunning_locked - account_id - business - salutation - firstname - surname - street - house_number - zip - city - phone - email - billing_salutation - billing_firstname - billing_surname - billing_street - billing_house_number - billing_zip - billing_city - billing_email - billing_phone description: >- The contract record. Collections carry the list projection, single-contract responses the full view projection. description: >- The contract after the edit was applied, carrying the updated field values. '401': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Unauthorized '403': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Forbidden '404': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Not found '405': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - error properties: error: type: string description: Error message description: Method not allowed '422': headers: Content-Language: description: The locale of the response content (BCP 47 language tag). required: false schema: type: string example: en content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: errorKey: type: string description: A key identifying the error message: type: string description: The error message parameter: type: string description: The parameter that caused the error, if any required: - errorKey - message - parameter description: Error description: List of errors description: Request validation failed security: - bearer: - crm:contracts components: securitySchemes: bearer: type: http description: OAuth2 Bearer Authorization scheme: bearer bearerFormat: JWT ```` ## Related topics - [Contract management](https://chargecloud.dev/contract-management.md) - [Locations / Update](https://chargecloud.dev/api-reference/locations/locations-update.md) - [Contracts / Read](https://chargecloud.dev/api-reference/contracts/contracts-read.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.