Transaction documents

Use documents, such as receipts, and invoices, to calculate the CO₂e emissions of transactions with Lune.

Pre-requisites

Complete the following setup steps before using this guide:

Generate an API key and authenticate your account.

Set up Client Accounts to track emissions for your individual customers.

Review how to calculate emissions for individual transactions using the API.

1. Extract transaction documents

The first step is extracting data from any documents that contain useful information into a key-value pair format.While Object Character Recognition (OCR) software is commonly used to extract data from documents, you can use any method of your choice. The extracted data must be formatted as JSON, with no predefined schema requirements. Lune will process this input to determine the transaction details.If multiple data sources reference the same transaction, they can be combined to build a more comprehensive unstructured data object.

Lune is optimised to work with outputs from OCR software like Mindee but can process any unstructured data submitted.

2. Build the document request

At minimum, the request must include the unstructured_data property, with a key_value object:

Unstructured data input

You can also add optional structured inputs. See a list of recommended inputs below.

unstructured_data.key_value

Required. The transaction document in JSON format. Must include a country, a total amount and currency, an overall category. Each line item must include a description, category, amount, and currency.

name

Optional. Identification you can generate for the request to make it easier to reconcile it in your systems. Will be generated for you if not provided.

is_transaction_document

Optional. Set this property to true for a processed transaction document. If the calculation is for a quote or forecast, set it to false.

transaction_document_processed_at

Optional. Provide this property as the date and time of processing for the document in RFC 3339 format. This will improve reporting accuracy.

To see all available properties, go to the API reference.

3. Make the API request

The API processes one transaction per request. Use the estimates/transaction-documents/ endpoint to calculate emissions for several transactions. Send a POST request to this endpoint to create the estimate.

Include the Authorization header with your API Key as a Bearer Token. To associate the emission calculation with a specific client account, add either a Lune-Account header or a client account object to your request.

Sample Request

The request includes unstructured data from an actual invoice, as well as a generated name input to allow for easier reconciliation of the transaction in the your system.

Transaction document request

Requests can also be made asynchronously with a POST request to the /v1/estimates/transaction-documents/async endpoint. When processing is complete, you'll recieve a notification through a webhook. See our guide to learn how to set up the webhook for your asyncronous transaction document processing.

4. Interpret the results

The API response contains:

Emission calculation for the document: Refer to the mass property of the results.
Interpretation of detected items: The line_items property shows how Lune interpreted each line item. Additionally, each line item includes a mass for the emissions calculated for that item, and the emission_factor used to calculate the estimate.

We recommend manually reviewing the line_items property to verify accuracy the first few times you use this request. If anything looks unexpected, get in touch - we are continually improving our data interpretation algorithms.

Currently, only transaction type estimates are available. Future updates will include activity-based emissions (for example, use of sheets of A4 paper).

Sample response

See the sample response below for a transaction document. The total emissions calculated for the document is 1.12 tonnes CO₂e. The document contained two line items, an office chair and standing desk. These line items emitted 0.51 and 0.61 tonnes of CO₂e respectively.

Response for transaction document request

Success! Each transaction analysed brings us closer to a more sustainable future.

What to do next...

Now that you have your estimate, there are several actions you can take!

Offset the calculated emissions by purchasing carbon credits through the API.

Generate an analytics report for your customers about their emissions.

Troubleshooting

If you receive a 422 status code, it could mean one of the following issues has occurred:

transaction_document_inference_failure

The relevant information could not be extracted from the unstructured data. Please ensure the data includes a country, a total amount and currency, and an overall category. Each line item must include a description, category, amount, and currency.

transaction_document_creation_failure

The relevant information was properly extracted, but one or more of the line items could not be matched to an emission factor meaning an emission calculation could not be completed.