Fulfillment with API

Direct integration

The following integration doc details how to perform the following steps with the SQUAKE API in order to:

• [optional] calculate emissions, for example using SQUAKE's API

• [optional] pick a carbon product provided by SQUAKE

• quote pricing for the carbon emissions you want to compensate

• request a purchase

• settle payment

• [optional] track your compensation's lifecycle

Emission Calculation

[optional] skip this step, if you already know the carbon emissions to compensate for.

SQUAKE offers a wide variety of emission calculations using industry standards and externally certified algorithms to determine emissions for various activities such as hotel stays, flights, freight, and so forth.

The calculation step is optional; with SQUAKE, you can also compensate for any carbon amounts provided by you.

For example, request the emissions for a as follows:

curl -X POST
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/purchases \
     -d {} # see below for the request body

// request body for POST /calculations

{
  "items": [
    {
      "type": "air_freight",
      "methodology": "GLEC",
      "parameters": {
        "origin": "FRA",
        "destination": "SFO",
        "weight_in_tonnes": 7
      },
      "metadata": {
        "flight_number": "LH123"
      }
    },
    {
      "type": "air_freight",
      "methodology": "GLEC",
      "parameters": {
        "origin": "SFO",
        "destination": "FRA",
        "weight_in_tonnes": 11
      },
      "metadata": {
        "flight_number": "LH321"
      }
    }
  ],
  "expand": [
    "items"
  ]
}

The response includes the emissions as follows:

{
  "total_carbon_quantity": 7,
  "carbon_unit": "tonne",
  "emissions_per_item": [
    {
      "carbon_quantity": 3,
      "carbon_unit": "tonne",
      "metadata": {
        "flight_number": "LH123"
      },
      "type": "air_freight",
      "methodology": "GLEC"
    },
    {
      "carbon_quantity": 4,
      "carbon_unit": "tonne",
      "metadata": {
        "flight_number": "LH321"
      },
      "type": "air_freight",
      "methodology": "GLEC"
    }
  ]
}

NOTE: The calculation endpoint is stateless; hence SQUAKE does not return a unique identifier for a specific calculation. Please store the carbon quantity and carbon unit for a later purchase.

Define a product to use for emission compensation

[optional] SQUAKE allows you to define a default product that will be used if do not choose any.

SQUAKE offers many products which may contribute to one or several certified climate projects from any of our partners. We are happy to help you to assemble a reference product that fits your vision. Furthermore, SQUAKE offers reference products for various pre-defined categories, such as technology-focused projects with an immediate and direct impact.

If you want a custom reference product, please contact sales. Else, you can list all products available via a GET request to choose one:

curl -X GET
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/projects

Take note of the returned ID in the format of product_[A-Za-z0-9]* for later purchases.

Pricing

[optional] A stateless endpoint to retrieve a preview on the price, for example to display it to an end-customer. No purchase obligation.

Once you know the carbon amount you want to offset, you can request pricing for that, making a GET request to the /pricing endpoint.

Given a price, you could calculate the amount yourself. Using the pricing endpoint, however, guarantees you consistent results. This endpoint is stateless and merely for your information or to inform your customer.

It is enough to fetch a pricing once per product; you can show the same pricing to each customer as long as the pricing is still valid.

curl -X GET
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/pricing \
     -d product=product_sdf2lka234fj \
     -d carbon_quantity=34 \
     -d carbon_unit=tonne \
     -d price_currency=USD

If you do not have a specific carbon amount but instead a fixed amount of money you want to contribute, the same endpoint can be used as follows:

curl -X GET
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/pricing \
     -d product=product_sdf2lka234fj \
     -d price_unit_amount=85000 \
     -d price_currency=USD

In both cases, the price and carbon amount compensatable are returned in the response:

{
  "price": "price_a5808f78cf1a8",
  "product": "product_17d65a66e9d41",
  "valid_from": "2022-08-13T17:43:23Z",
  "valid_until": "2022-08-13T17:43:23Z",
  "unit_amount": 34,
  "unit": "tonne",
  "amount": 85000,
  "currency": "USD"
}

Purchase

You, merchant or platform (on behalf of a merchant), registers a purchase for carbon offsets.

Request a purchase for a given quantity of carbon emissions. SQUAKE supports various currencies; find an extensive list in the API documentation.

curl -X POST
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/purchases \
     -d product=product_sdf2lka234fj \
     -d currency=USD
     -d carbon_quantity=34 \
     -d carbon_unit=tonne \
     -d certificate_document={} \ # [optional] data for a certificate
     -d metadata={} # [optional] arbitrary key-value pairs for your convenience

Please refer to the API documentation for a complete reference of all possible parameters.

Please note the ID from the response (see below).

{
  "id": "purchase_sd234asdfl23",
  "files": [
    "file_34sdfgJH9df4g35" // e.g., a confirmation PDF, if requested
  ],
  "payment_method": "batch_settlement",
  "state": "processing",
  "metadata": null,
  "next_action": null
}

In the most simple case, the lifecycle of a purchase is

(1) processing: you have successfully registered a purchase via the above-mentioned API call. (2) succeeded: SQUAKE has successfully invoiced this purchase from you.

Refund

You can refund purchased offsets within a refundable period (typically 14 days) using the /refund endpoint.

curl -X POST
     -H 'Accept: application/json' \
     -H "Authorization: Bearer $TOKEN" \
     -G https://api.squake.earth/v2/refunds \
     -d purchase=purchase_54a087f342e1 \
     -d description='short user-facing description for context' \
     -d metadata={} # arbitrary key-value pairs for your convenience

A refund object is returned:

{
  "id": "refund_abd349usflk43",
  "amount": 1753,
  "currency": "EUR",
  "metadata": null,
  "status": "pending",
  "description": "short user-facing description for context",
  "purchase": "purchase_54a087f342e1"
}

A refund has the following lifecycle states:

• pending: you have initiated the refund

• succeeded: SQUAKE has accepted and initiated the refund

• failed: the automated refund was rejected (e.g., performed outside the refundable period, Please contact us if needed).

• requires_action: further steps might be necessary due to, for example, legal reasons in some cases

• canceled: you –or you and SQUAKE mutually– have agreed to cancel the refund. In this case, the purchase will be settled through SQUAKE as usual.

Settlement

After the purchase is made and the refundable period has passed, SQUAKE will settle the required carbon credits. SQUAKE updates you on the entire process via its trust page. SQUAKE can also send the reference ID for the trust page directly to your customer via email.