Skip to content
Space Invoices Documentation

Revenue Recognition

Revenue Recognition

Deferred revenue and accrued revenue reporting generated from finalized sales documents and their service periods.

Endpoints
IntroductionPOST/revenue-recognition/backfillGET/revenue-recognition/settingsGET/revenue-recognition/reportGET/revenue-recognition/detailsGET/revenue-recognition/linesGET/revenue-recognition/documents/{id}PATCH/revenue-recognition/settings

The Revenue Recognition object

object

Attributes

dataarray of objects
Other attributes
totalnumber
currency_codestring
document_idstring
Examplejson
{
  "calculation_mode": "recognition_entries",
  "data": [
    {
      "id": "rre_123",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "document_item_id": "di_123",
      "document_item_name": "Telemetry platform hosting",
      "customer_id": "cus_123",
      "customer_name": "Nebula Propulsion Labs",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "recognized_amount": 2500,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28",
      "method": "service_period_daily"
    },
    {
      "id": "rre_124",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "document_item_id": "di_123",
      "document_item_name": "Telemetry platform hosting",
      "customer_id": "cus_123",
      "customer_name": "Nebula Propulsion Labs",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "recognized_amount": 2500,
      "period_start": "2026-02-01",
      "period_end": "2026-02-28",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28",
      "method": "service_period_daily"
    }
  ],
  "total": 5000,
  "currency_code": "EUR",
  "document_id": "inv_123"
}

Backfill generated revenue recognition entries

POST/revenue-recognition/backfill

