Delete Use of Sold Products (v2) - Dcycle Platform Docs

curl -X POST "https://api.dcycle.io/v2/use-of-sold-products/delete" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: 9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]}'

import os
import uuid

import requests

response = requests.post(
    "https://api.dcycle.io/v2/use-of-sold-products/delete",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
        "Idempotency-Key": str(uuid.uuid4()),  # keep it to retry this same batch
    },
    json={"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]},
    timeout=60,
)
response.raise_for_status()
print(response.json()["id"])

{
  "id": "6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
  "status": "processing",
  "entity_type": "use_of_product",
  "operation": "delete",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-21T09:24:17.552Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
    "items": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f/items"
  }
}

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "1 of the submitted records are invalid; nothing was written.",
  "errors": [
    {
      "source_row_index": 0,
      "client_row_id": null,
      "error_code": "NOT_FOUND",
      "error_params": { "field": "ids", "value": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a" }
    }
  ],
  "rejected": 1,
  "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}

{ "dry_run": true, "submitted": 1, "valid": 1 }

POST

use-of-sold-products

delete

curl -X POST "https://api.dcycle.io/v2/use-of-sold-products/delete" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: 9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]}'

import os
import uuid

import requests

response = requests.post(
    "https://api.dcycle.io/v2/use-of-sold-products/delete",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
        "Idempotency-Key": str(uuid.uuid4()),  # keep it to retry this same batch
    },
    json={"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]},
    timeout=60,
)
response.raise_for_status()
print(response.json()["id"])

{
  "id": "6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
  "status": "processing",
  "entity_type": "use_of_product",
  "operation": "delete",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-21T09:24:17.552Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
    "items": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f/items"
  }
}

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "1 of the submitted records are invalid; nothing was written.",
  "errors": [
    {
      "source_row_index": 0,
      "client_row_id": null,
      "error_code": "NOT_FOUND",
      "error_params": { "field": "ids", "value": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a" }
    }
  ],
  "rejected": 1,
  "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}

{ "dry_run": true, "submitted": 1, "valid": 1 }

← Sold Products API Delete uses of sold products by id, with their emissions. The period, its sales and the product stay: the period is left with no use, and a later Create Use of Sold Products (v2) for it is calculated from scratch. The request checks every id and answers 202 Accepted with an ingest job that deletes them in the background (see how bulk ingestion works). Follow it with GET /v2/ingest-jobs/{id} or, for a job submitted with an API key, the ingest_job.finished webhook. The ids are the entity_id of the items of the job that created the uses, or the use_of_product_data_id of Period Emissions.

Permanent. Deleted uses 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.

curl -X POST "https://api.dcycle.io/v2/use-of-sold-products/delete" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Idempotency-Key: 9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]}'

import os
import uuid

import requests

response = requests.post(
    "https://api.dcycle.io/v2/use-of-sold-products/delete",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
        "Idempotency-Key": str(uuid.uuid4()),  # keep it to retry this same batch
    },
    json={"ids": ["7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a"]},
    timeout=60,
)
response.raise_for_status()
print(response.json()["id"])

{
  "id": "6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
  "status": "processing",
  "entity_type": "use_of_product",
  "operation": "delete",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-21T09:24:17.552Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f",
    "items": "/v2/ingest-jobs/6d5c4b3a-2918-4f07-8e6d-5c4b3a29180f/items"
  }
}

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "1 of the submitted records are invalid; nothing was written.",
  "errors": [
    {
      "source_row_index": 0,
      "client_row_id": null,
      "error_code": "NOT_FOUND",
      "error_params": { "field": "ids", "value": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a" }
    }
  ],
  "rejected": 1,
  "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}

{ "dry_run": true, "submitted": 1, "valid": 1 }

How it works

The request checks every id. One that does not exist, is outside your organization’s perimeter or is repeated rejects the whole request with 422, and nothing is deleted.
The job deletes them in the background, 200 uses per chunk. Each use goes with the emissions it produced on every country sale of its period (with their calculation steps) and its calculation settings; those of a year that another period of the product still uses stay.
When every chunk is done the job is completed (or completed_with_errors). For a job submitted with an API key, ingest_job.finished is sent with "operation": "delete" to the webhook endpoints of the x-organization-id organization.

Request

Headers

string

required

Your API key (see Authentication).

string

required

The organization the uses are deleted for. The uses of its products, and of those of the organizations under it (its perimeter), can be deleted.

string

required

1 to 255 characters, one per batch, looked up per organization across every v2 bulk route. Within 24 hours, the same key with the same route and body returns the original job (with Idempotent-Replayed: true); 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 is valid. It does not check or store the Idempotency-Key.

Body Parameters

array[uuid]

required

Use of sold product ids, 1 to 5,000, each once.

Response

202 Accepted with the job (entity_type: use_of_product, operation: delete) and a Location header to it. GET /v2/ingest-jobs/{id}/items has one item per use, in the order sent; an item is failed with DELETE_FAILED when its use was already gone by the time the job reached it.

Errors

Problem details. Per-id codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED (source_row_index is the position in ids):

`error_code`	Cause
`NOT_FOUND`	The use does not exist or is outside your organization’s perimeter (both answer the same).
`DUPLICATE_ID`	The use is already in the request.

Request-level errors: 401 for a missing or invalid API key, 403 LOGGED_USER_NOT_MEMBER when the key’s user is not a member of the organization, 422 REQUEST_VALIDATION_FAILED for a malformed body (no ids, more than 5,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

Limits

Limit	Value
Ids per request	1 to 5,000
Uses per deletion chunk	200

Create Use of Sold Products (v2)

Set or replace the use of periods in bulk

Delete Sold Products (v2)

Delete whole products, with their periods and uses

Period Emissions

Find the id of a period’s use

Get Ingest Job

Follow the deletion

​How it works

​Request

​Headers

​Query Parameters

​Body Parameters

​Response

​Errors

​Limits

​Related Endpoints

Create Use of Sold Products (v2)

Delete Sold Products (v2)

Period Emissions

Get Ingest Job

How it works

Request

Headers

Query Parameters

Body Parameters

Response

Errors

Limits

Related Endpoints