Update Waste - Dcycle Platform Docs

Update Waste

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    identification_name: '<string>',
    description: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    base_quantity: 123,
    destination: '<string>',
    total_km_to_waste_center: 123,
    file_url: '<string>',
    file_name: '<string>',
    file_id: {},
    unit_id: '<string>',
    waste_ler_code_id: '<string>',
    waste_rd_code_id: '<string>',
    custom_emission_factor_id: '<string>',
    custom_ef_record_id: '<string>',
    facility_percentages: [{facility_id: '<string>', percentage: 123, organization_id: '<string>'}]
  })
};

fetch('https://api.dcycle.io/v1/wastes/{waste_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/wastes/{waste_id}"

payload = {
    "identification_name": "<string>",
    "description": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "base_quantity": 123,
    "destination": "<string>",
    "total_km_to_waste_center": 123,
    "file_url": "<string>",
    "file_name": "<string>",
    "file_id": {},
    "unit_id": "<string>",
    "waste_ler_code_id": "<string>",
    "waste_rd_code_id": "<string>",
    "custom_emission_factor_id": "<string>",
    "custom_ef_record_id": "<string>",
    "facility_percentages": [
        {
            "facility_id": "<string>",
            "percentage": 123,
            "organization_id": "<string>"
        }
    ]
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/wastes/{waste_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "identification_name": "<string>",
  "description": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "base_quantity": 123,
  "destination": "<string>",
  "total_km_to_waste_center": 123,
  "file_url": "<string>",
  "file_name": "<string>",
  "file_id": {},
  "unit_id": "<string>",
  "waste_ler_code_id": "<string>",
  "waste_rd_code_id": "<string>",
  "custom_emission_factor_id": "<string>",
  "custom_ef_record_id": "<string>",
  "facility_percentages": [
    {
      "facility_id": "<string>",
      "percentage": 123,
      "organization_id": "<string>"
    }
  ]
}
'

{
  "id": "<string>",
  "identification_name": "<string>",
  "description": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "base_quantity": 123,
  "quantity": 123,
  "percentage": 123,
  "destination": "<string>",
  "total_km_to_waste_center": 123,
  "status": "<string>",
  "error_messages": {},
  "co2e": 123,
  "co2e_biomass": 123,
  "enabled": {},
  "file_id": {},
  "file_name": {},
  "file_url": {},
  "created_at": {},
  "updated_at": {}
}

PATCH

wastes

{waste_id}

Update Waste

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    identification_name: '<string>',
    description: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    base_quantity: 123,
    destination: '<string>',
    total_km_to_waste_center: 123,
    file_url: '<string>',
    file_name: '<string>',
    file_id: {},
    unit_id: '<string>',
    waste_ler_code_id: '<string>',
    waste_rd_code_id: '<string>',
    custom_emission_factor_id: '<string>',
    custom_ef_record_id: '<string>',
    facility_percentages: [{facility_id: '<string>', percentage: 123, organization_id: '<string>'}]
  })
};

