Green spend management

The Lune API and our approach

Lune provides a single API for use in-app and web channels to fetch, mutate, and deliver the data necessary to offset CO₂ emissions across a range of verticals.

Our API-first approach allows our customers to embed carbon offsetting and emission calculations into logistics, payments, and fintech platforms to deliver a unique and programmatically driven experience that brings climate into our clients' products.

Overview

In this guide, you will learn how to interact with the Lune API to:

Calculate emissions for financial transactions
Offset those emissions.

Who is this guide for?

This guide is primarily aimed at Product Managers and developers looking to integrate CO₂ emissions estimations and offsetting into an existing end-user experience.

Feel free to contact our support team if you encounter any issues integrating our spend management use case.

Concepts

Client account - You can optionally create a client account for each of your clients to define their basic characteristics, such as name, currency, and beneficiary. Clients will be provided a Lune defaults
Lune defaults - Lune has provided a default Project bundle for each of our clients. Every order will be placed against the following projects and ratios:
- Conserving forests in Asia - 95%
- Ocean Carbon Removal - 5%
Project bundle - Group of offsetting projects with similar characteristics., e.g., Conserving forests in Asia and Ocean Carbon Removal

spend-management-dashboard

API flow

fintech-apiflow

Getting an API key

First, head over to the Lune dashboard and generate a new API key.

Navigate to https://dashboard.lune.co/developers
Select New Test API Key, enter a value in the Name field, and select an account from Default account
Select Save
Copy your API key, as you'll need it to interact with the Lune API

apikey

Create a client account

A client account is required for each of your clients and defines their basic characteristics, for example, the currency used to display emission offsetting prices.

Store and map the client account id to your client in your database.

Client accounts are optional but recommended for B2B businesses and discouraged for B2C businesses. Learn about their benefits and how to use either.

Sample request

You can optionally pass in beneficiary to link a client account to the legal entity receiving the carbon offset.

Sample response

A successful request will return a unique id, which you will need to pass in later interactions with the Lune API.

Where:

id is the unique identifier for each of your clients, which you must map in your code base
name is a name that you will use to identify your client and present offsetting options to
currency defines the currency used to display the price for each offsetting option
type defines the type of account. Use test for your playground
beneficiary is the legal entity shown on the Carbon Offset Certificate and carbon registries

Following a successful response, a client account will be added to your dashboard:

You can access the dedicated client account page by appending the id to /client-account e.g., https://dashboard.lune.co/settings/client-accounts/K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb.

Sample request

curl "https://api.lune.co/v1/accounts/client" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MY TEST COMPANY",
      "currency": "USD",
      "beneficiary": "MY TEST COMPANY INC"
    }'

Sample response

{
  "id": "K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb",
  "name": "MY TEST COMPANY",
  "currency": "USD",
  "balance": "0",
  "balance_outstanding": "0",
  "type": "test",
  "scope": "client_account",
  "beneficiary": "MY TEST COMPANY INC",
  "organisation_id": "42O097M13DKvo5pmlJYZjmVlGzqJwXbE",
  "bundle_portfolio_id": null,
  "logo": null
}

new-client-account

Calculate emissions for transactions

To calculate an estimate of CO₂ emissions for up to 100 transactions, pass in the transaction amount, the MCC (Merchant Category Code), and Merchant country for each transaction.

As product input you can use MCC (eg "category_code": "5411") or free text search (eg "search_term": "iphone").

To prevent batch failure, each transaction is processed individually.

Within the response, any failed transactions will be returned with an error code and message.

Sample request

Where:

$CLIENT_ACCOUNT_ID is the unique identifier for the client
value.value defines the shipment load; in this example, 40 tonnes
value.currency is the currency in which the transaction was completed
merchant.category_code is the Merchant Category Code (MCC) used to classify the type of goods and services that are transacted
merchant.name is the name of merchant in the transaction
merchant.country_code is the 3-character (ISO 3166) country code for the country in which the transaction was completed

Sample response

A successful 200 response will result in an estimate of CO₂ emissions for each transaction, which can be presented in-app.

The following example shows the CO₂ emissions estimate for one of the three transactions from the request above.

Where:

mass.amount is the calculated amount of CO₂ emissions for the transaction
mass.unit is the mass unit
quote.bundles is a container object for the Project bundles that will be used to offset the emissions associated with the transaction and includes the bundle id, bundle name, and unit price
quote.estimated_total_cost is the total cost of offsetting the CO₂ emissions for that transaction in the client's currency

Calculate the sum of emissions from the transaction response and store it. This is the amount that will need to be offset in the next request.

Convert mass.amounts to the same unit before summing.

Sample request

curl https://api.lune.co/v1/estimates/transactions/batch \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID" \
  -X POST \
  -d '[
    {
      "value": {
        "value": "8.99",
        "currency": "USD"
      },
      "merchant": {
        "category_code": "5411",
        "name": "Starbucks",
        "country_code": "USA"
      }
    },
    {
      "value": {
        "value": "120",
        "currency": "USD"
      },
      "merchant": {
        "category_code": "3001",
        "name": "British Airways",
        "country_code": "USA"
      }
    },
    {
      "value": {
        "value": "8.99",
        "currency": "USD"
      },
      "merchant": {
        "category_code": "5818",
        "name": "Netflix",
        "country_code": "USA"
      }
    }
  ]'

Sample response

