# 1ClickImpact API - Full Reference

Last verified 2026-06-25. Maintained by 1ClickImpact, Inc. - canonical source for API behavior.

Base URL (Production): https://api.1clickimpact.com
Base URL (Sandbox):    https://sandbox.1clickimpact.com
Auth Header: x-api-key: YOUR_API_KEY

Related AI / LLM index files:
- Main site: https://1clickimpact.com/llms.txt and https://1clickimpact.com/llms-full.txt
- Shopify app help: https://help.1clickimpact.com/llms.txt
- This API reference (short): https://docs.1clickimpact.com/llms.txt

---

## WhoAmI
GET /v1/whoami
Description: Verify your API key and retrieve your account details.
Headers: x-api-key: YOUR_API_KEY

Response example:
{
  "user_id": "U123",
  "email": "my-email@email.com"
}

---

## Plant Trees
POST /v1/plant_tree
Description: Plant trees for your organization or on behalf of a customer. Each unit = 1 tree.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "category": "food",
  "notify": true,
  "metadata": { "order_id": "ORD-456", "source": "shopify" }
}
- amount (required): number of trees to plant (1-10,000,000)
- customer_email (optional): plants on behalf of a customer; triggers customer tracking
- customer_name (optional): display name for the customer; customer_email must be present
- category (optional): only supported value is "food" - plants food-bearing trees providing nutrition/income for local communities and grants access to exclusive live planting sessions. If omitted, standard reforestation trees are planted.
- notify (optional): send email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "tree_planted": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Clean Ocean
POST /v1/clean_ocean
Description: Remove ocean plastic waste. Amount is in lbs.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "cleanup_site": "Pacific Coast", "event": "World Ocean Day 2024" }
}
- amount (required): lbs of waste to remove (1-10,000,000)
- customer_email (optional): removes on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "waste_removed": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Capture Carbon
POST /v1/capture_carbon
Description: Capture/offset CO2 emissions. Amount is in lbs.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "facility": "Portland Plant", "batch": "B-2024-09" }
}
- amount (required): lbs of CO2 to capture (1-10,000,000)
- customer_email (optional): captures on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "carbon_captured": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Donate Money
POST /v1/donate_money
Description: Make a charitable donation. Amount is in the smallest currency unit (cents for USD). Supports optional `category` to tag donations with a specific cause.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 500,
  "category": "hunger",
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "charity": "PayPal Giving Fund", "campaign": "holiday-2024" }
}
- amount (required): smallest USD units (e.g. 10 = $0.10, 100 = $1.00, 500 = $5.00). Range 1-1,000,000,000.
- category (optional): donation cause category ID. The full cause label will appear in the /v1/track response as `donation_category`. Valid values:
  - "veterans" -> Veterans Support
  - "animals" -> Animal Welfare
  - "hunger" -> Hunger Relief
  - "education" -> Education
  - "climate" -> Climate Action
  - "water" -> Clean Water
  - "healthcare" -> Healthcare
  - "housing" -> Housing & Shelter
  - "youth" -> Youth Development
  - "disaster" -> Disaster Relief
- customer_email (optional): donates on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "money_donated": 500,
  "category": "hunger",
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Cancel Impact
POST /v1/cancel_impact
Description: Cancel and reverse a previously created impact. Designed for refund flows. Removes the impact from aggregate totals, reverses usage billing, and marks the impact as cancelled in the tracking system. The original record is preserved for audit purposes. Idempotent - calling multiple times returns the same result without double-reversing.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "user_id": "U1234",
  "time_utc": "2025-03-12T15:22:14.753Z",
  "reason": "order refunded"
}
- user_id (required): the user ID associated with the impact to cancel (format U12345). From /v1/records or /v1/customer_records.
- time_utc (required): the UTC timestamp of the original impact (ISO 8601 format). From /v1/records or /v1/customer_records.
- reason (optional): reason for cancellation (max 200 characters).

Response example:
{
  "user_id": "U1234",
  "time_utc": "2025-03-12T15:22:14.753Z",
  "cancelled_on": "2025-04-30T10:15:32.000Z",
  "reason": "order refunded",
  "tree_planted": 10,
  "category": "food",
  "message": "impact cancelled successfully"
}

Response fields:
  - user_id: the user ID associated with the cancelled impact
  - time_utc: the UTC timestamp of the original impact
  - cancelled_on: UTC time when the impact was cancelled
  - reason: cancellation reason if provided (optional)
  - tree_planted / waste_removed / carbon_captured / money_donated: original impact amounts that were reversed (only non-zero fields present)
  - category: category of the cancelled impact if one was set (optional)
  - message: "impact cancelled successfully" for new cancellations, "impact was already cancelled" for repeat calls

