Delivery Emissions

Create a delivery-emissions estimate

Creates an optional educational Well-to-Wheel delivery-emissions estimate. An estimate is not environmental impact by itself and is not required to confirm a contribution.

Inputs

Supported vehicle categories: motorcycle_gasoline, car_gasoline.
Distance: 0 < distance_km <= 200, at most three decimal places.
Idempotency-Key is required.

Factors

motorcycle_gasoline: 143.23 g CO₂e/km
car_gasoline: 207.51 g CO₂e/km

Calculation and display

raw_emissions_gco2e = distance_km × emission_factor_gco2e_per_km
estimated_emissions_kgco2e = raw_emissions_gco2e ÷ 1000
Customer display uses two decimals and round-half-up. Values below 0.01 kg CO₂e are shown as <0.01, never 0.00.

Unassociated estimates expire after 24 hours. If a confirmed contribution already exists for the same partner, environment, and partner_order_ref, this request may create the association. You can also associate later with POST /v1/impact-transactions/{transaction_id}/emissions-associations. After association, the immutable snapshot is the reporting record.

Reusing Idempotency-Key with the same canonical payload returns the original estimate. A conflicting payload returns idempotency_conflict. Do not use partner_order_ref alone as the estimate identity.

POST

emissions

estimates

cURL

curl -X POST "{baseUrl}/v1/emissions/estimates" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_est_01HZX4K9M2Q8R7N6P5T4V3" \
  -H "Content-Type: application/json" \
  -d '{"partner_order_ref":"ord_9f3c2a71","distance_km":"7.400","distance_unit":"km","vehicle_category":"motorcycle_gasoline"}'

const response = await fetch(`${baseUrl}/v1/emissions/estimates`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AKHDAR_API_KEY,
    "Idempotency-Key": "idem_est_01HZX4K9M2Q8R7N6P5T4V3",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    partner_order_ref: "ord_9f3c2a71",
    distance_km: "7.400",
    distance_unit: "km",
    vehicle_category: "motorcycle_gasoline"
  })
});

import os
import requests

response = requests.post(
    f"{baseUrl}/v1/emissions/estimates",
    headers={
        "X-API-Key": os.environ["AKHDAR_API_KEY"],
        "Idempotency-Key": "idem_est_01HZX4K9M2Q8R7N6P5T4V3",
        "Content-Type": "application/json",
    },
    json={
        "partner_order_ref": "ord_9f3c2a71",
        "distance_km": "7.400",
        "distance_unit": "km",
        "vehicle_category": "motorcycle_gasoline",
    },
)

{
  "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": "1.059902",
    "lifecycle_boundary": "well_to_wheel",
    "raw_emissions_gco2e": "1.059902",
    "estimated_emissions_kgco2e": "1.059902",
    "display": {
      "uses_less_than_threshold": false,
      "formatted_en": "1.06 kg CO₂e",
      "formatted_ar": "1.06 كجم CO₂e",
      "kgco2e_two_decimals": "1.06"
    },
    "disclosure_en": "Estimated from distance and vehicle type.",
    "disclosure_ar": "تقديرية حسب المسافة ونوع المركبة.",
    "calculated_at": "2026-08-03T12:00:00.000Z",
    "expires_at": "2026-08-03T12:00:00.000Z",
    "environment": "sandbox"
  },
  "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:00.000Z",
      "associated_at": "2026-08-03T12:00:00.000Z",
      "environment": "sandbox",
      "immutable": true
    }
  },
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "idempotency_key": "idem_01HZX5Z9Y8X7W6V5U4T3S2R1"
  }
}

Authorizations

X-API-Key

string

header

required

Canonical server-to-server API key header name: X-API-Key. Partner customer applications must not use this credential. Examples must never include raw API secrets.

Headers

Idempotency-Key

string

required

Transport/request idempotency key required for delivery-emissions estimate creation, contribution confirmation, and emissions-association creation. Same key + same canonical payload returns the original result. Same key + conflicting canonical payload returns idempotency_conflict.

Non-PII transport idempotency key.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"idem_01HZX5Z9Y8X7W6V5U4T3S2R1"

X-Correlation-ID

string

Optional request correlation header. If omitted, Akhdar generates one. Every success and error response includes X-Correlation-ID. Error payloads include correlation_id.

Non-PII request correlation identifier.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"corr_7c2e9b1a4d6f8e0c"

Body

application/json

