Skip to main content
POST
/
v1
/
invoices
/
recalculate
Recalculate Invoices
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({invoice_ids: {}, activity_categories: {}})
};

fetch('https://api.dcycle.io/v1/invoices/recalculate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "invoice_ids": {},
  "count": 123,
  "processing_job_ids": {}
}

​
Recalculate Invoices

Enqueue EF-config recalculation for a set of invoices by activity category. The endpoint returns 202 Accepted immediately and creates one ProcessingJob per requested activity category. Invoices remain in their current status while jobs are processing.
All invoice IDs must belong to the caller’s organization. IDs that don’t match are silently dropped. All surviving invoices must share a single supported type (heat or electricity) unless only cross-type categories (e.g. energy) are requested.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

​
Body Parameters

​
invoice_ids
array of strings
required
One or more invoice UUIDs to recalculate. Must be non-empty.Example: ["a1b2c3d4-...", "e5f6g7h8-..."]
​
activity_categories
array of strings
required
Activity categories to recalculate. Must be non-empty. Duplicates are silently deduplicated.Allowed values:
  • stationary — Scope 1 stationary combustion (heat invoices)
  • stationary_generation — Scope 3 heat generation (heat invoices)
  • electricity — Scope 2 market-based electricity
  • electricity_location_based — Scope 2 location-based electricity
  • electricity_generation — Scope 3 electricity generation
  • electricity_transmission_and_distribution — Scope 3 T&D losses
  • energy — General energy category (cross-type)
Example: ["electricity", "electricity_location_based"]

​
Response

{
  "invoice_ids": ["a1b2c3d4-...", "e5f6g7h8-..."],
  "count": 2,
  "processing_job_ids": ["j1j2j3j4-...", "k5k6k7k8-..."]
}
​
invoice_ids
array of strings
UUIDs of the invoices that were enqueued (after organization scoping).
​
count
integer
Number of invoices enqueued.
​
processing_job_ids
array of strings
One ProcessingJob UUID per dispatched activity category.

​
Error Codes

CodeHTTP StatusDescription
MIXED_INVOICE_TYPES400Invoices span multiple types (e.g., heat and electricity mixed)
UNSUPPORTED_INVOICE_TYPE400Invoice type is not supported for recalculation
ACTIVITY_CATEGORY_MISMATCH400A requested category is incompatible with the invoice type