Upload shipments for emissions reporting
Upload up to 1,000 shipments for emissions reporting in one API request. You can use your own emissions data, request Lune calculations during upload, or request calculations later.Pre-requisites
Complete the following setup steps before using this guide:
Generate an API key and authenticate your account.
Set up the account that will own the shipments and their emission estimates.
1. Upload shipments
Send aPOST request to the upload a batch of shipments endpoint. The shipments array accepts between 1 and 1,000 shipments, and each shipment's legs array must contain between 1 and 10 legs.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.
contact_id, or set it for each shipment with target_internal_id and target_internal_name. This example sets the counterparty for each shipment with target_internal_id and target_internal_name.Choose when to calculate emissions
Usecalculate_emissions to choose between two viable paths:truefalse or omittedemissions object on the shipment and either omit calculate_emissions or set it to false. If you set calculate_emissions to true, Lune schedules a calculation after the batch has been processed. Provide total_emissions and distance_km; you can also provide the wtt and ttw breakdown. All emission values are in kilograms. Lune sets the shipment's emissions_source to manual, which the get and list shipment endpoints return to your application. See the shipment batch request schema for the complete contract.id. Save it because you will use it to check processing and select the resulting shipments. If you set calculate_emissions to true, continue to Step 2 and then Step 4. If you set it to false, continue to Step 2, then either use your own emissions or request calculations in Step 3.2. Poll shipment processing
Uploading a batch starts asynchronous processing. Poll the get a shipment batch endpoint with the batchid until status is processed.There are currently no webhook events for successful shipment processing or successful emission calculations. You must poll for shipment processing, and when you request Lune calculations, you must also poll for emissions.
pending, processing, and processed. When it is processed, check for a batch-level batch_error. Otherwise, inspect success_count, failed_count, and each item in results.Save the shipment_id from every result with a status of success. In a batch result, this field contains the Lune-generated shipment identifier used by the other shipment endpoints. A failed result instead contains an error and its zero-based row_index in your original request.Do not confuse the
shipment_id in a batch result with the required, customer-provided shipment_id used elsewhere in the API. Only the batch result uses shipment_id for the Lune-generated identifier.3. Request calculations for uploaded shipments
Use this path when the shipments were uploaded withcalculate_emissions set to false or omitted, and you later want Lune to calculate their emissions.Send a POST request to the calculate shipments endpoint. Use the id query parameter to select a successfully processed shipment, and repeat the parameter to select more than one shipment. To request calculations for every shipment from one upload, use its batch id as the shipment_batch_id query parameter.calculation_batch_ids, but the API does not currently provide an endpoint for retrieving their status. Poll the shipments themselves to determine when their emissions are available.4. Poll for emissions
Poll the get a shipment endpoint for each successfulshipment_id. The calculation is complete when estimate_id is not null. You can then read total_emissions, wtt, ttw, and the calculated values for each leg. Emissions values are returned as strings in kilograms.shipment_batch_id to retrieve the shipments together. The emissions filter can select shipments with or without calculated CO₂e values.A null estimate_id means calculated emissions are not available. The API does not currently distinguish a calculation that is still running from one that failed. If estimate_id remains null after your polling timeout, contact Lune support with the shipment and calculation batch identifiers.
