CLclevergy
Invoices

Create a new invoice

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

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.

post/contracts/{contractId}/invoices

Request

  • Base URL
    https://connect.clever.gy
  • Auth
    API key in header clevergy-api-key

Path parameters

contractIdstring required

ID of the contract for which to create the invoice

Request body

issueDatestring date-time required

Date when the invoice was issued

invoicePeriodFromstring date-time required

Start of the invoice period

invoicePeriodTostring date-time required

End of the invoice period

type'ELECTRICITY' | 'GAS' | 'WATER' | 'OTHER' required

Type of the contract

costnumber double required

Total cost of the invoice

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

obtainMethod'REAL' | 'ESTIMATED' required

Method in which the invoice is obtained

totalEnergyConsumptionnumber double

Total energy consumption recorded in the invoice in kWh

Example request

{
  "issueDate": "2023-01-15T12:00:00Z",
  "invoicePeriodFrom": "2023-01-01T00:00:00Z",
  "invoicePeriodTo": "2023-01-31T23:59:59Z",
  "type": "ELECTRICITY",
  "cost": 125.5,
  "externalId": "ext-456",
  "concepts": {
    "energyCost": 75.2,
    "powerCost": 35,
    "otherCost": 15.3,
    "totalEnergySurplus": 10.5,
    "surplusSaving": 5,
    "discountSaving": 20,
    "virtualWallet": 15,
    "excessPowerCost": 10,
    "reactiveEnergyCost": 8
  },
  "obtainMethod": "REAL",
  "totalEnergyConsumption": 350.75
}

Response

Invoice created successfully

idstring required

Unique identifier of the invoice

issueDatestring date required

Date when the invoice was issued

invoicePeriodFromstring date required

Start of the invoice period

invoicePeriodTostring date required

End of the invoice period

type'ELECTRICITY' | 'GAS' | 'WATER' | 'OTHER' required

Type of the contract

costnumber double required

Total cost of the invoice

contractIdstring required

ID of the contract associated with this invoice

externalIdstring

External identifier for the invoice, used for integration with third-party systems. Unique per Clevergy user; may be reused across different users.

conceptsobject

Additional invoice concepts as key-value pairs

fileUrlstring 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

totalEnergyConsumptionnumber double

Total energy consumption recorded in the invoice in kWh

paymentDatestring date

Date when the invoice was paid

paymentStatus'PENDING' | 'PAID' | 'OVERDUE'

Payment status of the invoice

Example response

{
  "id": "invoice-123",
  "issueDate": "2023-01-15",
  "invoicePeriodFrom": "2023-01-01",
  "invoicePeriodTo": "2023-01-31",
  "type": "ELECTRICITY",
  "cost": 125.5,
  "contractId": "contract-123",
  "externalId": "ext-456",
  "concepts": {
    "energy": "75.20",
    "taxes": "15.30",
    "fixed": "35.00"
  },
  "fileUrl": "https://example.com/invoices/detail/123",
  "obtainMethod": "REAL",
  "totalEnergyConsumption": 350.75,
  "paymentDate": "2023-02-01",
  "paymentStatus": "PAID"
}

Changes

No recorded changes to this operation across all 1 revision of this API.