fetch('https://api.dcycle.io/v1/wastes/{waste_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/wastes/{waste_id}"

payload = {
    "identification_name": "<string>",
    "description": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "base_quantity": 123,
    "destination": "<string>",
    "total_km_to_waste_center": 123,
    "file_url": "<string>",
    "file_name": "<string>",
    "file_id": {},
    "unit_id": "<string>",
    "waste_ler_code_id": "<string>",
    "waste_rd_code_id": "<string>",
    "custom_emission_factor_id": "<string>",
    "custom_ef_record_id": "<string>",
    "facility_percentages": [
        {
            "facility_id": "<string>",
            "percentage": 123,
            "organization_id": "<string>"
        }
    ]
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/wastes/{waste_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "identification_name": "<string>",
  "description": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "base_quantity": 123,
  "destination": "<string>",
  "total_km_to_waste_center": 123,
  "file_url": "<string>",
  "file_name": "<string>",
  "file_id": {},
  "unit_id": "<string>",
  "waste_ler_code_id": "<string>",
  "waste_rd_code_id": "<string>",
  "custom_emission_factor_id": "<string>",
  "custom_ef_record_id": "<string>",
  "facility_percentages": [
    {
      "facility_id": "<string>",
      "percentage": 123,
      "organization_id": "<string>"
    }
  ]
}
'

{
  "id": "<string>",
  "identification_name": "<string>",
  "description": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "base_quantity": 123,
  "quantity": 123,
  "percentage": 123,
  "destination": "<string>",
  "total_km_to_waste_center": 123,
  "status": "<string>",
  "error_messages": {},
  "co2e": 123,
  "co2e_biomass": 123,
  "enabled": {},
  "file_id": {},
  "file_name": {},
  "file_url": {},
  "created_at": {},
  "updated_at": {}
}

← Wastes API Update specific fields of an existing waste record. All fields are optional - only include fields you want to modify. Omitted fields will retain their current values.

CO2e Recalculation: When you update fields like base_quantity, waste_ler_code_id, or unit_id, CO2e emissions are automatically recalculated.

waste_efs_id removed. The legacy catalog-based emission factor selector is no longer accepted — sending it in the request body has no effect. Every waste is recomputed through the conversion-factors pipeline: use waste_ler_code_id/waste_rd_code_id for a standard emission factor, or custom_ef_record_id for a custom one.

Request

Path Parameters

uuid

required

The UUID of the waste record to updateExample: 550e8400-e29b-41d4-a716-446655440000

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

All parameters are optional. Only include fields you want to update.

string

Waste identification name or invoice numberExample: "RSU-2024-001-Updated"

string

Description of the wasteExample: "Updated description"

date

Start date of the waste period, a year from 1970 to next year when it changes (resending the stored date is always accepted). An empty string ("") is treated the same as omitting the field — the existing value is left unchanged.Example: "2024-01-01"

date

End date of the waste period, a year from 1970 to next year, on or after start_date (the stored one when only end_date is sent). An empty string ("") is treated the same as omitting the field — the existing value is left unchanged.Example: "2024-06-30"

number

Waste quantity in the specified unit. Must be greater than 0.Example: 2000.0

string

Waste destination or treatment facilityExample: "New waste treatment plant"

number

Distance to waste treatment center in kilometersExample: 30.0

string

URL of a supporting document, or the document itself as a base64 data URI (data:<mime>;base64,...), which is uploaded and stored as a URL. A data URI that is not valid base64 is rejected with 422. Send null to remove the attachment.

string

Original name of the attached document, up to 255 characters. A new file_url sent without file_name clears the stored name.Example: "manifest.xlsx"

uuid | null

UUID of a file of your files to attach as the supporting document, instead of a data URI in file_url. The waste stores the file’s URL and its name with extension as file_url and file_name. The file must be uploaded and belong to your organization or one you can write to; any other id answers 404 (NOT_FOUND). Sending it with a data URI in file_url answers 422. null removes the attachment (file_url, file_name and the link to the file). With facility_percentages, every part of the waste takes it.Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

uuid

UUID of the quantity unitExample: "61743a63-ff70-459c-9567-5eee8f7dfd5c"

uuid

UUID of the LER code from the kernel waste_ler_codes table. Required unless the waste already has one — every waste must end up with a LER code.Retrieve available options from GET /v1/wastes/ler-codesExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

uuid

UUID of the R/D operation code from the kernel waste_rd_codes table.Retrieve available options from GET /v1/wastes/rd-codes — pass ler_code_id to restrict to codes valid for the chosen LERExample: "b2c3d4e5-f6a7-8901-bcde-fa2345678901"

uuid

Deprecated, no longer functional. Even if sent, it is never persisted — use custom_ef_record_id for a custom emission factor.Example: "880e8400-e29b-41d4-a716-446655440000"

uuid

UUID of a custom emission-factor record. Transient input — persisted as a client_choice calculation config keyed on the waste, not stored on the waste row itself.Mutually exclusive with custom_emission_factor_id.Example: "c3d4e5f6-a7b8-9012-cdef-ab3456789012"

array

How the waste is split across facilities. A split waste is one record per facility (a part), all sharing a source_invoice_id; waste_id can be any of its parts.Send it and the edit applies to every part of the waste:

each part takes the other fields of the body, and its quantity is base_quantity × percentage, rounded to 2 decimals;
a facility you keep keeps its part (same id), and a facility swapped for another of the same organization moves its part (same id);
any other new facility gets a new part, which copies the fields of the part in the path that the body does not send (attachment, distance, operator…);
the part of a facility you leave out is deleted with its emissions.

The response is the part in the path; if you left its facility out, it is the waste’s first remaining part (another id). Leave facility_percentages out and only the part in the path changes, as before.Each facility once, every one inside your organization’s write perimeter, and the percentages adding up to 1 at most (within 0.0001); under 1, the rest of the waste is not counted. For a waste that is not split, send its facility at 1.If a part of the waste is outside your perimeter (a split made by a parent organization, edited from a subsidiary), the split cannot be changed: resend it as stored and only the part in the path changes; any other split answers 404.

Show entry fields

uuid

required

UUID of the facility receiving this share.

number

required

Share of the waste, greater than 0 and at most 1 (e.g. 0.6).

uuid

Ignored: a part belongs to its facility’s organization.

Example:

[{"facility_id": "550e8400-e29b-41d4-a716-446655440000", "percentage": 0.6}, {"facility_id": "660e8400-e29b-41d4-a716-446655440000", "percentage": 0.4}]

Response

string

Unique identifier (UUID) for the waste record

string

Waste identification name

string

Description of the waste

date

Start date of the waste period

date

End date of the waste period

number

Waste quantity in the original unit

number

Adjusted quantity after applying percentage allocation

number

Allocation percentage (0 to 1)

string

Waste destination or treatment facility

number

Distance to waste treatment center in km

string

Current status: uploaded, active, loading, or error

array[string] | null

Error details when status is error

number

CO2 equivalent emissions in kg CO2e

number

Biogenic CO2 emissions in kg CO2e

boolean | null

Whether the waste record is enabled for emission calculations

string | null

UUID of the linked file (if created via bulk import)

string | null

Name of the linked import file

string | null

Download URL for the linked file

datetime

Timestamp when the record was created

datetime | null

Timestamp when the record was last updated

Example

curl -X PATCH "https://api.dcycle.io/v1/wastes/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "base_quantity": 2000.0,
    "description": "Updated municipal solid waste",
    "destination": "New waste treatment plant"
  }'

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")
waste_id = "550e8400-e29b-41d4-a716-446655440000"

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id,
    "Content-Type": "application/json"
}

