Skip to main content
POST
← Logistics API Delete logistics legs (shipments) by id. The request checks every id and answers 202 Accepted with a job (see how bulk ingestion works); the deletion runs in the background, chunk by chunk, so thousands of ids never hold your request open. Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook.
Permanent. Deleted legs and their emissions cannot be recovered. Use dry_run=true first if you are not sure.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

How it works

  1. The request checks every id. One that does not exist, belongs to another organization, is not active or is repeated rejects the whole request with 422 and nothing is deleted.
  2. The job deletes in the background, 500 ids per chunk, each leg with its project links. The totals of the packages the legs belonged to (distance and emissions) are recalculated from their remaining legs; a package left without legs stays, with totals of 0. A leg that someone else deleted in the meantime ends failed with DELETE_FAILED; the others go on.
  3. When every chunk is done the job is completed (or completed_with_errors), and, for a job submitted with an API key, ingest_job.finished is sent to your webhook endpoints with "operation": "delete".
If a Create Logistics Requests (v2) job is still calculating a leg you delete, that job reports the leg failed with NOT_FOUND. The organization’s logistics intensity values (by TOC, hub and project) are not recalculated when the job finishes: they catch up later, in the background, as after Create Logistics Requests (v2). The legs and their packages’ totals are already up to date when the job finishes. The ids are the legs’ Dcycle ids: the entity_id of each item of the Create Logistics Requests (v2) job, or the id in List Logistics Requests.

Request

Headers

string
required
Your API key (see Authentication).Example: ${DCYCLE_API_KEY}
string
required
Your organization UUID. Only this organization’s legs can be deleted.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
string
required
1 to 255 characters, one per batch. It is looked up per organization across every v2 bulk route, creates included: do not reuse the key of the batch that created the legs. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true) instead of deleting again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free and a request with it is a new one. See The Idempotency-Key.

Query Parameters

boolean
default:"false"
Check only: the same 422 for bad ids, nothing deleted, no job; 200 with {"dry_run": true, "submitted": n, "valid": n} when every id would be deleted. The Idempotency-Key header is still required, but a dry run does not check or store it.

Body Parameters

array[uuid]
required
Leg ids to delete, 1 to 5,000, each once.

Response

202 Accepted, the job (operation: delete) and a Location header to it. Per-id outcomes are in GET /v2/ingest-jobs/{id}/items: one item per id, in the order sent, with stage: delete and entity_id = the leg id.

Errors

Problem details. Per-id codes in errors[].error_code: The API key and the organization are checked as in Create Logistics Requests (v2): 401, 400 ORGANIZATION_ID_REQUIRED and 403 (LOGGED_USER_NOT_MEMBER, API_KEY_SCOPE_DENIED, VIEWER_CANNOT_WRITE), each in Errors. Then 422 REQUEST_VALIDATION_FAILED for a malformed body (empty ids, more than 5,000, not UUIDs, unknown fields), 422 IDEMPOTENCY_KEY_REUSED and 409 IDEMPOTENCY_KEY_IN_PROGRESS.

Create Logistics Requests (v2)

Create up to 5,000 legs in one request

Get Ingest Job

Follow the deletion