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 asynchronously. Use the /estimates/transaction-documents/async endpoint to calculate emissions for transaction documents. 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.

Payload limit: 100kB.Exceeding this limit? Include only essential data:

Invoice context: payer/payee addresses, vendor name, business industry, totals, currency
Line items: description and costs

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 async request

API response

After submitting your request, you'll receive an immediate response:

204 No Content: Your request was accepted and is being processed
400 Bad Request: There was a validation error with your request (check the error details in the response body)

The actual emission calculation results will be delivered via webhook when processing is complete.

Understanding the async process

When you submit a transaction document for processing, the following happens:

Request Submission: Your API request is received and queued for processing
Immediate Response: You receive a 204 No Content response indicating the request was accepted
Document Processing: Lune processes the document to extract transaction details and calculate emissions
Webhook Notification: When processing is complete, Lune sends a webhook to your configured endpoint
Response Handling: Your webhook receiver processes the response containing the emission estimates

Webhook Setup Required: You must configure a webhook receiver to receive the processing results. See our webhooks guide for setup instructions, including authentication and integrity verification.

Webhook event types

Transaction document processing generates the following webhook events:

transaction_document.success: The document was successfully processed and emission estimates are available
transaction_document.error: There was an error processing the document

For detailed information about webhook setup, authentication, and event handling, see our webhooks guide. This includes:

4. Interpret the webhook results

When processing is complete, you'll receive a webhook notification containing:

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 described in this guide. passenger_transportation and activity estimates are also supported.Filter out non-transaction type estimates if you only spend-based estimates are of interest.

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.

Webhook response for transaction document request

Webhook payload structure

The webhook payload contains the following fields:

mass

The total emissions calculated for the entire document, including unit and amount.

line_items

Array of emission calculations for each line item in the document.

id

Unique identifier for the emission estimate.

request

The original request data that was submitted.

metadata

Additional metadata associated with the estimate.

is_transaction_document

Boolean indicating if this was processed as a transaction document.

transaction_document_processed_at

Timestamp when the document was processed.

Line item structure

Each line item in the line_items array contains:

item

The description of the item as extracted from the document.

mass

Emissions calculated for this specific line item.

type

Type of emission calculation (e.g., 'transaction').

value

The monetary value and currency of the line item.

category

The category assigned to this line item.

emission_factor

The emission factor used for the calculation.

Handling webhook responses

Your webhook receiver should handle both success and error events:

Success event (`transaction_document.success`)

Success event (`transaction_document.error`)

Error payload structure

When a transaction_document.error event is received, the payload contains:

error

The error code indicating what went wrong during processing.

message

Human-readable description of the error.

Common error codes:

transaction_document_inference_failure: Could not extract required information from the document
transaction_document_creation_failure: Information was extracted but could not be matched to emission factors

Error handling best practices

Always return a 2xx status code to acknowledge webhook receipt
Handle duplicate events by checking the event_id field
Process events in order using the sequence field
Implement retry logic for transient failures

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.