> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices

> Manage energy invoices — electricity, gas, water, and other utility records for facilities

<Note>
  **Early Access** - The Dcycle CLI is currently available for enterprise customers.
  [Contact us](/docs/support) to learn more about access.
</Note>

## Overview

The `invoice` command manages energy and utility invoice records attached to facilities. Invoices are the primary data source for Scope 1 and Scope 2 emissions calculations.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice <subcommand> [flags]
```

### Available Commands

| Command              | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `list`               | List invoices for a facility                         |
| `show`               | Show invoice details                                 |
| `download`           | Download the invoice file                            |
| `edit`               | Edit invoice metadata                                |
| `delete`             | Delete an invoice                                    |
| `bulk-delete`        | Delete multiple invoices at once                     |
| `migrate`            | Move invoices to another facility                    |
| `recalculate`        | Recalculate invoice emissions (one-by-one via PATCH) |
| `recalculate-v2`     | Batch recalculate via activity categories            |
| `recalculate-legacy` | Batch recalculate via legacy endpoint                |

### Invoice Types

| Type                    | Typical Unit | GHG Scope |
| ----------------------- | ------------ | --------- |
| `electricity`           | kWh          | Scope 2   |
| `heat`                  | kWh          | Scope 1/2 |
| `water`                 | m³           | Scope 3   |
| `recharge`              | kWh          | Scope 2   |
| `process`               | varies       | Scope 1   |
| `waste_water_treatment` | m³           | Scope 3   |

***

## List Invoices

List invoices for a specific facility. Requires `--facility`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice list --facility <facility-id>

# Aliases
dcy invoice ls --facility <facility-id>
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List all invoices for a facility
dcy invoice list --facility <facility-id>

# Filter by type and year
dcy invoice list --facility <facility-id> --type electricity --year 2024

# Filter by status
dcy invoice list --facility <facility-id> --status active

# Increase page size
dcy invoice list --facility <facility-id> --size 200

# JSON output for scripting
dcy invoice list --facility <facility-id> --format json
```

### Flags

| Flag         | Short | Required | Default | Description              |
| ------------ | ----- | -------- | ------- | ------------------------ |
| `--facility` | `-f`  | Yes      | —       | Facility ID              |
| `--type`     | `-t`  | No       | —       | Filter by invoice type   |
| `--year`     | —     | No       | —       | Filter by year           |
| `--size`     | —     | No       | `50`    | Page size                |
| `--org`      | —     | No       | —       | Organization ID override |

### Output

```
Showing 3 invoices for facility abc12345-...
def67890-... | electricity | 2024-01-01 → 2024-01-31 | 1500.00 | 0.45 | active
ghi11223-... | heat        | 2024-01-01 → 2024-01-31 |  800.00 | 0.32 | active
jkl44556-... | water       | 2024-01-01 → 2024-01-31 |   45.00 | 0.01 | active
```

Columns: ID, type, period, quantity, CO2e (tCO2e), status.

***

## Show Invoice

Display detailed information about a single invoice.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice show <invoice-id>
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice show 00000000-0000-0000-0000-000000000000

# JSON output
dcy invoice show <invoice-id> --format json
```

### Flags

| Flag    | Description              |
| ------- | ------------------------ |
| `--org` | Organization ID override |

### Output Fields

ID, invoice number, type, status, period, quantity, base quantity, unit ID, CO2e, CO2e biomass, CUPS code, file URL, uploaded by, and facility distribution percentages.

***

## Download Invoice

Download the file attached to an invoice (PDF, image, etc.).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice download <invoice-id>
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Download to current directory
dcy invoice download <invoice-id>

# Download to specific path
dcy invoice download <invoice-id> --output ./invoices/

# Overwrite existing file
dcy invoice download <invoice-id> --output invoice.pdf --overwrite
```

### Flags

| Flag          | Short | Default | Description                             |
| ------------- | ----- | ------- | --------------------------------------- |
| `--output`    | `-o`  | —       | Output file path or directory           |
| `--overwrite` | —     | `false` | Overwrite destination file if it exists |
| `--org`       | —     | —       | Organization ID override                |

***

## Edit Invoice

