Financial Categories

Financial Categories

Entity-scoped reporting categories shared by saved items, document lines, revenue analytics, and future expense reporting.

Endpoints

IntroductionPOST/financial-categoriesGET/financial-categoriesGET/financial-categories/revenue-summaryPATCH/financial-categories/{id}PATCH/financial-categories/document-items/batchPATCH/financial-categories/document-items/{id}DELETE/financial-categories/{id}

The Financial Category object

object

Attributes

idstring

Other attributesExpand all

entity_idstring

namestring

keystring

colorstringnullable

sort_orderinteger

archived_atstring<date-time>nullable

created_atstring<date-time>

updated_atstring<date-time>

---

Create a financial category

POST/financial-categories

Create a financial category

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

namestringrequired

Other parametersExpand all

keystringoptionalnullable

colorstringoptionalnullable

sort_orderintegeroptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.financialCategories.create({
  name: "Mission services",
  color: "#93c5fd",
  sort_order: 0
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Example:

MinimalExplicit keyHosting revenueImplementation revenue

Response

Returns

idstring

Other parametersExpand all

entity_idstring

namestring

keystring

colorstringnullable

sort_orderinteger

archived_atstring<date-time>nullable

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "fcat_abc123",
  "entity_id": "ent_abc123",
  "name": "Mission services",
  "key": "mission-services",
  "color": "#93c5fd",
  "sort_order": 0,
  "archived_at": null,
  "created_at": "2026-04-15T10:00:00.000Z",
  "updated_at": "2026-04-15T10:00:00.000Z"
}

---

List financial categories

GET/financial-categories

List financial categories

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

include_archivedbooleanoptional

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.financialCategories.list({
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

dataarray of objectsShow child attributes

json

Copy

{
  "data": [
    {
      "id": "fcat_abc123",
      "entity_id": "ent_abc123",
      "name": "Mission services",
      "key": "mission-services",
      "color": "#93c5fd",
      "sort_order": 0,
      "archived_at": null,
      "created_at": "2026-04-15T10:00:00.000Z",
      "updated_at": "2026-04-15T10:00:00.000Z"
    }
  ]
}

---

Get accrued revenue grouped by financial category

GET/financial-categories/revenue-summary

Get accrued revenue grouped by financial category

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

Start date filter (ISO 8601 date).

date_tostringrequired

End date filter (ISO 8601 date).

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

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

console.log(response);

Response

Returns

dataarray of objectsShow child attributes

Other parametersExpand all

totalnumber

currency_codestring

date_fromstring

date_tostring

json

Copy

{
  "data": [
    {
      "financial_category_id": "fcat_abc123",
      "name": "Mission services",
      "color": "#93c5fd",
      "amount": 12000,
      "percentage": 75,
      "currency_code": "EUR"
    },
    {
      "financial_category_id": null,
      "name": "Uncategorized",
      "color": null,
      "amount": 4000,
      "percentage": 25,
      "currency_code": "EUR"
    }
  ],
  "total": 16000,
  "currency_code": "EUR",
  "date_from": "2026-01-01",
  "date_to": "2026-12-31"
}

---

Update a financial category

PATCH/financial-categories/{id}

Update a financial category

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_.

Body parameters

namestringoptionalnullable

keystringoptionalnullable

colorstringoptionalnullable

sort_orderintegeroptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.financialCategories.update('FINANCIAL_CATEGORY_ID', {
  name: "Mission services retainer",
  color: "#60a5fa"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parametersExpand all

entity_idstring

namestring

keystring

colorstringnullable

sort_orderinteger

archived_atstring<date-time>nullable

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "fcat_abc123",
  "entity_id": "ent_abc123",
  "name": "Mission services retainer",
  "key": "mission-services",
  "color": "#60a5fa",
  "sort_order": 0,
  "archived_at": null,
  "created_at": "2026-04-15T10:00:00.000Z",
  "updated_at": "2026-04-15T12:00:00.000Z"
}

---

Atomically update saved categories for multiple document line items

PATCH/financial-categories/document-items/batch

Atomically update saved categories for multiple document line items

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

assignmentsarray of objectsrequiredShow child attributes

Atomic batch of saved document line category updates.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.financialCategories.updateDocumentItemFinancialCategories({
  assignments: [
    {
      id: "item_abc123",
      financial_category_id: "fcat_abc123"
    },
    {
      id: "item_def456",
      financial_category_id: null
    }
  ]
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Example:

MinimalAssign by line

Response

json

Copy

[
  {
    "document_item_id": "item_abc123",
    "financial_category_id": "fcat_abc123"
  },
  {
    "document_item_id": "item_def456",
    "financial_category_id": null
  }
]

---

Update the saved category for a document line item

PATCH/financial-categories/document-items/{id}

Update the saved category for a document line item

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_.

Body parameters

financial_category_idstringoptionalnullable

financial_category_keystringoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.financialCategories.updateDocumentItemFinancialCategory('FINANCIAL_CATEGORY_ID', {
  financial_category_id: "fcat_abc123"
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Example:

MinimalAssign by keyClear assignment

Response

Returns

document_item_idstring

financial_category_idstringnullable

json

Copy

{
  "document_item_id": "item_abc123",
  "financial_category_id": "fcat_abc123"
}

---

Archive a financial category

DELETE/financial-categories/{id}

Archive a financial category

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_.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.financialCategories.delete('FINANCIAL_CATEGORY_ID', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log('Deleted successfully');

---