This endpoint calculates the carbon footprint of a transaction and locks in pricing and tax rates for carbon credits and sustainability contributions. The returned quote must be reused when allocating funds. For the full request and response schema, see the Create carbon quote endpoint in the API reference.

📘

Direct API integration only

This endpoint is used in direct API integrations. If you're using one of the ekko SDKs, the quote is generated automatically in the backend and you don't need to call this endpoint.

When to use this endpoint

Use this endpoint whenever you need to show environmental footprint data or pricing to a consumer. For example:

• At checkout
• After a purchase
• In a post-purchase or confirmation flow

What the quote contains

Every carbon quote response includes:

• A carbon footprint calculation with localised equivalents
• A carbon credit quote tied to that footprint
• Sustainability contribution data, expressed as effective rates

This gives you flexibility over what you surface to consumers. For example, you might show only the footprint and a credit price, or combine credits with a round-up contribution option.

❗️

Reuse the quote

The quote locks in pricing and tax rates. You must pass the quoteId when allocating funds.

Request fields

Example request

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "locale": "en-GB",
  "consumer": {
    "reference": "consumer_123",
    "postalCode": "SW1A 1AA",
    "city": "London",
    "countryCode": "GBR"
  },
  "merchant": {
    "name": "Blossom & Bloom",
    "mcc": "5992",
    "address": {
      "line1": "Ground floor",
      "line2": "45 Rosewood Avenue",
      "line3": "Unit 124A",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GBR"
    }
  },
  "transaction": {
    "amount": 47.97,
    "currencyCode": "GBP"
  },
  "projectFilters": {
    "credits": {
      "matchConsumerLocation": true
    }
  },
  "responseOptions": {
    "includeImpactPartnerDetails": true,
    "includeImpactPartnerRates": true
  }
}

Response

The response contains three main sections: footprint, credits and contribution.

Footprint

The footprint section returns the estimated greenhouse gas emissions for the transaction, with localised equivalents you can display to consumers.

"footprint": {
  "co2eGrams": 18251,
  "co2eOunces": 644,
  "equivalents": [
    {
      "key": "phone",
      "value": 106,
      "description": "That's like using your mobile phone for 106 hours"
    },
    {
      "key": "car",
      "value": 81,
      "description": "That's like driving 81 km by car"
    }
  ]
}

Each equivalent has a key you can use to select an icon or layout, a numeric value and a localised description ready to display.

Credits

The credits section returns the cost of purchasing carbon credits to address the estimated emissions. amounts.total includes the impact amount, service fee and applicable sales tax.

Always display amounts.total to the consumer. The itemised breakdown is provided for jurisdictions where sales tax must be displayed separately.

"credits": {
  "amounts": {
    "total": 0.518,
    "impact": 0.216,
    "impactTax": 0.0,
    "serviceFee": 0.043,
    "serviceFeeTax": 0.009
  },
  "effectiveRates": {
    "impact": 0.5,
    "impactTax": 0.0,
    "serviceFee": 0.2,
    "serviceFeeTax": 0.2
  },
  "unit": {
    "description": "tCO2e",
    "price": 15
  },
  "consumerLocationMatchAccuracy": "country",
  "impactPartners": [
    {
      "id": "250636c2-8702-47c1-9720-7c3f93395790",
      "name": "Gold Standard",
      "shortDescription": "Text describing the impact partner",
      "images": {
        "logos": [
          { "path": "logos/gold-standard-logo.png", "type": "default", "width": 200, "height": 200 }
        ],
        "thumbnails": [
          { "path": "thumbnails/gold-standard-thumb.jpg", "type": "default", "width": 400, "height": 300 }
        ],
        "backgrounds": [
          { "path": "backgrounds/gold-standard-bg.jpg", "type": "default", "width": 1920, "height": 1080 }
        ]
      }
    }
  ]
}

amounts is the breakdown to charge for this quote. effectiveRates are the rates used to derive those amounts, expressed as proportions. unit describes the carbon credit unit and its price in the quote currency.

The consumerLocationMatchAccuracy field indicates how closely the selected projects match the consumer's location. Possible values are state, country and global. If no local projects are available, ekko falls back to broader matching.

Impact partner details (name, shortDescription, images) are included only when responseOptions.includeImpactPartnerDetails is set to true. When it is false, the impactPartners array is left out.

📘

Selecting projects

The quote response doesn't list individual projects. To retrieve the projects allocated to a quote, call the List quote projects endpoint (GET /quotes/{id}/projects). You can pass a project ID from that response when allocating funds.

Contribution

The contribution section returns the effective rates for sustainability contributions. Unlike credits, contributions aren't tied to the transaction's footprint. They let consumers support environmental projects through fixed amounts or round-ups.

"contribution": {
  "effectiveRates": {
    "impact": 0.5,
    "impactTax": 0.0,
    "serviceFee": 0.2,
    "serviceFeeTax": 0.2
  },
  "impactPartners": [
    {
      "id": "9405545f-a850-4427-ab0d-10b5b734e925",
      "name": "Tusk",
      "shortDescription": "Text describing the impact partner",
      "images": {
        "logos": [
          { "path": "logos/tusk-logo.png", "type": "default", "width": 200, "height": 200 }
        ]
      }
    }
  ]
}

The effective rates tell you how any contribution amount will be split. For example, with impact at 0.5 and serviceFee at 0.2, a £1.00 contribution would allocate £0.50 to impact, £0.20 as a service fee and the remainder to sales tax where applicable.

As with credits, the impactPartners array is included only when responseOptions.includeImpactPartnerDetails is true.

Partner rates

When you set responseOptions.includeImpactPartnerRates to true, the response includes a top-level partnerRates section with per-partner rate breakdowns for both credits and contributions.

"partnerRates": {
  "credits": [
    {
      "partnerId": "250636c2-8702-47c1-9720-7c3f93395790",
      "rates": { "impact": 0.5, "impactTax": 0.0, "serviceFee": 0.2, "serviceFeeTax": 0.2 }
    }
  ],
  "contribution": [
    {
      "partnerId": "9405545f-a850-4427-ab0d-10b5b734e925",
      "rates": { "impact": 0.5, "impactTax": 0.0, "serviceFee": 0.2, "serviceFeeTax": 0.2 }
    }
  ]
}

Tax handling

The correct tax jurisdiction and rates are determined by ekko based on the merchant and consumer locations. You don't need to calculate tax yourself. The breakdown fields in the response exist to support jurisdictions where sales tax must be displayed to consumers.