​

Bulk Upload Purchases

​

Upload Flow

​

Step 1: Request Presigned URL

​

Request

​

Headers

​

Body Parameters

​

Response

​

Example

curl -X POST "https://api.dcycle.io/api/v1/purchases/bulk/csv" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "2024_q1_purchases.csv"
  }'

​

Successful Response

{
  "upload_url": "https://dcycle-purchases.s3.amazonaws.com/files/dcycle/...",
  "file_name": "2024_q1_purchases",
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destination_file_key": "files/dcycle/.../2024_q1_purchases.csv",
  "message": "Upload pre-signed url generated"
}

​

Step 2: Upload CSV to S3

# The presigned URL already includes authentication parameters
curl -X PUT "${UPLOAD_URL}" \
  -H "Content-Type: text/csv" \
  --data-binary @2024_q1_purchases.csv

​

CSV Format

quantity,unit_id,sector,product_name,purchase_date,country,description,recycled,frequency,supplier_business_name,supplier_country
25000.50,eur-unit-uuid,IT Services,Cloud Computing,2024-01-15,ES,AWS monthly costs,0.0,monthly,AWS EMEA SARL,IE
15000.00,eur-unit-uuid,Office Supplies,Printer Paper,2024-01-10,ES,Q1 paper purchase,0.3,quarterly,Office Depot,ES
8500.75,eur-unit-uuid,Transportation,Courier Services,2024-01-20,ES,Monthly DHL costs,0.0,monthly,DHL Express,ES

​

Required Columns

​

Optional Columns

​

Column Details

• Must be positive number
• Typically in currency units (EUR, USD, etc.)
• No negative values allowed

• Must be a valid UUID from the Units endpoint
• For spend-based purchases, use currency units (EUR, USD, GBP, etc.)
• Get valid unit IDs: GET /api/v1/units?type=fiat_currency

• Economic sector classification
• Based on EXIOBASE or NAICS codes
• Examples: "IT Services", "Manufacturing", "Transportation", "Construction"

• Descriptive name of the product or service
• Free text field
• Examples: "Cloud Computing", "Office Furniture", "Legal Services"

• Must be today or in the past
• Format: YYYY-MM-DD
• Used to select appropriate emission factors by year

• ISO 3166-1 alpha-2 country code (2 letters)
• Where the purchase was made
• Common values: ES (Spain), US (USA), FR (France), DE (Germany), GB (UK)

• For recurring purchases
• Values: once, weekly, monthly, quarterly, yearly
• Default: once

• Percentage of recycled content
• Range: 0.0 (0%) to 1.0 (100%)
• Reduces emission calculations
• Leave empty or 0.0 if not applicable

​

Download Template

​

Step 3: Asynchronous Processing

1. Validation: The system validates format, units, sectors, and dates
2. Processing: Each row is processed and purchases are created
3. Emission Calculation: CO2e values calculated using economic input-output factors
4. Supplier Matching: Suppliers are matched or created based on business_name and country
5. Notification: (Coming soon) You’ll receive a webhook when complete

​

Step 4: Verify Results

# List purchases
curl "https://api.dcycle.io/api/v1/purchases" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

​

Complete Example Script

import requests
import os
from time import sleep

class DcyclePurchases:
    def __init__(self, api_key, org_id, user_id):
        self.api_key = api_key
        self.org_id = org_id
        self.user_id = user_id
        self.base_url = "https://api.dcycle.io"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "x-organization-id": org_id,
            "x-user-id": user_id,
            "Content-Type": "application/json"
        }

    def upload_csv(self, csv_file_path):
        """Complete CSV upload: presigned URL + upload + verification"""

        # 1. Get presigned URL
        file_name = os.path.basename(csv_file_path)
        response = requests.post(
            f"{self.base_url}/api/v1/purchases/bulk/csv",
            headers=self.headers,
            json={"file_name": file_name}
        )
        response.raise_for_status()

        upload_url = response.json()["upload_url"]
        file_id = response.json()["file_id"]

        print(f"✅ Presigned URL obtained (File ID: {file_id})")

        # 2. Upload file
        with open(csv_file_path, 'rb') as f:
            upload_response = requests.put(
                upload_url,
                data=f,
                headers={'Content-Type': 'text/csv'}
            )
        upload_response.raise_for_status()

        print(f"✅ File uploaded successfully")

        # 3. Wait for processing (optional)
        print("⏳ Processing... (this may take a few minutes)")
        sleep(30)  # Wait 30 seconds

        # 4. Verify purchases
        purchases = self.get_purchases()
        print(f"✅ Total purchases: {purchases['total']}")

        return file_id

    def get_purchases(self, page=1, size=50):
        """List purchases"""
        response = requests.get(
            f"{self.base_url}/api/v1/purchases",
            headers=self.headers,
            params={"page": page, "size": size}
        )
        response.raise_for_status()
        return response.json()