payload = {
    "base_quantity": 2000.0,
    "description": "Updated municipal solid waste",
    "destination": "New waste treatment plant"
}

response = requests.patch(
    f"https://api.dcycle.io/v1/wastes/{waste_id}",
    headers=headers,
    json=payload
)

waste = response.json()
print(f"Waste updated: {waste['id']}")
print(f"New quantity: {waste['base_quantity']}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const wasteId = "550e8400-e29b-41d4-a716-446655440000";

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId,
  'Content-Type': 'application/json'
};

const payload = {
  base_quantity: 2000.0,
  description: "Updated municipal solid waste",
  destination: "New waste treatment plant"
};

axios.patch(
  `https://api.dcycle.io/v1/wastes/${wasteId}`,
  payload,
  { headers }
)
.then(response => {
  const waste = response.data;
  console.log(`Waste updated: ${waste.id}`);
  console.log(`New quantity: ${waste.base_quantity}`);
})
.catch(error => console.error(error));

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "identification_name": "RSU-2024-001",
  "description": "Updated municipal solid waste",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "base_quantity": 2000.0,
  "quantity": 2000.0,
  "percentage": 1.0,
  "destination": "New waste treatment plant",
  "total_km_to_waste_center": 25.0,
  "status": "active",
  "error_messages": null,
  "co2e": 601.0,
  "co2e_biomass": 16.4,
  "enabled": true,
  "file_id": null,
  "file_name": null,
  "file_url": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T15:45:00Z"
}

Common Errors

404 Not Found

Cause: Waste record not found in organization

{
  "detail": "Waste with id=UUID('...') not found",
  "code": "WASTE_NOT_FOUND"
}

Solution: Verify the waste ID is correct and belongs to your organization.

403 Forbidden

Cause: Waste doesn’t belong to your organization

{
  "detail": "Waste doesn't belong to organization",
  "code": "FORBIDDEN"
}

Solution: Verify the x-organization-id header matches the organization that owns this waste record.

422 Validation Error

Cause: Invalid values

{
  "detail": [
    {
      "loc": ["body", "base_quantity"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

Solution: Ensure numeric values are valid and within allowed ranges. A facility_percentages that breaks the split rule answers 422 with a code, and nothing is changed:

{
  "code": "FACILITY_PERCENTAGES_INVALID",
  "detail": "facility_percentages is invalid (FACILITY_PERCENTAGES_INVALID): {'field': 'facility_percentages'}"
}

`code`	Cause
`FACILITIES_MUST_BE_UNIQUE`	A facility is listed twice.
`REFERENCE_NOT_FOUND`	A facility does not exist, is disabled or is outside your organization’s perimeter (all answer the same, so ids cannot be probed).
`FACILITY_PERCENTAGES_INVALID`	The percentages add up to more than 1 (beyond 0.0001).

A changed split of a waste with a part outside your perimeter answers 404, like a waste that does not exist.

List Wastes

Retrieve all waste records

Create Waste

Add a new waste record

Facilities

List facilities for your organization

​Request

​Path Parameters

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​404 Not Found

​403 Forbidden

​422 Validation Error

​Related Endpoints

List Wastes

Create Waste

Facilities

Request

Path Parameters

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

404 Not Found

403 Forbidden

422 Validation Error

Related Endpoints