---
title: "Update an invoice"
method: PUT
path: "/contracts/{contractId}/invoices/{id}"
tags: ["Invoices"]
---

# Update an invoice

`PUT /contracts/{contractId}/invoices/{id}`

## Request

- Base URL: `https://connect.clever.gy`
- URL: `https://connect.clever.gy/contracts/{contractId}/invoices/{id}`
- Auth: API key in header `clevergy-api-key`

Updates the details of a specific invoice by its ID

## Path parameters

- `contractId` string, required
- `id` string, required

## Request body

- CreateOrUpdateInvoiceRequest: Request to create a new invoice
  - `issueDate` string, date-time, required: Date when the invoice was issued
  - `invoicePeriodFrom` string, date-time, required: Start of the invoice period
  - `invoicePeriodTo` string, date-time, required: End of the invoice period
  - `type` 'ELECTRICITY' | 'GAS' | 'WATER' | 'OTHER', required: Type of the contract
  - `cost` number, double, required: Total cost of the invoice
  - `externalId` string, required: External identifier for the invoice, used for integration with third-party systems. Must be unique per Clevergy user (cannot be reused across that user's contracts); may be reused for different users.
  - `concepts` object: Additional invoice concepts as key-value pairs
    - `energyCost` number, double: Cost of energy consumption in the invoice
    - `powerCost` number, double: Cost of power in the invoice
    - `otherCost` number, double: Cost of other concepts in the invoice (e.g., taxes, fees)
    - `totalEnergySurplus` number, double: Total energy surplus in the invoice in kWh
    - `surplusSaving` number, double: Savings from energy surplus in the invoice
    - `discountSaving` number, double: Savings from discounts applied in the invoice
    - `virtualWallet` number, double: Amount credited to the virtual wallet from the invoice. This can be positive (credit) or negative (debit)
    - `excessPowerCost` number, double: Cost of excess power consumption in the invoice
    - `reactiveEnergyCost` number, double: Cost of reactive energy consumption in the invoice
  - `obtainMethod` 'REAL' | 'ESTIMATED', required: Method in which the invoice is obtained
  - `totalEnergyConsumption` number, double: Total energy consumption recorded in the invoice in kWh

## Response `200`

Invoice updated successfully

- Invoice: Invoice information
  - `id` string, required: Unique identifier of the invoice
  - `issueDate` string, date, required: Date when the invoice was issued
  - `invoicePeriodFrom` string, date, required: Start of the invoice period
  - `invoicePeriodTo` string, date, required: End of the invoice period
  - `type` 'ELECTRICITY' | 'GAS' | 'WATER' | 'OTHER', required: Type of the contract
  - `cost` number, double, required: Total cost of the invoice
  - `contractId` string, required: ID of the contract associated with this invoice
  - `externalId` string: External identifier for the invoice, used for integration with third-party systems. Unique per Clevergy user; may be reused across different users.
  - `concepts` object: Additional invoice concepts as key-value pairs
  - `fileUrl` string, nullable: Signed URL to access the invoice PDF when available. Null when no file has been uploaded for this invoice.
  - `obtainMethod` 'REAL' | 'ESTIMATED': Method in which the invoice is obtained
  - `totalEnergyConsumption` number, double: Total energy consumption recorded in the invoice in kWh
  - `paymentDate` string, date: Date when the invoice was paid
  - `paymentStatus` 'PENDING' | 'PAID' | 'OVERDUE': Payment status of the invoice

## Other responses

- `401`: Unauthorized
- `404`: Invoice not found
- `409`: Invoice already exists for this user with the same external id (including on another contract of the same user)
- `default`: Unexpected error

---

[API](https://skmtc.dev/clevergy/apis/clevergy-connect-api.md) - [All operations](https://skmtc.dev/clevergy/apis/clevergy-connect-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clevergy/apis/clevergy-connect-api/revisions/d333c5eecb5b?raw)