Purchases - Dcycle Platform Docs

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

Overview

The purchase command tracks goods and services purchased from suppliers, covering GHG Protocol Scope 3 Category 1 (Purchased Goods & Services) and Category 2 (Capital Goods).

dcy purchase <subcommand> [flags]

Available Commands

Command	Description
`list`	List purchases
`show`	Show purchase details
`edit`	Edit a purchase
`upload`	Upload purchases from CSV
`purge-orphan-suppliers`	Remove suppliers with no associated purchases
`supplier-specific upload-suppliers`	Upload supplier-specific emission factors
`supplier-specific upload-purchases`	Upload purchases linked to supplier-specific factors

List Purchases

dcy purchase list [flags]

# Aliases
dcy purchase ls

Examples

# List all purchases
dcy purchase list

# Search by description or supplier
dcy purchase list --search "steel"

# Filter by exact description
dcy purchase list --description "Steel beams"

# Filter by status (repeatable for multiple values)
dcy purchase list --status validated
dcy purchase list --status validated --status uploaded

# Filter by purchase type (repeatable)
dcy purchase list --purchase-type goods
dcy purchase list --purchase-type spend_based

# Filter by expense type (repeatable)
dcy purchase list --expense-type capital_goods
dcy purchase list --expense-type capex

# Pagination
dcy purchase list --page 2 --size 100

# JSON output for scripting
dcy purchase list --format json

Flags

Flag	Default	Description
`--search`	—	Search by description or supplier name
`--description`	—	Filter by exact description
`--status`	—	Filter by status (repeatable)
`--purchase-type`	—	Filter by purchase type (repeatable)
`--expense-type`	—	Filter by expense type (repeatable)
`--page`	`1`	Page number
`--size`	`50`	Page size
`--org`	—	Organization ID override

Output

Showing 3 of 42 purchases in Acme Corp
abc123-... | Steel Beams    | 500.00 kg  | capex     | validated | SupplierCo
def456-... | Office Paper   |  20.00 EUR | opex      | uploaded  | PaperInc
ghi789-... | IT Equipment   | 3 units    | capex     | active    | TechSupply

Columns: ID, product name, quantity, expense type, status, supplier.

Show Purchase

Display full details for a single purchase.

dcy purchase show <purchase-id>

Examples

dcy purchase show 00000000-0000-0000-0000-000000000000

# JSON output
dcy purchase show <purchase-id> --format json

Flags

Flag	Description
`--org`	Organization ID override

Output Fields

ID, product name, description, purchase date, quantity, expense type, purchase type, status, sector, unit, supplier, recycled value, CO2e, and file information.

Edit Purchase

Update metadata on a single purchase.

dcy purchase edit <purchase-id> [flags]

Examples

dcy purchase edit <purchase-id> --description "Updated description"
dcy purchase edit <purchase-id> --quantity 500 --unit-id <unit-uuid>
dcy purchase edit <purchase-id> --purchase-date 2024-06-15
dcy purchase edit <purchase-id> --expense-type capital_goods

Flags

Flag	Description
`--description`	Purchase description
`--quantity`	Quantity
`--purchase-date`	Purchase date (YYYY-MM-DD)
`--recycled`	Recycled value
`--product-name`	Product name
`--unit-id`	Unit ID
`--expense-type`	Expense type
`--org`	Organization ID override

Upload Purchases

Bulk upload purchases from a CSV file.

dcy purchase upload <file.csv> [flags]

Examples

# Upload with validation (default)
dcy purchase upload purchases.csv

# Skip validation
dcy purchase upload purchases.csv --skip-validation

Flags

Flag	Default	Description
`--skip-validation`	`false`	Skip validation step
`--org`	—	Organization ID override

Purge Orphan Suppliers

Remove suppliers that have no associated purchases. Useful for cleanup after bulk delete operations.

dcy purchase purge-orphan-suppliers [flags]

Examples

# With confirmation prompt
dcy purchase purge-orphan-suppliers