partner_order_ref

string

required

Stable non-PII partner order correlation reference. Enforces one confirmed contribution per partner order within partner and environment. Must not contain direct personal data.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Example:

"ord_9f3c2a71"

distance_km

string

required

Partner-supplied estimated route distance in kilometres as a decimal string. Validation rules:

Positive decimal-string values only
0 < distance_km <= 200
Maximum three decimal places
Maximum value exactly 200
200, 200.0, 200.00, and 200.000 are valid
Values above 200 are invalid
Reject excess precision rather than silently round Trailing-zero numeric equivalence is preserved for values within range (5, 5.0, 5.000).

Pattern: ^(?:0\.(?!0+$)\d{1,3}|(?:[1-9]|[1-9]\d|1\d{2})(?:\.\d{1,3})?|200(?:\.0{1,3})?)$

Example:

"7.400"

distance_unit

enum<string>

required

Distance unit. Kilometres only.

Available options:

km

Example:

"km"

vehicle_category

enum<string>

required

Exact supported vehicle categories. Aliases, inferred vehicles, and defaults are not accepted.

Available options:

motorcycle_gasoline,

car_gasoline

Example:

"motorcycle_gasoline"

order_context_at

string<date-time>

Optional partner-supplied order context timestamp. Omission does not block estimate creation. Included in the estimate idempotency hash only when supplied.

Example:

"2026-08-03T12:00:00.000Z"

Response

Idempotent replay of the same estimate-creating request returned the original estimate. Same authenticated partner, environment, Idempotency-Key, and canonical request-body hash return the original estimate.

estimate

object

required

Show child attributes

association

object

required

Association outcome when estimate creation also evaluates association to an existing confirmed contribution for the same partner_order_ref. not_requested when no confirmed contribution was available at create time.

Option 1
Option 2
Option 3

Show child attributes

request

object

required

Show child attributes

⌘I

cURL

curl -X POST "{baseUrl}/v1/emissions/estimates" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_est_01HZX4K9M2Q8R7N6P5T4V3" \
  -H "Content-Type: application/json" \
  -d '{"partner_order_ref":"ord_9f3c2a71","distance_km":"7.400","distance_unit":"km","vehicle_category":"motorcycle_gasoline"}'

const response = await fetch(`${baseUrl}/v1/emissions/estimates`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AKHDAR_API_KEY,
    "Idempotency-Key": "idem_est_01HZX4K9M2Q8R7N6P5T4V3",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    partner_order_ref: "ord_9f3c2a71",
    distance_km: "7.400",
    distance_unit: "km",
    vehicle_category: "motorcycle_gasoline"
  })
});

import os
import requests

response = requests.post(
    f"{baseUrl}/v1/emissions/estimates",
    headers={
        "X-API-Key": os.environ["AKHDAR_API_KEY"],
        "Idempotency-Key": "idem_est_01HZX4K9M2Q8R7N6P5T4V3",
        "Content-Type": "application/json",
    },
    json={
        "partner_order_ref": "ord_9f3c2a71",
        "distance_km": "7.400",
        "distance_unit": "km",
        "vehicle_category": "motorcycle_gasoline",
    },
)

{
  "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": "1.059902",
    "lifecycle_boundary": "well_to_wheel",
    "raw_emissions_gco2e": "1.059902",
    "estimated_emissions_kgco2e": "1.059902",
    "display": {
      "uses_less_than_threshold": false,
      "formatted_en": "1.06 kg CO₂e",
      "formatted_ar": "1.06 كجم CO₂e",
      "kgco2e_two_decimals": "1.06"
    },
    "disclosure_en": "Estimated from distance and vehicle type.",
    "disclosure_ar": "تقديرية حسب المسافة ونوع المركبة.",
    "calculated_at": "2026-08-03T12:00:00.000Z",
    "expires_at": "2026-08-03T12:00:00.000Z",
    "environment": "sandbox"
  },
  "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:00.000Z",
      "associated_at": "2026-08-03T12:00:00.000Z",
      "environment": "sandbox",
      "immutable": true
    }
  },
  "request": {
    "correlation_id": "corr_7c2e9b1a4d6f8e0c",
    "idempotency_key": "idem_01HZX5Z9Y8X7W6V5U4T3S2R1"
  }
}

Overview

Contributions

Delivery Emissions

Webhooks

Create a delivery-emissions estimate

Authorizations

Headers

Body

Response