Notes:
  - Impacts that have already been processed (donation received by a non-profit) cannot be cancelled via the API. Contact 1ClickImpact for assistance.
  - You are not charged for cancelled impacts - usage billing is automatically reversed.
  - The /v1/track response for a cancelled impact will show `cancelled_on` and `cancellation_reason` fields.

---

## Website Carbon
GET /v1/carbon
Description: Calculate the carbon footprint of any website. Returns CO2 emissions per page view, carbon rating (A+ to F), green hosting status, and energy statistics using V4 of the Sustainable Web Design Model. Results are cached for 7 days.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - url (required): website URL to analyze (e.g., "example.com" or "https://example.com/page"). Subdomains supported. Redirects followed automatically. Max 2048 characters.
  - recalculate (optional): "true" to bypass cache and force fresh analysis. Default: false.

Response example:
{
  "url": "example.com",
  "cleaner_than": 0.91,
  "rating": "A",
  "green_hosting": false,
  "statistics": {
    "transfer_size": 495573,
    "energy": 0.000139,
    "co2": {
      "grid": {
        "grams": 0.068
      },
      "renewable": {
        "grams": 0.057
      }
    }
  },
  "tested_on": "2026-04-21"
}

Response fields:
  - url: normalized URL analyzed (lowercase, no protocol, no trailing slash)
  - cleaner_than: 0.0-1.0 - fraction of websites this page is cleaner than (e.g., 0.91 = cleaner than 91%)
  - rating: carbon grade - A+ (<=0.040g), A (<=0.079g), B (<=0.145g), C (<=0.209g), D (<=0.278g), E (<=0.359g), F (>0.359g)
  - green_hosting: whether the host uses renewable energy (verified by Green Web Foundation)
  - statistics.transfer_size: total page weight in bytes
  - statistics.energy: kWh consumed per page view
  - statistics.co2.grid.grams: grams CO2 per view assuming standard grid energy (494 gCO2e/kWh)
  - statistics.co2.renewable.grams: grams CO2 per view assuming renewable energy for data center portion
  - tested_on: date analyzed (YYYY-MM-DD), cached for 7 days

Notes:
  - Sandbox keys (test_ prefix) return a mock response with sample data
  - First analysis of a URL may take up to 30 seconds; subsequent requests return cached results instantly
  - The API verifies the URL is reachable before analysis; unreachable sites return an error

---

## Aggregated Impact
GET /v1/impact
Description: Returns total lifetime impact across all categories, including top-level totals and a breakdown between your direct impact (user_impact) and impact generated on behalf of customers (customer_impact).
Headers: x-api-key: YOUR_API_KEY

Response example:
{
  "user_id": "U123",
  "tree_planted": 100,
  "waste_removed": 50,
  "carbon_captured": 75,
  "money_donated": 25000,
  "user_impact": {
    "tree_planted": 60,
    "waste_removed": 30,
    "carbon_captured": 45,
    "money_donated": 15000
  },
  "customer_impact": {
    "tree_planted": 40,
    "waste_removed": 20,
    "carbon_captured": 30,
    "money_donated": 10000
  }
}

---

## Daily Impact
GET /v1/impact/daily
Description: Returns time-series daily impact data. Use for dashboards, reports, and trend analysis.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - start_date (optional): date in YYYY-MM-DD format e.g. "2025-01-01"
  - end_date (optional): date in YYYY-MM-DD format e.g. "2025-03-01"

Response example:
{
  "user_id": "U123",
  "daily_impact": [
    {
      "date": "2025-01-15",
      "tree_planted": 5,
      "waste_removed": 0,
      "carbon_captured": 0,
      "money_donated": 0
    },
    {
      "date": "2025-01-21",
      "tree_planted": 0,
      "waste_removed": 10,
      "carbon_captured": 0,
      "money_donated": 500
    }
  ]
}

---

## Records
GET /v1/records
Description: Retrieve your organization's full impact history. Supports multiple filter_by values as repeated query params.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - filter_by (optional): "tree_planted" | "waste_removed" | "carbon_captured" | "money_donated" (repeatable, e.g. ?filter_by=carbon_captured&filter_by=waste_removed)
  - start_date (optional): YYYY-MM-DD - return records after this date
  - end_date (optional): YYYY-MM-DD - return records up to this date
  - limit (optional): records per page, default 10, max 1000
  - cursor (optional): cursor value from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by time_utc

Response example:
{
  "user_records": [
    {
      "user_id": "U123",
      "time_utc": "2024-09-16T20:34:04.429Z",
      "tree_planted": 10,
      "metadata": { "order_id": "ORD-456", "source": "shopify" }
    },
    {
      "user_id": "U123",
      "time_utc": "2024-09-17T13:24:04.429Z",
      "waste_removed": 15
    }
  ],
  "cursor": "fNJjcmV32dGVkTiOi..."
}
Note: cursor is only present when more records exist (not the last page). The `metadata` field is only present on records that were created with metadata.