[
  {
    "mass": {
      "unit": "t",
      "amount": "0.01388"
    },
    "quote": {
      "bundles": [
        {
          "quantity": "0.013186",
          "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
          "unit_price": "12.8",
          "bundle_name": "Conserving forests in Asia",
          "offset_cost": "0.17",
          "gross_unit_price": "14.22",
          "insufficient_available_quantity": null
        },
        {
          "quantity": "0.000694",
          "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
          "unit_price": "250",
          "bundle_name": "Ocean Carbon Removal",
          "offset_cost": "0.17",
          "gross_unit_price": "277.78",
          "insufficient_available_quantity": null
        }
      ],
      "currency": "USD",
      "requested_value": null,
      "estimated_quantity": "0.01388",
      "requested_quantity": "0.01388",
      "estimated_commission": "0.04",
      "estimated_total_cost": "0.38",
      "estimated_offset_cost": "0.34"
    },
    "id": "0M3zv7Qr2OGRqY9QVoEYVdbwKPx5XWao",
    "request": {
      "value": {
        "value": "8.99",
        "currency": "USD"
      },
      "merchant": {
        "category_code": "5411",
        "name": "Starbucks",
        "country_code": "USA"
      }
    }
  }
]

spend-management-transactions

Displaying emissions and the cost

To display the emissions which have not yet been offset and the cost, pass in the calculated sum of emissions.

Sample request

Where:

mass.amount is the total amount of CO₂ emissions for the transactions to be offset
mass.unit is the mass unit

Sample response

A successful 200 request will return the total cost of offsetting the CO₂ emissions, along with options for offsetting (Lune defaults) which can be presented in-app:

Where:

estimated_total_cost is the total cost of offsetting the CO₂ emissions in the client's currency
bundles is a container object for the Project bundles that will be used to offset the emissions associated with the transactions and includes the bundle id, bundle name, and unit price

Sample request

curl https://api.lune.co/v1/orders/by-mass/quote \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID" \
  -X POST \
  -d '{
    "mass": {
      "amount": "259.111",
      "unit": "kg"
    }
  }'

Sample response

{
  "currency": "USD",
  "estimated_quantity": "0.25911",
  "estimated_offset_cost": "6.39",
  "estimated_total_cost": "7.1",
  "estimated_commission": "0.71",
  "requested_quantity": "0.259111",
  "requested_value": null,
  "bundles": [
    {
      "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
      "bundle_name": "Conserving forests in Asia",
      "quantity": "0.246155",
      "unit_price": "12.8",
      "gross_unit_price": "14.22",
      "offset_cost": "3.15",
      "insufficient_available_quantity": null
    },
    {
      "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
      "bundle_name": "Ocean Carbon Removal",
      "quantity": "0.012955",
      "unit_price": "250",
      "gross_unit_price": "277.78",
      "offset_cost": "3.24",
      "insufficient_available_quantity": null
    }
  ]
}

spend-management-offsetnow

Offset emissions

To offset emissions, pass in the calculated sum of emissions.

Sample request

Where:

mass.amount is the total amount of CO₂ in tonnes to offset
mass.unit is the mass unit

Sample response

Where:

id is the unique identifier for the booking
idempotency_key is a unique token that you submit as a request header, that guarantees that only one order will be created regardless of how many times a request is sent to us
statusis the order status. placed means the order has been validated, accepted and will be fulfilled
offset_cost is the cost of purchasing the offsets
total_cost is the total cost of purchasing the offsets, including Lune's fee
commission is Lune's fee
quantity is the total quantity of offsets purchased, expressed in tonnes
bundles.bundle_id are the Lune default project bundles against which CO₂ emissions will be offset

Sample request

curl https://api.lune.co/v1/orders/by-mass \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID" \
  -X POST   -d '{
  "mass": {
    "amount": "259.111",
    "unit": "kg"
  }
}'

Sample response

{
  "id": "dk23N8xjQLEnvY0XPgbYgX79RB4zDKOl",
  "metadata": {},
  "idempotency_key": null,
  "type": "quantity",
  "status": "placed",
  "currency": "USD",
  "offset_cost": "6.54",
  "total_cost": "7.27",
  "commission": "0.73",
  "quantity": "0.25911",
  "created_at": "2022-11-17T18:05:04.057Z",
  "bundles": [
    {
      "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
      "bundle_name": "Conserving forests in Asia",
      "quantity": "0.246155",
      "unit_price": "13.39",
      "gross_unit_price": "14.88",
      "offset_cost": "3.3",
      "insufficient_available_quantity": null
    },
    {
      "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
      "bundle_name": "Ocean Carbon Removal",
      "quantity": "0.012955",
      "unit_price": "250",
      "gross_unit_price": "277.78",
      "offset_cost": "3.24",
      "insufficient_available_quantity": false
    }
  ],
  "projects": [],
  "certificate": null,
  "offset_link_id": null,
  "email": null,
  "estimate_id": null,
  "requested_quantity": "0.259111",
  "requested_value": null
}

spend-management-confirmation

Green spend management

The Lune API and our approach​

Overview​

Who is this guide for?​

Concepts​

API flow​

Getting an API key​

Create a client account​

Sample request​

Sample response​

Calculate emissions for transactions​

Sample request​

Sample response​

Displaying emissions and the cost​

Sample request​

Sample response​

Offset emissions​

Sample request​

Sample response​

The Lune API and our approach

Overview

Who is this guide for?

Concepts

API flow

Getting an API key

Create a client account

Sample request

Sample response

Calculate emissions for transactions

Sample request

Sample response

Displaying emissions and the cost

Sample request

Sample response

Offset emissions

Sample request

Sample response