Edit metadata on one or more invoices. Supports multiple invoice IDs in a single command.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice edit <invoice-id> [<invoice-id>...] [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Enable/disable
dcy invoice edit <invoice-id> --enabled
dcy invoice edit <invoice-id> --disabled

# Change status
dcy invoice edit <invoice-id> --status completed

# Update multiple invoices at once
dcy invoice edit <id1> <id2> <id3> --status completed --yes

# Change supplier
dcy invoice edit <invoice-id> --supplier-id <supplier-uuid>

# Trigger recalculation by changing fuel or unit
dcy invoice edit <invoice-id> --facility-fuel-id <fuel-uuid> --yes
dcy invoice edit <invoice-id> --base-quantity 1500 --unit-id <unit-uuid> --yes
```

### Flags

| Flag                 | Short | Description                                                        |
| -------------------- | ----- | ------------------------------------------------------------------ |
| `--status`           | `-s`  | Set invoice status                                                 |
| `--enabled`          | —     | Enable the invoice                                                 |
| `--disabled`         | —     | Disable the invoice                                                |
| `--supplier-id`      | —     | Set supplier ID                                                    |
| `--facility-fuel-id` | —     | Set facility fuel ID (uses PUT, triggers recalculation)            |
| `--unit-id`          | —     | Set unit ID (uses PUT, triggers recalculation)                     |
| `--base-quantity`    | —     | Set base quantity / consumption (uses PUT, triggers recalculation) |
| `--yes`              | `-y`  | Skip confirmation prompt                                           |
| `--org`              | —     | Organization ID override                                           |

<Warning>
  `--facility-fuel-id`, `--unit-id`, and `--base-quantity` use PUT instead of PATCH, which triggers full invoice recalculation. The `--enabled` and `--disabled` flags are mutually exclusive.
</Warning>

***

## Delete Invoice

Delete a single invoice by ID.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice delete <invoice-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# With confirmation prompt
dcy invoice delete <invoice-id>

# Skip confirmation
dcy invoice delete <invoice-id> --yes
```

### Flags

| Flag    | Short | Default | Description              |
| ------- | ----- | ------- | ------------------------ |
| `--yes` | `-y`  | `false` | Skip confirmation prompt |
| `--org` | —     | —       | Organization ID override |

***

## Bulk Delete

Delete multiple invoices at once, either from a CSV file or by listing IDs directly.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice bulk-delete [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# From CSV file (columns: id, facility_id, optionally type)
dcy invoice bulk-delete --file invoices.csv --yes

# By IDs (requires --facility and --type)
dcy invoice bulk-delete --ids "id1,id2,id3" --facility <facility-id> --type electricity --yes
```

### Flags

| Flag         | Short | Default | Description                                                                  |
| ------------ | ----- | ------- | ---------------------------------------------------------------------------- |
| `--file`     | —     | —       | CSV file with columns: `id`, `facility_id` (optional: `type`)                |
| `--ids`      | —     | —       | Invoice IDs, comma or newline separated (requires `--facility` and `--type`) |
| `--facility` | —     | —       | Facility ID (used with `--ids`)                                              |
| `--type`     | —     | —       | Invoice type (used with `--ids`)                                             |
| `--yes`      | `-y`  | `false` | Skip confirmation prompt                                                     |
| `--org`      | —     | —       | Organization ID override                                                     |

***

## Migrate

Move invoices from one facility to another using a CSV file with invoice IDs.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice migrate --file <csv-path> --to-facility <facility-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Preview what would be migrated
dcy invoice migrate --file invoices.csv --to-facility <facility-id> --dry-run

# Execute migration
dcy invoice migrate --file invoices.csv --to-facility <facility-id> --yes
```

### Flags

| Flag            | Short | Required | Default | Description                                   |
| --------------- | ----- | -------- | ------- | --------------------------------------------- |
| `--file`        | `-f`  | Yes      | —       | CSV file with invoice IDs (column: `id`)      |
| `--to-facility` | `-t`  | Yes      | —       | Target facility ID                            |
| `--dry-run`     | —     | No       | `false` | Show what would be migrated without executing |
| `--yes`         | `-y`  | No       | `false` | Skip confirmation prompt                      |

***

## Recalculate

Recalculate emissions for invoices in a facility. Processes invoices one by one via PATCH.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice recalculate --facility <facility-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Recalculate all pending invoices
dcy invoice recalculate --facility <facility-id>

# Also recalculate completed invoices
dcy invoice recalculate --facility <facility-id> --completed --yes

# Override unit_id on every invoice before recalculating
dcy invoice recalculate --facility <facility-id> --unit-id <unit-uuid> --yes
```

### Flags

| Flag          | Short | Required | Default | Description                                             |
| ------------- | ----- | -------- | ------- | ------------------------------------------------------- |
| `--facility`  | `-f`  | Yes      | —       | Facility ID                                             |
| `--completed` | —     | No       | `false` | Include completed invoices with no calculated emissions |
| `--unit-id`   | —     | No       | —       | Override unit\_id on every invoice before recalculating |
| `--yes`       | `-y`  | No       | `false` | Skip confirmation prompt                                |
| `--org`       | —     | No       | —       | Organization ID override                                |

***

## Recalculate V2

Batch recalculate emissions via POST with activity category filtering. Supports scope-based and category-based filtering.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice recalculate-v2 --facility <facility-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Recalculate all scopes
dcy invoice recalculate-v2 --facility <facility-id> --yes

# Only Scope 1
dcy invoice recalculate-v2 --facility <facility-id> --scope 1

# Only Scope 3
dcy invoice recalculate-v2 --facility <facility-id> --scope 3

# Explicit activity categories (overrides --scope)
dcy invoice recalculate-v2 --facility <facility-id> \
  --activity-category heat --activity-category electricity --yes

# Include completed invoices
dcy invoice recalculate-v2 --facility <facility-id> --completed --yes
```

### Flags

| Flag                  | Short | Required | Default | Description                                                  |
| --------------------- | ----- | -------- | ------- | ------------------------------------------------------------ |
| `--facility`          | `-f`  | Yes      | —       | Facility ID                                                  |
| `--scope`             | —     | No       | `all`   | Scope to recalculate: `1`, `3`, or `all`                     |
| `--activity-category` | —     | No       | —       | Explicit activity category (repeatable, overrides `--scope`) |
| `--completed`         | —     | No       | `false` | Include completed invoices with no calculated emissions      |
| `--yes`               | `-y`  | No       | `false` | Skip confirmation prompt                                     |
| `--org`               | —     | No       | —       | Organization ID override                                     |

***

## Recalculate Legacy

Batch recalculate via the legacy endpoint. Can target invoices by facility or by explicit IDs.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy invoice recalculate-legacy [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# By facility
dcy invoice recalculate-legacy --facility <facility-id> --yes

# By explicit invoice IDs
dcy invoice recalculate-legacy --ids "id1,id2,id3" --yes

# Include completed invoices (with --facility)
dcy invoice recalculate-legacy --facility <facility-id> --completed --yes
```

### Flags

| Flag          | Short | Default | Description                                                         |
| ------------- | ----- | ------- | ------------------------------------------------------------------- |
| `--facility`  | `-f`  | —       | Facility ID (mutually exclusive with `--ids`)                       |
| `--ids`       | —     | —       | Invoice IDs, comma separated (mutually exclusive with `--facility`) |
| `--completed` | —     | `false` | Include completed invoices with no calculated emissions             |
| `--yes`       | `-y`  | `false` | Skip confirmation prompt                                            |
| `--org`       | —     | —       | Organization ID override                                            |

***

## Common Options

All invoice commands support:

| Flag            | Description                        |
| --------------- | ---------------------------------- |
| `--format json` | JSON output (default: text)        |
| `--verbose`     | Show HTTP request/response details |
| `--timeout`     | Request timeout in seconds         |

***

## Workflows

### Invoice Audit Pipeline

Export, filter, and verify energy invoices programmatically:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Export all invoices for a facility as JSON
dcy invoice list --facility <facility-id> --year 2024 --format json > invoices.json

# Recalculate emissions for invoices with errors
dcy invoice recalculate --facility <facility-id> --completed --yes

# Verify results
dcy invoice list --facility <facility-id> --type electricity --year 2024
```

### Bulk Migration Between Facilities

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. List invoices to identify what needs moving
dcy invoice list --facility <old-facility-id> --format json > to-migrate.json

# 2. Create CSV with invoice IDs
echo "id" > migrate.csv
dcy invoice list --facility <old-facility-id> --format json | jq -r '.[].id' >> migrate.csv

# 3. Preview migration
dcy invoice migrate --file migrate.csv --to-facility <new-facility-id> --dry-run

# 4. Execute
dcy invoice migrate --file migrate.csv --to-facility <new-facility-id> --yes
```

### Piping with jq

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Count invoices by type
dcy invoice list --facility <facility-id> --format json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

# Sum CO2e by type
dcy invoice list --facility <facility-id> --format json | jq 'group_by(.type) | map({type: .[0].type, total_co2e: map(.co2e // 0) | add})'

# Find invoices without emissions
dcy invoice list --facility <facility-id> --format json | jq '[.[] | select(.co2e == null)]'
```