---

## Customer Records
GET /v1/customer_records
Description: Retrieve per-customer impact history. Optionally filter by a specific customer. Each record contains a nested customer object.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - customer_email (optional): filter to a specific customer
  - filter_by (optional): "tree_planted" | "waste_removed" | "carbon_captured" | "money_donated" (repeatable)
  - start_date (optional): YYYY-MM-DD
  - end_date (optional): YYYY-MM-DD
  - limit (optional): default 10, max 1000
  - cursor (optional): from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by time_utc

Response example:
{
  "customer_records": [
    {
      "user_id": "U123",
      "customer": {
        "customer_id": "U1234",
        "customer_email": "sample-customer@email.com",
        "customer_name": "Sample Customer"
      },
      "time_utc": "2024-06-12T15:22:14.753Z",
      "tree_planted": 10,
      "metadata": { "order_id": "ORD-456", "source": "shopify" }
    }
  ],
  "cursor": "eyJjcmVhdGVkT24i..."
}
Note: the `metadata` field is only present on records that were created with metadata.

---

## Customers
GET /v1/customers
Description: List all customers who have had impact created on their behalf. Customers are auto-onboarded when you create impact using their customer_email.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - customer_email (optional): retrieve or check a specific customer
  - limit (optional): default 10, max 1000
  - cursor (optional): from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by onboarded_on

Response example:
{
  "customers": [
    {
      "customer_id": "U1234",
      "customer_email": "sample-customer@email.com",
      "customer_name": "Sample Customer",
      "onboarded_on": "2024-06-12T15:22:14.753Z"
    }
  ],
  "cursor": "fNJjcmV32dGVkTiOi..."
}

---

## Track
GET /v1/track
Description: Real-time lifecycle tracking for a specific impact event across the complete environmental impact lifecycle.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - user_id (required): from the POST action response OR from /v1/records or /v1/customer_records
  - time_utc (required): from the POST action response OR from /v1/records or /v1/customer_records

Example: GET /v1/track?user_id=U1234&time_utc=2025-03-12T15:22:14.753Z

Response fields:
  - tracking_id: unique identifier formatted as user_id-time_utc
  - impact_initiated: UTC time when the impact process was initiated
  - tree_planted / waste_removed / carbon_captured / money_donated: impact amounts
  - category: impact category. "food" for food-bearing trees, or a donation cause ID (e.g., "hunger", "education", "veterans") for donations
  - donation_available: UTC time when donation became available (optional)
  - donation_sent: UTC time when donation was transferred to nonprofit (optional)
  - assigned_agent: name of nonprofit/agent assigned to execute the impact (optional)
  - project_location: description of the project location and implementing partners (optional)
  - location_map: Google Maps embed URL for visualizing the project location (optional)
  - impact_completed: UTC time when the impact was completed (optional)
  - project_id: slug identifier of the environmental project associated with this impact - use with GET /v1/projects/:project_id (optional)
  - donation_category: what type of impact the donation funded, e.g. "planting food trees" (optional, donate_money only)
  - certificate: certificate URL - only present in production (optional)
  - impact_video: URL to video recording or live session (optional)
  - live_session_date: UTC timestamp for scheduled live session (optional)
  - metadata: object of key-value pairs provided when the impact was created (optional)
  - is_test_transaction: true if this was a test transaction (optional)
  - is_bonus_impact: true if this was a bonus impact from a subscription plan (optional)
  - cancelled_on: UTC time when the impact was cancelled. Only present for cancelled impacts (optional)
  - cancellation_reason: reason provided for the cancellation. Only present for cancelled impacts that included a reason (optional)

Response example:
{
  "tracking_id": "U1234-2025-03-12T15:22:14.753Z",
  "impact_initiated": "2025-03-12T15:22:14.753Z",
  "tree_planted": 10,
  "category": "food",
  "donation_available": "2025-03-22T23:44:02.121Z",
  "donation_sent": "2025-03-26T20:11:17.707Z",
  "assigned_agent": "Planting On Demand",
  "project_id": "trees-uganda-di",
  "project_location": "Rwenzori Mountains, Uganda with Dream International.",
  "location_map": "https://www.google.com/maps/embed?...",
  "impact_completed": "2025-04-16T13:00:00.000Z",
  "certificate": "https://1clickimpact.com/certificate/U1234-2025-03-12T15:22:14.753Z",
  "impact_video": "https://meet.google.com/ynx-sgcq-dbd",
  "live_session_date": "2025-04-16T13:00:00.000Z",
  "metadata": { "order_id": "ORD-456", "source": "shopify" }
}

---

## Projects
GET /v1/projects
Description: Browse all verified environmental impact projects available through 1ClickImpact. Filter by project type and request localized content.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - type (optional): "trees" | "ocean" | "carbon" - filter by impact type
  - locale (optional): "en" | "de" | "es" | "fr" | "nl" - return translated content; falls back to English

