> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhdar-sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use {baseUrl} for the environment-specific base URL provided to the partner integration team. Do not invent an API hostname.
> x-akhdar-* fields are publication provenance only. Do not treat them as partner integration instructions.

# Delivery Emissions

> Optional educational Well-to-Wheel estimates. An estimate is not environmental impact by itself.

<Info>
  Delivery Emissions provides an optional, educational Well-to-Wheel estimate. An estimate is not environmental impact by itself and is not required to confirm a contribution.
</Info>

## Operations

* `POST {baseUrl}/v1/emissions/estimates` creates an estimate.
* `GET {baseUrl}/v1/emissions/estimates/{calculation_id}` retrieves an estimate.
* `POST {baseUrl}/v1/impact-transactions/{transaction_id}/emissions-associations` associates an estimate with a confirmed contribution.

`Idempotency-Key` is required when creating an estimate or association.

## Calculation rules

Supported vehicle categories are:

* `motorcycle_gasoline`
* `car_gasoline`

Distance must satisfy `0 < distance_km <= 200` and may have no more than three decimal places.

The Well-to-Wheel factors are:

* `motorcycle_gasoline`: `143.23 gCO2e/km`
* `car_gasoline`: `207.51 gCO2e/km`

The calculation is `estimated_emissions_kgco2e = raw_emissions_gco2e / 1000`. Display values use two decimals with round-half-up. Values below `0.01` are shown as `<0.01`, never `0.00`.

## Create an estimate

Send this JSON to `POST {baseUrl}/v1/emissions/estimates`:

```json theme={null}
{
  "partner_order_ref": "ord_9f3c2a71",
  "distance_km": "7.400",
  "distance_unit": "km",
  "vehicle_category": "motorcycle_gasoline"
}
```

A calculated estimate returns HTTP `201`:

```json theme={null}
{
  "estimate": {
    "calculation_id": "calc_01HZX4K9M2Q8R7N6P5T4V3W2X1",
    "partner_order_ref": "ord_9f3c2a71",
    "status": "calculated",
    "distance_km": "7.400",
    "distance_unit": "km",
    "vehicle_category": "motorcycle_gasoline",
    "methodology_version": "DEM-WTW-v1.0.0",
    "vehicle_catalog_version": "DVC-v1.0.0",
    "emission_factor_version": "EF-DESNZ-2026-MOTORCYCLE-GASOLINE-AVG-WTW-v1.0.0",
    "emission_factor_gco2e_per_km": "143.23",
    "lifecycle_boundary": "well_to_wheel",
    "raw_emissions_gco2e": "1059.90200",
    "estimated_emissions_kgco2e": "1.059902",
    "display": {
      "kgco2e_two_decimals": "1.06",
      "uses_less_than_threshold": false,
      "formatted_en": "1.06 kg CO₂e",
      "formatted_ar": "1.06 كجم CO₂e"
    },
    "disclosure_en": "Estimated from distance and vehicle type.",
    "disclosure_ar": "تقديرية حسب المسافة ونوع المركبة.",
    "calculated_at": "2026-08-03T12:00:00Z",
    "expires_at": "2026-08-04T12:00:00Z",
    "environment": "sandbox"
  },
  "association": {
    "status": "not_requested"
  },
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c"
  }
}
```

## Associate an estimate

Unassociated estimates expire after 24 hours. After association, the immutable link snapshot is authoritative.

```bash theme={null}
curl -X POST "{baseUrl}/v1/impact-transactions/txn_01HZX6M4N5P6Q7R8S9T0U1V2/emissions-associations" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_assoc_01HZX8A1B2C3D4E5F6G7H8" \
  -H "Content-Type: application/json" \
  -d '{"calculation_id":"calc_01HZX4K9M2Q8R7N6P5T4V3W2X1"}'
```

A successful late association returns HTTP `201`:

```json theme={null}
{
  "association": {
    "status": "associated",
    "link": {
      "association_id": "link_01HZX7A1B2C3D4E5F6G7H8J9",
      "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
      "calculation_id": "calc_01HZX4K9M2Q8R7N6P5T4V3W2X1",
      "partner_order_ref": "ord_9f3c2a71",
      "estimated_emissions_kgco2e": "1.059902",
      "estimated_emissions_unit": "kgco2e",
      "distance_km": "7.400",
      "distance_unit": "km",
      "vehicle_category": "motorcycle_gasoline",
      "methodology_version": "DEM-WTW-v1.0.0",
      "emission_factor_version": "EF-DESNZ-2026-MOTORCYCLE-GASOLINE-AVG-WTW-v1.0.0",
      "calculated_at": "2026-08-03T12:00:00Z",
      "associated_at": "2026-08-03T12:20:00Z",
      "environment": "sandbox",
      "immutable": true
    }
  },
  "contribution_status": "confirmed",
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "idempotency_key": "idem_assoc_01HZX8A1B2C3D4E5F6G7H8"
  }
}
```

Association failure is non-fatal: the contribution remains confirmed, and the partner must not restore points.