Lune Docs Logo
Log inContact us

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:
/illustrations/stamp-key.png
Generate an API key and authenticate your account.
/illustrations/stamp-accounts.png
Set up Client Accounts to track emissions for your individual customers.
/illustrations/stamp-shopping.png
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.
  • 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:
    1. Request Submission: Your API request is received and queued for processing
    2. Immediate Response: You receive a 204 No Content response indicating the request was accepted
    3. Document Processing: Lune processes the document to extract transaction details and calculate emissions
    4. Webhook Notification: When processing is complete, Lune sends a webhook to your configured endpoint
    5. 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!