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

# Purchases

> Track goods and services purchased from suppliers for Scope 3 emissions

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

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy purchase list [flags]

# Aliases
dcy purchase ls
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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.

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

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

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

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy purchase upload <file.csv> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy purchase purge-orphan-suppliers [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy purchase supplier-specific upload-suppliers [file.csv] [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy purchase supplier-specific upload-purchases [file.csv] [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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     |

<Tip>
  Supplier-specific emission factors improve accuracy over generic spend-based factors. Request real data from your suppliers' environmental reports.
</Tip>

***

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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'
```