Update a shipping emission estimate (single)

Path Parameters

idstringrequired

The estimate's unique identifier

Query Parameters

estimate_mass_unitstring

By default estimate mass units are returned in tonnes.

Estimate mass units in responses are converted to estimate_mass_unit when set.

Parameters

shipmentrequired

Either a mass given in kilograms or tonnes (mass) or the number of Twenty-foot Equivalent Units (TEUs) (with their cargo type, optionally). Note that providing mass will result in more accurate estimates for methods other than container_ship. Estimates using container_ship are more precise when the shipment is given in TEUs.

namestring

A name to reference this calculation.

bundle_selectionarray of object

Bundle selection percentages.

The sum of all percentages must equal 100.

If not specified, the preconfigured allocation ratios are going to be used.

If, for each selection, percentage is not provided, the selection is divided equally (best effort) between bundles. percentage must be provided for all or none of the bundles.

quantity_truncenum

Selects to which precision to truncate quantities specific to carbon offsetting.

Enum:

is_shipmentboolean

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstringdate-time

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

routerequired

Either the shipping distance or the start/destination address pair.

Note that for sea transport the source/destination pair should be as close to locations of existing and well-known ports as possible. Coordinates or addresses that lie far from the shore line or coordinates deep into the sea or ocean will result in inaccurate calculations.

When transporting goods over unusual routes or between unusual points it's better to provide us the distance directly to ensure better calculations.

methodrequired

country_codeenum

The three-letter code of the country where the shipping takes place, if applicable.

Providing this value will improve the estimation process. If the shipping spans multiple countries you can either make multiple per-country estimations or choose the country with the largest share of the route.

Enum:

Returns

massobjectrequired

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

idempotency_keystring

Account-unique identifier provided by the client.

idempotency_key has two purposes:

Clients can safely retry estimate requests without accidentally performing the same operation multiple times.
Clients can use idempotency_key to reconcile estimates with entities on their system.

vessel_inference_details

The method we used to infer a vessel from client provided input.

null when vessel identifier provided by client or no vessel inference not relevant to estimation.

distanceobject

adjusted_distanceobject

Distance estimation after distance adjustment factors have been applied. Adjusted factors are decided by GLEC and are added to make distances more realistic.

distance_calculation_methodrequired

The method we used to determine the shipping distance.

null in case of logistics sites or when resolved_legs is set.

routerequired

The shipping route.

null in case of logistics sites and situations where the concept of a route doesn't make sense or we're unable to return the route. That includes the following situations at the moment:

Routes where source or destination is an address (or both are).
Most land and inland waterways routes.
The actual distance value was provided by the user.
The emission estimate was created before 2023-09-22.

emission_factorobjectrequired

methodologyarray of enumrequired

Summary of the methodology used to calculate emissions or any value which is a prerequisite.

imo_unavailable_container_ship_fallback: the vessel IMO was not found, therefore a generic container ship emission factor has been used. flight_number_unavailable_fallback: the flight number could not be found or the aircraft is currently not supported, therefore a generic plane method has been used.

distance_calculation_detailsrequired

Information regarding why an alternative distance calculation method was used. null in case several resolved legs are presented.

methodology_detailsrequired

converted_shipmentrequired

The shipment after conversion to the emission factor unit (mass to/from TEU).

null if no conversion was necessary.

shipment_conversion_methodrequired

The method we used to convert the shipment to the emission factor unit.

null if no conversion was necessary.

resolved_legsrequired

If the input shipping method results in multiple legs being detected, each leg will be calculated and shown separately.

idstringrequired

The emission calculation unique identifier

is_shipmentbooleanrequired

When true, the emission estimate refers to an actual shipment of goods, will be included in Lune analytics and can be included in any CO2 emissions reporting.

This property exists to distinguish booking quotes or forecasts from actual shipments where goods are moved.

You can mark an estimate as shipment at any time.

shipped_atstringdate-timerequired

The date and time of shipping the goods for the purpose of analytics (it doesn't affect emission calculations in any way).

If a value is provided when creating or updating an estimate we use the value. Otherwise defaults to the current time when creating estimates and remains unchanged when updating estimates.

This property must be formatted as RFC 3339, section 5.6 timestamp.

Examples:

2023-12-01T12:30:30.000Z
2023-12-01T12:30:30Z
2023-12-01T11:30:30+01.00

quoterequired

requestobjectrequired

Parameters for estimating shipping emissions

metadataobject

An arbitrary dictionary (key-value pairs) to store application-specific information.

Lune doesn't use this information for order processing. Its purpose is for the API clients to be able to attach arbitrary information (to an order for example) and then retrieve it.

external_estimate_urlrequired

An external accessible URL linking to a detailed page that provides complete information about the estimate.

sourceenum

Identifies the source used to create the estimate.

Enum:

api
dashboard
csv
chain_io
ecotransit_csv
widget

PUT /estimates/shipping/{id}

curl 'https://api.lune.co/v1/estimates/shipping/Vxg3b7MoBkrNQA328Rgpnvmw1J8a6Lqj' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -X PUT \
  -d '{
    "shipment": {
      "containers": "2"
    },
    "route": {
      "source": {
        "locode": "CNSGH"
      },
      "destination": {
        "locode": "NLRTM"
      }
    },
    "method": {
      "vessel_type": "container_ship"
    },
    "is_shipment": true,
    "shipped_at": "2023-11-20T10:20:30Z"
  }'

Response

{
  "id": "08QD7GPaBx5b6Y6mJlWyONXLvrZljRE2",
  "is_shipment": true,
  "shipped_at": "2023-11-20T10:20:30Z",
  "mass": {
    "amount": "2.969503",
    "unit": "t"
  },
  "quote": {
    "estimated_quantity": "2.969502",
    "estimated_commission": "8.03",
    "estimated_total_cost": "80.18",
    "estimated_offset_cost": "72.15",
    "requested_value": null,
    "requested_quantity": "2.969503",
    "currency": "USD",
    "bundles": [
      {
        "bundle_id": "q9aKx7b6nNXMk3Yv3pD1mlW5Od2eLZE8",
        "bundle_name": "Conserving forests in Asia",
        "quantity": "2.821027",
        "unit_price": "12.42",
        "gross_unit_price": "13.8",
        "offset_cost": "35.04",
        "insufficient_available_quantity": null
      },
      {
        "bundle_id": "xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w",
        "bundle_name": "Ocean Carbon Removal",
        "quantity": "0.148475",
        "unit_price": "250",
        "gross_unit_price": "277.78",
        "offset_cost": "37.12",
        "insufficient_available_quantity": null
      }
    ]
  },
  "distance": {
    "amount": "22466.6346",
    "unit": "km"
  },
  "methodology": [],
  "request": {
    "shipment": {
      "containers": "2"
    },
    "route": {
      "source": {
        "locode": "CNSGH"
      },
      "destination": {
        "locode": "NLRTM"
      }
    },
    "method": {
      "vessel_type": "container_ship"
    }
  },
  "source": "api"
}