---
title: "Create a new invoice"
method: POST
path: "/contracts/{contractId}/invoices"
tags: ["Invoices"]
---

# Create a new invoice

`POST /contracts/{contractId}/invoices`

## Request

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

Creates a new invoice with the provided details. This endpoint provides a signed URL for uploading a PDF invoice.

:::tip
**Recommended guide**
If you are unsure which parameters to include when creating a gas or electricity invoice, refer to the [complete documentation](https://docs.clever.gy/developer/how-to-set-up/invoices).
:::

### Steps and considerations
1. POST invoice metadata to obtain the upload URL (`fileUrl` field).
2. PUT the PDF file to the returned URL (valid for 15 minutes).

> **Important:** After creating the invoice, the PDF must be uploaded to the `fileUrl` returned in the response. If the PDF is not uploaded, the invoice will not be processed and will not be available to the customer.

## Path parameters

- `contractId` 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 created 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

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Contract 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)