Getting Started with the EcoCart API

What is the EcoCart API?

The EcoCart API provides a calculation engine that generates emissions (e.g. kg of CO2e) and offset amounts (e.g. USD, EUR, etc.) for a given E-Commerce transaction.

How Does it Work?

Once your E-Commerce store has been onboarded onto the EcoCart system, this API will be ready to be integrated into your E-Commerce cart/checkout workflow.

Authentication

EcoCart will provide an API Key. Please include it in all HTTP requests in the header like the below example:

'X-ECO-KEY': 'Bearer {API_KEY}'

Creating a calculation

To create a generic E-Commerce Calculation, please reference the /offset/calculation/ecommerce POST endpoint.

If the response was successful and a 201 was returned, the information included in the response body can be used to display the information to a given user. Some useful pieces of information include:

• identifier: used to confirm the order in a subsequent PUT request.
• emissions_total: the total estimated emissions amount for the given order. Includes both the manufacturing and shipping emissions.
• offset_cost_total: the total dollar amount to offset the calculated emissions amount.

If a customer updates their cart information, simply make a subsequent POST request to re-calculate the emissions amount.

If you are on a merchant_payor payor mode (i.e. the customer doesn't have to opt into the offset amount), you can make a single POST request at the end of the order workflow instead of requiring to make multiple calculations.

Confirming a calculation

When calculations are created, they are by default not confirmed. Thus, you must explicitly confirm an order with a subsequent request at the /offset/calculation/{identifier} PUT endpoint.

After you have made a successful POST request in the above step, using the identifier in the response body, you can set the order_confirmed property to true to ensure that the order will be offset. Once this property is set, this transaction will be included in your next invoice.