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 the shipment batch. If calculations are scheduled, you must then poll each calculation batch.
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 id from every result with a status of success. This Lune-provided shipment ID is distinct from the shipment_id in your request and is used by the other shipment endpoints and to match later calculation results. A failed result instead contains an error and its zero-based row_index in your original request.The response also contains calculation_batch_id, which identifies the most recently scheduled calculation batch for this shipment batch, or is null when none has been scheduled.When you upload with calculate_emissions set to true, save this ID for Step 4. If it is null after the shipment batch is processed, poll the shipment batch with the same bounded backoff and timeout. Stop immediately if batch_error is present, because Lune will not schedule a calculation. If the ID is still null when your timeout expires, contact Lune support with the shipment batch identifier.If you request further calculations in Step 3, calculation_batch_id changes to the ID of the most recently scheduled calculation batch. Retain any IDs you still need to poll.calculation_batch_id set to null because its upload request sets calculate_emissions to false. When it is set to true, Lune populates the field after scheduling, for example: "calculation_batch_id": "MXJvWdBbNaDVokYzDZAP9lZG6zwj7K1R".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. Lune splits large selections across batches, so you must check every returned ID in Step 4.4. Poll calculation batches
Poll the get a shipment calculation batch endpoint for every calculation batch ID. Use thecalculation_batch_id returned by the shipment batch when you requested calculations during upload, or use each ID in calculation_batch_ids when you requested calculations in Step 3.Use bounded backoff between requests and stop after a timeout appropriate for your application. If a calculation batch has not reached processed by then, contact Lune support with the shipment batch and calculation batch identifiers.pending, processing, and processed. While it is pending, results, success_count, and failed_count are absent. While it is processing, results contains the first requested shipments, in request order, and can contain fewer items than shipment_count.A calculation batch with a
status of processed has finished attempting the requested calculations, but individual shipments may still have failed. Always check for a batch-level batch_error. If it is absent, inspect success_count, failed_count, and every item in results. Each failed result contains the affected shipment id and an error with the calculation failure details.estimate_id. The estimate_id is null when the calculation uses a non-Lune methodology, such as EcoTransIT, so no Lune estimate is created. A failed result identifies the shipment and explains the error. Consult the calculation batch response schema for every possible batch and row result.Once a calculation batch is processed, use the get a shipment endpoint to retrieve each successful shipment and read total_emissions, wtt, ttw, and its per-leg values. For larger batches, use the list shipments endpoint with shipment_batch_id and the emissions filter; these emissions values are strings in kilograms.