# Skip confirmation
dcy purchase purge-orphan-suppliers --yes

Flags

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

Supplier-Specific Operations

Upload custom emission factors from specific suppliers, then upload purchases linked to those factors. This improves accuracy over generic spend-based calculations.

Upload Supplier Emission Factors

dcy purchase supplier-specific upload-suppliers [file.csv] [flags]

Examples

# Generate CSV template
dcy purchase supplier-specific upload-suppliers --template

# Validate without uploading
dcy purchase supplier-specific upload-suppliers factors.csv --dry-run

# Upload emission factors
dcy purchase supplier-specific upload-suppliers factors.csv

Flags

Flag	Default	Description
`--template`	`false`	Print CSV template to stdout
`--dry-run`	`false`	Validate without uploading
`--org`	—	Organization ID override

Upload Supplier-Specific Purchases

dcy purchase supplier-specific upload-purchases [file.csv] [flags]

Examples

# Generate CSV template
dcy purchase supplier-specific upload-purchases --template

# Validate without uploading
dcy purchase supplier-specific upload-purchases purchases.csv --dry-run

# Upload
dcy purchase supplier-specific upload-purchases purchases.csv

Flags

Flag	Default	Description
`--template`	`false`	Print CSV template to stdout
`--dry-run`	`false`	Validate without uploading
`--org`	—	Organization ID override

Supplier-specific emission factors improve accuracy over generic spend-based factors. Request real data from your suppliers’ environmental reports.

Common Options

All purchase commands support:

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

Workflows

Bulk Upload Pipeline

# 1. Upload purchases CSV (validates first by default)
dcy purchase upload purchases.csv

# 2. If validation passes, upload for real
dcy purchase upload purchases.csv --skip-validation

# 3. Verify uploaded data
dcy purchase list --status uploaded

Supplier-Specific Factors Pipeline

# 1. Generate and fill supplier emission factor template
dcy purchase supplier-specific upload-suppliers --template > suppliers.csv
# (edit suppliers.csv with your data)

# 2. Validate
dcy purchase supplier-specific upload-suppliers suppliers.csv --dry-run

# 3. Upload factors
dcy purchase supplier-specific upload-suppliers suppliers.csv

# 4. Generate and fill purchases template
dcy purchase supplier-specific upload-purchases --template > purchases.csv
# (edit purchases.csv with your data)

# 5. Upload purchases
dcy purchase supplier-specific upload-purchases purchases.csv

Piping with jq

# List purchases by expense type
dcy purchase list --format json | jq 'group_by(.expense_type) | map({type: .[0].expense_type, count: length})'

# Find purchases without emissions
dcy purchase list --format json | jq '[.[] | select(.co2e == null)] | length'

# Export supplier names
dcy purchase list --format json | jq '[.[].supplier.business_name // "N/A"] | unique'

​Overview

​Available Commands

​List Purchases

​Examples

​Flags

​Output

​Show Purchase

​Examples

​Flags

​Output Fields

​Edit Purchase

​Examples

​Flags

​Upload Purchases

​Examples

​Flags

​Purge Orphan Suppliers

​Examples

​Flags

​Supplier-Specific Operations

​Upload Supplier Emission Factors

​Examples

​Flags

​Upload Supplier-Specific Purchases

​Examples

​Flags

​Common Options

​Workflows

​Bulk Upload Pipeline

​Supplier-Specific Factors Pipeline

​Piping with jq

Overview

Available Commands

List Purchases

Examples

Flags

Output

Show Purchase

Examples

Flags

Output Fields

Edit Purchase

Examples

Flags

Upload Purchases

Examples

Flags

Purge Orphan Suppliers

Examples

Flags

Supplier-Specific Operations

Upload Supplier Emission Factors

Examples

Flags

Upload Supplier-Specific Purchases

Examples

Flags

Common Options

Workflows

Bulk Upload Pipeline

Supplier-Specific Factors Pipeline

Piping with jq