> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Logistics Request (v2)

> Create a logistics shipment with asynchronous emissions calculation

# Create Logistics Request (v2)

`v2` of [Create Logistics Request](/api-reference/logistics/create-request). It accepts the
**exact same request body** and returns the **same response shape**, but the expensive
distance and emissions calculation is performed **asynchronously** instead of inline. This
keeps the request fast and predictable for high-volume integrations.

<Note>
  **Same contract as v1.** Headers, body parameters and validation are identical to
  `POST /v1/logistics/requests`. Only the timing of the distance/emissions calculation
  changes. See the [v1 reference](/api-reference/logistics/create-request) for the full list
  of body parameters.
</Note>

## v1 vs v2

| Behaviour                                         | v1 (`/v1/logistics/requests`)                   | v2 (`/v2/logistics/requests`)                                                           |
| ------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| Distance calculation (when `distance_km` omitted) | Calculated **inline**, returned in the response | **Deferred** to an async worker, `null` in the immediate response                       |
| Emissions (`co2e`)                                | Calculated **inline**, returned in the response | **Deferred** to an async worker, `null` in the immediate response                       |
| `tkm`                                             | Returned in the response                        | Returned only if `distance_km` was provided; otherwise `null` until the async calc runs |
| Response latency                                  | Higher (waits for geocoding + distance APIs)    | Low (returns as soon as the record is persisted)                                        |

<Warning>
  In v2, `co2e` is **always `null`** in the immediate response, and `distance_km` / `tkm`
  are `null` whenever the client did not supply `distance_km`. These fields are populated
  asynchronously. Read them back later via
  [`GET /v1/logistics/requests`](/api-reference/logistics/get-requests) (filter by `movement_id`)
  once the calculation has completed.
</Warning>

## Request

The request is identical to v1. Minimal example:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v2/logistics/requests" \
    -H "x-api-key: $DCYCLE_API_KEY" \
    -H "x-organization-id: $DCYCLE_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "origin_country": "ES",
      "load": 1000,
      "load_unit": "kg",
      "toc": "truck_diesel",
      "year": 2024
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      "https://api.dcycle.io/v2/logistics/requests",
      headers={
          "x-api-key": DCYCLE_API_KEY,
          "x-organization-id": DCYCLE_ORG_ID,
      },
      json={
          "origin": "Madrid, Spain",
          "destination": "Barcelona, Spain",
          "origin_country": "ES",
          "load": 1000,
          "load_unit": "kg",
          "toc": "truck_diesel",
          "year": 2024,
      },
  )
  data = response.json()
  print(data["id"], data["co2e"])  # co2e is None while the async calculation is pending
  ```
</CodeGroup>

## Response

The response shape matches v1, with `co2e` (and `distance_km` / `tkm` when not provided)
returned as `null` while the asynchronous calculation is pending.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "origin_country": "ES",
  "distance_km": null,
  "load": 1000,
  "load_unit": "kg",
  "toc": "truck_diesel",
  "category": "road",
  "year": 2024,
  "co2e": null,
  "tkm": null,
  "created_at": "2026-06-23T09:00:00Z",
  "updated_at": "2026-06-23T09:00:00Z"
}
```

<ResponseField name="co2e" type="number | null">
  Total CO2 equivalent emissions in kilograms. **`null` in v2** until the asynchronous
  calculation completes.
</ResponseField>

<ResponseField name="distance_km" type="number | null">
  Distance in kilometers. Echoes the value you provided; **`null`** when omitted (it is
  calculated asynchronously).
</ResponseField>

<ResponseField name="tkm" type="number | null">
  Tonne-kilometers. Computed up front when `distance_km` is provided; otherwise **`null`**
  until the asynchronous calculation completes.
</ResponseField>

<Note>
  All other response fields (`id`, `origin`, `destination`, `load`, `toc`, `category`,
  traceability fields, etc.) are returned exactly as documented for
  [v1](/api-reference/logistics/create-request).
</Note>

## Reading back the calculated values

Because the calculation is asynchronous, poll the list endpoint (filtering by the
`movement_id` you submitted) until `kgco2e` / `distance_km` are populated:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.dcycle.io/v1/logistics/requests?search=MOV-2024-001234" \
  -H "x-api-key: $DCYCLE_API_KEY" \
  -H "x-organization-id: $DCYCLE_ORG_ID"
```

<Tip>
  Migrating from v1? No code changes are required beyond the URL prefix and handling
  `co2e` (and possibly `distance_km` / `tkm`) being `null` in the immediate response.
</Tip>