Invoices - Dcycle Platform Docs

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

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.

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.

dcy invoice list --facility <facility-id>

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

Examples

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

dcy invoice show <invoice-id>

Examples

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

dcy invoice download <invoice-id>

Examples

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

dcy invoice edit <invoice-id> [<invoice-id>...] [flags]

Examples

# 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

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

Delete Invoice

Delete a single invoice by ID.

dcy invoice delete <invoice-id> [flags]

Examples

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

dcy invoice bulk-delete [flags]

Examples

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

dcy invoice migrate --file <csv-path> --to-facility <facility-id> [flags]

Examples

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

dcy invoice recalculate --facility <facility-id> [flags]

Examples

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

dcy invoice recalculate-v2 --facility <facility-id> [flags]

Examples

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

dcy invoice recalculate-legacy [flags]

Examples

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

# 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

# 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

# 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)]'

​Overview

​Available Commands

​Invoice Types

​List Invoices

​Examples

​Flags

​Output

​Show Invoice

​Examples

​Flags

​Output Fields

​Download Invoice

​Examples

​Flags

​Edit Invoice

​Examples

​Flags

​Delete Invoice

​Examples

​Flags

​Bulk Delete

​Examples

​Flags

​Migrate

​Examples

​Flags

​Recalculate

​Examples

​Flags

​Recalculate V2

​Examples

​Flags

​Recalculate Legacy

​Examples

​Flags

​Common Options

​Workflows

​Invoice Audit Pipeline

​Bulk Migration Between Facilities

​Piping with jq

Overview

Available Commands

Invoice Types

List Invoices

Examples

Flags

Output

Show Invoice

Examples

Flags

Output Fields

Download Invoice

Examples

Flags

Edit Invoice

Examples

Flags

Delete Invoice

Examples

Flags

Bulk Delete

Examples

Flags

Migrate

Examples

Flags

Recalculate

Examples

Flags

Recalculate V2

Examples

Flags

Recalculate Legacy

Examples

Flags

Common Options

Workflows

Invoice Audit Pipeline

Bulk Migration Between Facilities

Piping with jq