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 theunstructured_data
property, with a key_value
object:
unstructured_data.key_value
name
is_transaction_document
transaction_document_processed_at
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.
Sample Request
The request includes unstructured data from an actual invoice, as well as a generatedname
input to allow for easier reconciliation of the transaction in the your system.
API response
After submitting your request, you'll receive an immediate response:204 No Content
: Your request was accepted and is being processed400 Bad Request
: There was a validation error with your request (check the error details in the response body)
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 event types
Transaction document processing generates the following webhook events:transaction_document.success
: The document was successfully processed and emission estimates are availabletransaction_document.error
: There was an error processing the document
- Setting up webhook receivers
- Registering webhooks with Lune
- Authenticating webhook requests
- Handling webhook events
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 amass
for the emissions calculated for that item, and theemission_factor
used to calculate the estimate.
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 payload structure
The webhook payload contains the following fields:mass
line_items
id
request
metadata
is_transaction_document
transaction_document_processed_at
Line item structure
Each line item in theline_items
array contains:item
mass
type
value
category
emission_factor
Handling webhook responses
Your webhook receiver should handle both success and error events:
Error payload structure
When atransaction_document.error
event is received, the payload contains:error
message
transaction_document_inference_failure
: Could not extract required information from the documenttransaction_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