Response example:
{
  "projects": [
    {
      "project_id": "trees-uganda-di",
      "name": "Dream International Uganda",
      "type": "trees",
      "location": "Uganda",
      "description": "Dream International is a community-led tree and forest restoration in the Rwenzori Mountain region for ecosystem services, biodiversity, and climate resilience.",
      "about": [
        "Dream International leads a community-driven tree and forest restoration initiative in the Rwenzori Mountain region of western Uganda - part of the globally important Albertine Rift biodiversity hotspot.",
        "Local communities are trained and employed as stewards of restored forest areas, receiving ongoing support in sustainable land management, agroforestry, and eco-enterprise development.",
        "By restoring tree cover in the Rwenzori highlands, the project directly protects headwaters that supply clean drinking water to thousands of downstream households."
      ],
      "country_code": "UG",
      "organization": "Planting on Demand",
      "sdgs": [
        { "id": "climate-action", "number": 13, "title": "Climate Action", "color": "#3F7E44", "link": "https://sdgs.un.org/goals/goal13" },
        { "id": "life-on-land", "number": 15, "title": "Life On Land", "color": "#56C02B", "link": "https://sdgs.un.org/goals/goal15" },
        { "id": "clean-water", "number": 6, "title": "Clean Water & Sanitation", "color": "#26BDE2", "link": "https://sdgs.un.org/goals/goal6" },
        { "id": "decent-work", "number": 8, "title": "Decent Work & Economic Growth", "color": "#A21942", "link": "https://sdgs.un.org/goals/goal8" },
        { "id": "no-poverty", "number": 1, "title": "No Poverty", "color": "#E5243B", "link": "https://sdgs.un.org/goals/goal1" },
        { "id": "partnerships", "number": 17, "title": "Partnerships For The Goals", "color": "#19486A", "link": "https://sdgs.un.org/goals/goal17" }
      ],
      "image_urls": [
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/1.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/2.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/3.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/4.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/5.jpg"
      ],
      "latitude": -12.3733,
      "longitude": 27.2903,
      "available": true
    }
  ]
}

---

## Project (single)
GET /v1/projects/:project_id
Description: Retrieve full details for a single project by its ID. Use the project_id from the /v1/projects list or from a /v1/track response.
Headers: x-api-key: YOUR_API_KEY
Path params:
  - project_id (required): unique identifier of the project (e.g., "trees-uganda-di")
Query params:
  - locale (optional): "en" | "de" | "es" | "fr" | "nl" - return translated content; falls back to English

Response fields:
  - project_id: unique slug identifier for the project
  - name: display name of the project
  - type: "trees" | "ocean" | "carbon"
  - location: human-readable location string
  - description: one-sentence project summary
  - about: array of paragraph strings with deeper project detail
  - country_code: ISO 3166-1 alpha-2 country code (e.g., "UG")
  - organization: name of the non-profit or partner executing the project
  - sdgs: array of UN SDG objects - each with id, number, title, description, color, link, icon_url
  - image_urls: array of image URLs for use in project cards or detail pages
  - latitude: project latitude coordinate
  - longitude: project longitude coordinate
  - available: boolean - whether the project is currently accepting new impacts

---

## Free Tools

Website Carbon Calculator: https://1clickimpact.com/website-carbon
- Free browser tool to check any website's carbon footprint
- Enter a URL and get an instant A+ to F carbon rating
- Shows CO2 per page view, green hosting status, transfer size, energy stats
- Annual impact equivalents (trees, cups of tea, smartphone charges, EV km)
- Suggests Climate Action Badge configuration and offset amounts
- No sign-up required

How It Works: https://1clickimpact.com/website-carbon/how-it-works
- Full methodology breakdown using Sustainable Web Design Model V4
- Energy intensity table (operational + embodied across data centers, networks, devices)
- Rating system explanation (A+ through F thresholds)
- V3 vs V4 comparison (0.81 -> 0.30 kWh/GB, 63% reduction)
- 10 FAQs about the calculator
- Sources and references

---

## Errors
Standard HTTP status codes are used. Common errors:
- 401 Unauthorized: missing or invalid x-api-key
- 400 Bad Request: missing required fields or invalid values
- 429 Too Many Requests: rate limit exceeded
- 500 Internal Server Error: contact support

## Pagination
Cursor-based. Default page size is 10; max is 1000 via `limit` param. When more pages exist, the response includes a `cursor` field. Pass this `cursor` value as the `cursor` query param in the next request. When `cursor` is absent in the response, you have reached the last page. Supported on /v1/records, /v1/customer_records, and /v1/customers.
Can also use `start_date` and `end_date` (YYYY-MM-DD) to filter the date range of records returned.