Skip to main content

1-step integration

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​

This guide is designed to help you get started with the Lune API. It is suitable for both consumer and eCommerce apps.

In this guide, you will learn how to use a single API call to:

  • Offset your product
  • Round up — contribute your spare change toward carbon removal

  • Feel free to implement the examples in this guide or make your own.

    • Who is this guide for?​

    This guide is primarily aimed at developers looking to integrate CO₂ removal into an existing end-user experience.

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

    Concepts​

    • 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

    Getting an API key​

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

    1. Navigate to https://dashboard.lune.co/developers

    2. Select New Test API Key, enter a value in the Name field, and select an account from Default account

    3. Select Save

    4. Copy your API key, as you'll need it to interact with the Lune API

    apikey

    Offset your product​

    API flow​

    api-flow

    Estimate your product's emissions​

    Calculate your product's emissions using your preferred provider or Lune's dashboard

  • For each product, store its emissions in your database.

    • offsetting-decision

    Offsetting emissions​

    On successful checkout, place an order by mass.

    Sample request​

    Where:

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

    Sample response​

    A 200 response code confirms the order has been successfully placed.

    Where:

    • id is the unique identifier for the booking
    • status is the order status. placed means the order has been validated and 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" \
  -X POST \
  -d '
    {
      "mass": {
        "amount": "12.07"
        "unit": "kg"
      }
    }'
  • Sample response
    • {
  "id": "VfdoQ0PZjGMzvYO46lNA6kbgN1eOJx9B",
  "metadata": {},
  "idempotency_key": null,
  "type": "quantity",
  "status": "placed",
  "currency": "USD",
  "offset_cost": "0.31",
  "total_cost": "0.35",
  "commission": "0.04",
  "quantity": "0.012069",
  "created_at": "2023-01-04T15:00:27.349Z",
  "bundles": [
    {
      "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
      "bundle_name": "Conserving forests in Asia",
      "quantity": "0.011466",
      "unit_price": "13.57",
      "gross_unit_price": "15.08",
      "offset_cost": "0.16",
      "insufficient_available_quantity": null
    },
    {
      "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
      "bundle_name": "Ocean Carbon Removal",
      "quantity": "0.000603",
      "unit_price": "250",
      "gross_unit_price": "277.78",
      "offset_cost": "0.15",
      "insufficient_available_quantity": false
    }
  ],
  "projects": [],
  "certificate": null,
  "offset_link_id": null,
  "email": null,
  "estimate_id": null,
  "requested_quantity": "0.01207",
  "requested_value": null
}

    Round up​

    API flow​

    api-flow

    Calculate carbon removal contribution​

    Calculate the amount required to round up your checkout cost to the nearest unit.

    payments-intro

    Offsetting emissions​

    On successful checkout, place an order by value.

    Sample request​

    Where:

    • value is the rounded-up carbon removal contribution

    Sample response​

    A 200 response code confirms the order has been successfully placed.

    Where:

    • id is the unique identifier for the booking
    • status is the order status. placed means the order has been validated and 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-value \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -X POST \
  -d '
    {
      "value": "0.54"
    }'
  • Sample response
    • {
  "id": "2718zf6QGj9xMpwWKMbp2wrVXaK14OJq",
  "metadata": {},
  "idempotency_key": null,
  "type": "value",
  "status": "placed",
  "currency": "USD",
  "offset_cost": "0.49",
  "total_cost": "0.54",
  "commission": "0.05",
  "quantity": "0.019137",
  "created_at": "2023-01-04T15:19:06.280Z",
  "bundles": [
    {
      "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
      "bundle_name": "Conserving forests in Asia",
      "quantity": "0.018181",
      "unit_price": "13.57",
      "gross_unit_price": "15.08",
      "offset_cost": "0.25",
      "insufficient_available_quantity": null
    },
    {
      "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
      "bundle_name": "Ocean Carbon Removal",
      "quantity": "0.000956",
      "unit_price": "250",
      "gross_unit_price": "277.78",
      "offset_cost": "0.24",
      "insufficient_available_quantity": false
    }
  ],
  "projects": [],
  "certificate": null,
  "offset_link_id": null,
  "email": null,
  "estimate_id": null,
  "requested_value": "0.54",
  "requested_quantity": null
}