Share your climate impact

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 set up a public sustainability page to:

• Share your climate impact
• Enable your clients to share their climate impact

A sample Sustainability page can be seen here.

Who is this guide for?

This guide is aimed at heads of Sustainability or Growth Specialists to manage their Sustainability page via the Lune dashboard and developers looking to automatically integrate sustainability pages into an existing end-user experience.

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

Concepts

• Beneficiary - Legal entity that can claim the offsetting benefits and is listed in the official public registry
• Certificate - Proof of retired carbon credits in the beneficiary's name. Can be used in Net Zero audits
• Client account - Customers that wish to provide a Sustainability page to their clients must create a client account for each client to define their basic characteristics, such as name, currency, and beneficiary

A few words about certificates

Certificates contain links to the official entry in the registry's retirement ledger.

The account's beneficiary is the entity in the certificate and the registry claiming the offsetting benefits.

A certificate may list credits as:

• Retired - the carbon credits have been fully retired
• Allocated, pending retirement - the carbon credits have been purchased but cannot be retired yet.

Create a Sustainability page for your account

Head over to the Lune dashboard.

1. Navigate to https://dashboard.lune.co/share-your-impact

2. Create or edit the page's public URL. The public URL may be changed if not already taken

3. Decide what title, description, and sections you'd like to display. You may opt to display your own description if you prefer

4. Click Save to publish the Sustainability page

A Sustainability page is always linked to an account or client account.

A Sustainability page is created by default on an account's first order.

You may disable the page if you do not wish to share your impact.

Create a Sustainability page for your clients

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

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
}

Create the Sustainability page

You can create the Sustainability page via the API.

A Sustainability page is created by default on an account's first order.

When using Client Accounts, store the Sustainability page's slug in your database to point your clients to the page.

Sample request

Where:

• $CLIENT_ACCOUNT_ID is the unique identifier for the client account
• slug is the globally unique slug to append to https://sustainability.lune.co/

Sustainability pages for test accounts include a /test/ prefix before slug.

Sample response

A 200 response code confirms the Sustainability page has been created. A 409 response code is returned when:

• A Sustainability page already exists
• The slug is not available

Sample request

curl https://api.lune.co/v1/sustainability-pages \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID" \
  -X POST \
  -d '
    {
      "status": "enabled",
      "slug": "acme",
      "title": "by_volume",
      "description": "by_equivalent"
      "sections": [
        "bundles_breakdown",
        "certificates",
        "unsdg"
      ],
    }'

Sample response

{
  "title": "by_volume",
  "sections": [
    "bundles_breakdown",
    "certificates",
    "unsdg"
  ],
  "slug": "acme",
  "status": "enabled",
  "description": "by_equivalent"
  "custom_description": null
}

Update a Sustainability page

You can also update a Sustainability page via the API.

Sample request

Use a PUT request and the payload used to create a Sustainability page.

Sample response

A 200 response code confirms the Sustainability page has been updated. A 409 response code is returned when slug is not available.

Sample request

curl https://api.lune.co/v1/sustainability-pages \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID" \
  -X PUT \
  -d '
    {
      "status": "enabled",
      "slug": "acme",
      "title": "by_volume",
      "description": "by_equivalent"
      "sections": [
        "bundles_breakdown",
        "certificates",
        "unsdg"
      ],
    }'

Sample response

{
  "title": "by_volume",
  "sections": [
    "bundles_breakdown",
    "certificates",
    "unsdg"
  ],
  "slug": "acme",
  "status": "enabled",
  "description": "by_equivalent"
  "custom_description": null
}

Get a Sustainability page

You can retrieve a Sustainability page via the API.

Sample request

Where:

• $CLIENT_ACCOUNT_ID is the unique identifier for the client account

Sample response

A 404 response code is returned when the Sustainability page has not been created.

Sample request

curl https://api.lune.co/v1/sustainability-pages/current-account \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Lune-Account: $CLIENT_ACCOUNT_ID"

Sample response

{
  "title": "by_volume",
  "sections": [
    "bundles_breakdown",
    "certificates",
    "unsdg"
  ],
  "slug": "acme",
  "status": "enabled",
  "description": "by_equivalent"
  "custom_description": null
}