Update Waste

Modify waste record details and update disposal information

PATCH /v1/wastes/{waste_id}

Update Waste

JavaScript

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,
    unit_id: '<string>',
    waste_ler_code_id: '<string>',
    waste_rd_code_id: '<string>',
    custom_emission_factor_id: '<string>',
    custom_ef_record_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));

200

{
  "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

waste_id · uuid · required

The UUID of the waste record to update

Example: 550e8400-e29b-41d4-a716-446655440000

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

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

identification_name · string

Waste identification name or invoice number

Example: "RSU-2024-001-Updated"

description · string

Description of the waste

Example: "Updated description"

start_date · 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"

end_date · 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"

base_quantity · number

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

Example: 2000.0

destination · string

Waste destination or treatment facility

Example: "New waste treatment plant"

total_km_to_waste_center · number

Distance to waste treatment center in kilometers

Example: 30.0

unit_id · uuid

UUID of the quantity unit

Example: "61743a63-ff70-459c-9567-5eee8f7dfd5c"

waste_ler_code_id · 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-codes

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

waste_rd_code_id · 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 LER

Example: "b2c3d4e5-f6a7-8901-bcde-fa2345678901"

custom_emission_factor_id · 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"

custom_ef_record_id · 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"

Response

id · string

Unique identifier (UUID) for the waste record

identification_name · string

Waste identification name

description · string

Description of the waste

start_date · date

Start date of the waste period

end_date · date

End date of the waste period

base_quantity · number

Waste quantity in the original unit

quantity · number

Adjusted quantity after applying percentage allocation

percentage · number

Allocation percentage (0 to 1)

destination · string

Waste destination or treatment facility

total_km_to_waste_center · number

Distance to waste treatment center in km

status · string

Current status: uploaded, active, loading, or error

error_messages · array[string] | null

Error details when status is error

co2e · number

CO2 equivalent emissions in kg CO2e

co2e_biomass · number

Biogenic CO2 emissions in kg CO2e

enabled · boolean | null

Whether the waste record is enabled for emission calculations

file_id · string | null

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

file_name · string | null

Name of the linked import file

file_url · string | null

Download URL for the linked file

created_at · datetime

Timestamp when the record was created

updated_at · datetime | null

Timestamp when the record was last updated

Example

cURL

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"
  }'

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.

Related Endpoints

List Wastes

Retrieve all waste records

Create Waste

Add a new waste record

Facilities

List facilities for your organization