# Usage
if __name__ == "__main__":
    client = DcyclePurchases(
        api_key=os.getenv("DCYCLE_API_KEY"),
        org_id=os.getenv("DCYCLE_ORG_ID"),
        user_id=os.getenv("DCYCLE_USER_ID")
    )

    client.upload_csv("2024_q1_purchases.csv")

​

Common Errors

​

400 Bad Request - Missing file_name

{
  "detail": "Field required",
  "field": "file_name"
}

​

403 Forbidden - URL Expired

​

422 Validation Error - CSV Format

​

422 Validation Error - Invalid Unit ID

​

422 Validation Error - Invalid Date

​

422 Validation Error - Invalid Country

​

Limits and Recommendations

​

Best Practices

​

Data Preparation

1. Clean supplier names: Use consistent naming (e.g., “AWS EMEA SARL” not “Amazon Web Services” or “AWS”)
2. Validate unit IDs: Check that unit_id exists before upload using /api/v1/units?type=fiat_currency
3. Standardize sectors: Use consistent sector names across purchases
4. Include recycled content: For products with recycled materials, include the percentage

​

Error Handling

def check_for_errors():
    """Check if any purchases failed to process"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/purchases",
        headers=headers,
        params={"filter_by": "status:eqerror"}
    )

    purchases = response.json()

    if purchases['total'] > 0:
        print(f"⚠️ {purchases['total']} purchases have errors:")
        for purchase in purchases['items']:
            print(f"  - {purchase.get('product_name', 'Unnamed')}: {purchase.get('sector')}")

    return purchases['total']

# Check after processing
errors_count = check_for_errors()
if errors_count == 0:
    print("✅ All purchases processed successfully")

​

Incremental Updates

1. Export current purchases
2. Modify or add rows
3. Re-upload (system will handle duplicates)

​

Economic Sectors

​

Manufacturing & Production

• Manufacturing - General manufacturing
• Food & Beverage Manufacturing
• Textile Manufacturing
• Chemical Manufacturing

​

Services

• IT Services - Technology and software services
• Professional Services - Consulting, legal, accounting
• Financial Services - Banking, insurance
• Healthcare Services - Medical services

​

Transportation & Logistics

• Transportation - General transport services
• Air Transport - Air freight and passenger
• Water Transport - Sea and inland water transport
• Land Transport - Road and rail transport

​

Construction & Real Estate

• Construction - Building and infrastructure
• Real Estate - Property services

​

Other

• Office Supplies - Stationery, equipment
• Utilities - Water, waste management
• Agriculture - Agricultural products

​

Special Notes

​

Spend-Based Method

• Emissions calculated based on economic input-output tables
• Formula: CO2e = Amount (EUR) × Emission Factor (kg CO2e/EUR)
• Emission factors vary by sector, product, and country/region
• Factors updated annually based on latest data

​

Recycled Content

• Emission factor is reduced proportionally
• Example: 30% recycled content → 30% lower emissions
• Based on lifecycle assessment data
• Applies to materials like paper, plastics, metals

​

Supplier Matching

• Creates new suppliers if not found
• Matches by business_name and country
• Stores supplier data for future purchases
• Links purchases to supplier records

​

Country Codes

• Spain: ES
• United States: US
• France: FR
• Germany: DE
• United Kingdom: GB
• Italy: IT
• Netherlands: NL

​

Related Endpoints