Backfill generated revenue recognition entries

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.backfill({
  date_from: "2026-01-01",
  date_to: "2026-03-31",
  dry_run: true
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Example:
Response

Returns

processed_documentsnumber
generated_entriesnumber
dry_runboolean
json
{
  "processed_documents": 0,
  "generated_entries": 0,
  "dry_run": true
}

Get revenue recognition settings

GET/revenue-recognition/settings

Get revenue recognition settings

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.getSettings({
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

json
{
  "default_method": "service_period_daily"
}

Get revenue recognition report

GET/revenue-recognition/report

Get revenue recognition report

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

date_fromstringrequired

Report start date in YYYY-MM-DD format.

date_tostringrequired

Report end date in YYYY-MM-DD format.

basisstringoptional

recognized returns revenue recognized inside each period. deferred returns the remaining future recognition balance at the end of each period.

Possible values: "recognized", "deferred"

Default: "recognized"

group_bystringoptional

Report grouping dimension.

Possible values: "financial_category"

Default: "financial_category"

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.getReport({
  date_from: "2026-01-01",
  date_to: "2026-12-31"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

totalsarray of numbers
totalnumber
currency_codestring
date_fromstring
date_tostring
json
{
  "basis": "recognized",
  "group_by": "financial_category",
  "calculation_mode": "recognition_entries",
  "periods": [
    {
      "period": "2026-01",
      "date_from": "2026-01-01",
      "date_to": "2026-01-31"
    },
    {
      "period": "2026-02",
      "date_from": "2026-02-01",
      "date_to": "2026-02-28"
    }
  ],
  "series": [
    {
      "key": "fcat_hosting",
      "financial_category_id": "fcat_hosting",
      "name": "Hosting revenue",
      "color": "#2563eb",
      "values": [
        2500,
        2500
      ],
      "total": 5000
    }
  ],
  "totals": [
    2500,
    2500
  ],
  "total": 5000,
  "currency_code": "EUR",
  "date_from": "2026-01-01",
  "date_to": "2026-02-28"
}
Example:

Get revenue recognition report details

GET/revenue-recognition/details

Get revenue recognition report details

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

date_fromstringrequired

Report start date in YYYY-MM-DD format.

date_tostringrequired

Report end date in YYYY-MM-DD format.

basisstringoptional

recognized returns the entries recognized inside the date range. deferred returns the entries still to be recognized after date_to from documents dated on or before date_to, so the total equals the deferred balance at date_to.

Possible values: "recognized", "deferred"

Default: "recognized"

group_bystringoptional

Report grouping dimension.

Possible values: "financial_category"

Default: "financial_category"

financial_category_idstringoptionalnullable

Optional category ID. Use null/omit for all categories.

financial_category_keystringoptionalnullable

Optional category key (for example office-supplies), as an alternative to financial_category_id. Cannot be combined with financial_category_id. An unknown key selects nothing, like an unknown ID. Use null/omit for all categories.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.getDetails({
  date_from: "2026-01-01",
  date_to: "2026-12-31"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

dataarray of objects
Other parameters
totalnumber
currency_codestring
json
{
  "calculation_mode": "recognition_entries",
  "data": [
    {
      "id": "rre_123",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "document_item_id": "di_123",
      "document_item_name": "Telemetry platform hosting",
      "customer_id": "cus_123",
      "customer_name": "Nebula Propulsion Labs",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "recognized_amount": 2500,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28",
      "method": "service_period_daily"
    }
  ],
  "total": 2500,
  "currency_code": "EUR"
}
Example:

List revenue recognition report lines

GET/revenue-recognition/lines

Paged drill-down of a report selection by document line. Accepts the same selection as the details endpoint; each line sums its entries inside the selection (recognized inside the range, or still deferred after date_to). Lines are ordered by document date, document number and line, and total covers every line in the selection.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

date_fromstringrequired

Report start date in YYYY-MM-DD format.

date_tostringrequired

Report end date in YYYY-MM-DD format.

basisstringoptional

recognized returns the entries recognized inside the date range. deferred returns the entries still to be recognized after date_to from documents dated on or before date_to, so the total equals the deferred balance at date_to.

Possible values: "recognized", "deferred"

Default: "recognized"

group_bystringoptional

Report grouping dimension.

Possible values: "financial_category"

Default: "financial_category"

financial_category_idstringoptionalnullable

Optional category ID. Use null/omit for all categories.

financial_category_keystringoptionalnullable

Optional category key (for example office-supplies), as an alternative to financial_category_id. Cannot be combined with financial_category_id. An unknown key selects nothing, like an unknown ID. Use null/omit for all categories.

uncategorizedbooleanoptionalnullable

When true, only lines without a financial category. Cannot be combined with financial_category_id or financial_category_key.

limitintegeroptionalnullable

Number of lines per page (1-100). Defaults to 20; null or omitted uses the default.

next_cursorstringoptionalnullable

Opaque cursor from pagination.next_cursor of the previous response. Null or omitted starts at the first page.

prev_cursorstringoptionalnullable

Opaque cursor from pagination.prev_cursor of the previous response. Null or omitted starts at the first page.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.listLines({
  date_from: "2026-01-01",
  date_to: "2026-12-31"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

dataarray of objects
paginationobject

Pagination metadata including cursors and result counts

Other parameters
currency_codestring
json
{
  "calculation_mode": "recognition_entries",
  "data": [
    {
      "document_item_id": "di_123",
      "document_item_name": "Hosting plan",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "customer_id": "cus_123",
      "customer_name": "Acme Inc.",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "amount": 2500,
      "entry_count": 1,
      "first_period_start": "2026-02-01",
      "last_period_start": "2026-02-01",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28"
    }
  ],
  "total": 2500,
  "currency_code": "EUR",
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Get the revenue recognition schedule of a document

GET/revenue-recognition/documents/{id}

Returns every generated revenue recognition entry of one invoice, advance invoice or credit note, ordered by recognition month. The list is empty when the document has no generated schedule.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.getDocumentSchedule('REVENUERECOGNITION_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

dataarray of objects
Other parameters
totalnumber
currency_codestring
document_idstring
json
{
  "calculation_mode": "recognition_entries",
  "data": [
    {
      "id": "rre_123",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "document_item_id": "di_123",
      "document_item_name": "Telemetry platform hosting",
      "customer_id": "cus_123",
      "customer_name": "Nebula Propulsion Labs",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "recognized_amount": 2500,
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28",
      "method": "service_period_daily"
    },
    {
      "id": "rre_124",
      "document_id": "inv_123",
      "document_type": "invoice",
      "document_number": "2026-00001",
      "document_date": "2026-01-15",
      "document_item_id": "di_123",
      "document_item_name": "Telemetry platform hosting",
      "customer_id": "cus_123",
      "customer_name": "Nebula Propulsion Labs",
      "financial_category_id": "fcat_hosting",
      "financial_category_name": "Hosting revenue",
      "currency_code": "EUR",
      "source_amount": 5000,
      "recognized_amount": 2500,
      "period_start": "2026-02-01",
      "period_end": "2026-02-28",
      "service_period_start": "2026-01-01",
      "service_period_end": "2026-02-28",
      "method": "service_period_daily"
    }
  ],
  "total": 5000,
  "currency_code": "EUR",
  "document_id": "inv_123"
}
Example:

Update revenue recognition settings

PATCH/revenue-recognition/settings

Update revenue recognition settings

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.revenueRecognition.updateSettings({
  default_method: "service_period_daily"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Example:
Response

Returns

json
{
  "default_method": "service_period_daily"
}