Expenses

Expenses

Received supplier invoices and expense records.

Endpoints

IntroductionPOST/expensesPOST/expenses/customPOST/expenses/recognition/backfillPOST/expenses/recognitionsGET/expensesGET/expenses/reportGET/expenses/recognition/settingsGET/expenses/recognitions/{id}GET/expenses/{id}PATCH/expenses/recognition/settingsPATCH/expenses/{id}POST/expenses/{id}/voidDELETE/expenses/{id}DELETE/expenses/{id}/attachments/{fileId}POST/expenses/recognitions/{id}/retryGET/expenses/{id}/recognitionPOST/expenses/{id}/restorePOST/expenses/{id}/attachmentsGET/expenses/{id}/attachmentsGET/expenses/{id}/paymentsPOST/expenses/{id}/payments

The Expense object

object

Attributes

idstring

Other attributesExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

Examplejson

Copy

{
  "id": "exp_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Orbital Power Systems GmbH",
    "address": "Energieweg 8",
    "address_2": null,
    "post_code": "10115",
    "city": "Berlin",
    "state": null,
    "country": "Germany",
    "country_code": "DE",
    "tax_number": "DE987654321",
    "company_number": "HRB 98765",
    "email": "accounts@orbital-power.example",
    "phone": "+493012345678",
    "peppol_id": "0088:9876543210982",
    "is_tax_subject": true
  },
  "supplier_document_number": "OPS-2025-001",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": "2025-11-02",
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": "Ground facility maintenance — March billing period",
  "summary_classification": null,
  "items": [
    {
      "name": "Ground facility maintenance",
      "description": "Monthly ground facility maintenance",
      "quantity": 1,
      "unit": "service",
      "classification": "service",
      "price": 100,
      "gross_price": 119,
      "discounts": [],
      "taxes": [
        {
          "rate": 19,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_tax": 19
    }
  ],
  "taxes": [
    {
      "rate": 19,
      "base": 100,
      "amount": 19,
      "is_deductible": true,
      "deductible_percentage": 100,
      "reverse_charge": false
    }
  ],
  "total": 100,
  "total_with_tax": 119,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 119,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 1,
  "has_attachment": true,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-03T08:00:00.000Z"
}

---

Create expense

POST/expenses

This is the recommended endpoint for normal expense creation. Use it when Space Invoices should validate the supplied totals, tax summaries, and line items, then apply supplier handling, payment tracking initialization, and lifecycle rules.

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

typestringoptional

is_draftbooleanoptionalnullable

supplier_idstringoptionalnullable

supplierobjectoptionalnullableShow child attributes

save_supplierbooleanoptionalnullable

supplier_document_numberstringoptionalnullable

datestring<date>optionalnullable

date_receivedstring<date>optionalnullable

date_duestring<date>optionalnullable

date_servicestring<date>optionalnullable

date_service_tostring<date>optionalnullable

currency_codestringoptionalnullable

transaction_typestringoptionalnullable

referencestringoptionalnullable

notestringoptionalnullable

itemsarray of objectsoptionalnullableShow child attributes

taxesarray of objectsoptionalnullableShow child attributes

totalnumberoptionalnullable

total_with_taxnumberoptionalnullable

total_discountnumberoptionalnullable

expected_total_with_taxnumberoptionalnullable

paymentsarray of objectsoptionalnullableShow child attributes

calculation_modestringoptionalnullable

exchange_rateobjectoptionalnullableShow child attributes

summary_classificationstringoptionalnullable

metadataobjectoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.create({
  supplier: {
    name: "Office Supplies Ltd",
    tax_number: "SI12345678",
    country_code: "SI"
  },
  supplier_document_number: "2025-0417",
  date: "2025-10-03",
  total: 100,
  total_with_tax: 122,
  taxes: [
    {
      rate: 22,
      base: 100,
      amount: 22
    }
  ]
});

console.log(response);

Example:

MinimalSummary-onlyReverse-charge not deductibleCompleteBy supplier idMultiple tax ratesItemized (gross prices)Non-deductible VATPartially deductible VATMarked paid on creationForeign currencyDraft

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_9595a27b5d35015c3ef0c400",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": null,
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Office Supplies Ltd",
    "tax_number": "SI12345678",
    "country_code": "SI"
  },
  "supplier_document_number": "2025-0417",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": null,
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": null,
  "summary_classification": null,
  "items": [],
  "taxes": [
    {
      "rate": 22,
      "base": 100,
      "amount": 22,
      "is_deductible": true,
      "deductible_percentage": 100
    }
  ],
  "total": 100,
  "total_with_tax": 122,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 122,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 0,
  "has_attachment": false,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-04T08:00:00.000Z"
}

Example:

MinimalSummary-onlyCompleteDraft

---

Create expense with pre-calculated totals

POST/expenses/custom

Advanced endpoint for importing expenses that already have authoritative pre-calculated totals. Do not use this for normal expense creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.
The caller provides document totals, item totals, and tax summaries directly.
The persistence, supplier handling, payment tracking initialization, and lifecycle rules are identical to the standard create endpoint.

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

typestringoptional

is_draftbooleanoptionalnullable

supplier_idstringoptionalnullable

supplierobjectoptionalnullableShow child attributes

save_supplierbooleanoptionalnullable

supplier_document_numberstringoptionalnullable

datestring<date>optionalnullable

date_receivedstring<date>optionalnullable

date_duestring<date>optionalnullable

date_servicestring<date>optionalnullable

date_service_tostring<date>optionalnullable

currency_codestringoptionalnullable

transaction_typestringoptionalnullable

referencestringoptionalnullable

notestringoptionalnullable

itemsarray of objectsoptionalnullableShow child attributes

taxesarray of objectsoptionalnullableShow child attributes

totalnumberoptionalnullable

total_with_taxnumberoptionalnullable

total_discountnumberoptionalnullable

expected_total_with_taxnumberoptionalnullable

paymentsarray of objectsoptionalnullableShow child attributes

calculation_modestringoptionalnullable

exchange_rateobjectoptionalnullableShow child attributes

summary_classificationstringoptionalnullable

metadataobjectoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.createCustom({
  supplier: {
    name: "Office Supplies Ltd",
    tax_number: "SI12345678",
    country_code: "SI"
  },
  supplier_document_number: "2025-0417",
  date: "2025-10-03",
  total: 100,
  total_with_tax: 122,
  taxes: [
    {
      rate: 22,
      base: 100,
      amount: 22
    }
  ]
});

console.log(response);

Example:

MinimalSummary-onlyReverse-charge not deductibleCompleteBy supplier idMultiple tax ratesItemized (gross prices)Non-deductible VATPartially deductible VATMarked paid on creationForeign currencyDraft

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_9595a27b5d35015c3ef0c400",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": null,
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Office Supplies Ltd",
    "tax_number": "SI12345678",
    "country_code": "SI"
  },
  "supplier_document_number": "2025-0417",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": null,
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": null,
  "summary_classification": null,
  "items": [],
  "taxes": [
    {
      "rate": 22,
      "base": 100,
      "amount": 22,
      "is_deductible": true,
      "deductible_percentage": 100
    }
  ],
  "total": 100,
  "total_with_tax": 122,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 122,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 0,
  "has_attachment": false,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-04T08:00:00.000Z"
}

Example:

MinimalSummary-onlyCompleteDraft

---

Backfill expense recognition entries

POST/expenses/recognition/backfill

Backfill expense 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

date_fromstring<date>optionalnullable

date_tostring<date>optionalnullable

dry_runbooleanoptional

cursorstringoptionalnullable

limitintegeroptional

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.backfillExpenseRecognition({
  date_from: "2026-01-01",
  date_to: "2026-03-31",
  dry_run: true,
  limit: 100
});

console.log(response);

Example:

DryRunGenerateEntries

Response

Returns

processed_expensesinteger

generated_entriesinteger

dry_runboolean

next_cursorstringnullable

json

Copy

{
  "processed_expenses": 0,
  "generated_entries": 0,
  "dry_run": true,
  "next_cursor": "string"
}

---

Start expense recognition from a document file

POST/expenses/recognitions

Accepts one supplier invoice (PDF, JPEG, PNG, or WebP), creates an invoice-only draft expense with creation_source=ocr, and enqueues an async recognition job. For sandbox entities, no provider is called and no usage is charged: the submitted file is not stored and is replaced by a clearly marked deterministic demo invoice; the response exposes simulation_mode=sandbox_demo.

Returns 202 Accepted with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll GET /expenses/recognitions/{id} for status. Terminal success is ready_for_review or needs_attention; terminal failure is failed, with safe error_code and error_message fields.

Payment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.

X-Request-Id provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.

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.

x-request-idstringoptional

Optional idempotency key. Reusing it with the same entity and identical file replays the original result; reusing it with different file content fails with 409 Conflict.

Body parameters

filestring<binary>required

Supplier invoice PDF or image

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/image.png');
const file = new File([fileBuffer], 'image.png', { type: 'image/png' });

const response = await sdk.expenses.createRecognition({
  file
});

console.log(response);

---

List expenses

GET/expenses

Retrieve a paginated list of expenses with optional filtering.
Supports cursor-based pagination, full-text search across supplier snapshot and document fields, and suite-standard JSON query filters for date, totals, payment state, and supplier snapshot data.

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

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

has_attachmentbooleanoptional

Filter expenses by whether at least one attachment exists.

querystring<json>optional

JSON query object for filtering results. Supports MongoDB-style operators.

Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]

Allowed fields: id, number, type, is_draft, voided_at, deleted_at, supplier_id, supplier, supplier_document_number, date, date_received, date_due, date_service, date_service_to, currency_code, transaction_type, reference, note, summary_classification, total, total_with_tax, total_paid, total_due, paid_in_full, created_at, updated_at, metadata

Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range

order_byoptional

Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with - for descending order. When paginating, reuse cursors only with the same effective ordering.

searchstringoptional

Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.list({ limit: 20 });

console.log(response);

Response

Returns

dataarray of objectsShow child attributes

paginationobjectShow child attributes

Pagination metadata including cursors and result counts

json

Copy

{
  "data": [
    {
      "id": "exp_6595a27b5d35015c3ef0c3fd",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
      "type": "invoice",
      "is_draft": false,
      "voided_at": null,
      "supplier": {
        "name": "Orbital Power Systems GmbH",
        "address": "Energieweg 8",
        "address_2": null,
        "post_code": "10115",
        "city": "Berlin",
        "state": null,
        "country": "Germany",
        "country_code": "DE",
        "tax_number": "DE987654321",
        "company_number": "HRB 98765",
        "email": "accounts@orbital-power.example",
        "phone": "+493012345678",
        "peppol_id": "0088:9876543210982",
        "is_tax_subject": true
      },
      "supplier_document_number": "OPS-2025-001",
      "date": "2025-10-03",
      "date_received": "2025-10-03",
      "date_due": "2025-11-02",
      "date_service": null,
      "date_service_to": null,
      "currency_code": "EUR",
      "transaction_type": "domestic",
      "reference": "DE00-2025-001",
      "note": "Ground facility maintenance — March billing period",
      "summary_classification": null,
      "items": [
        {
          "name": "Ground facility maintenance",
          "description": "Monthly ground facility maintenance",
          "quantity": 1,
          "unit": "service",
          "classification": "service",
          "price": 100,
          "gross_price": 119,
          "discounts": [],
          "taxes": [
            {
              "rate": 19,
              "amount": 19,
              "is_deductible": true,
              "deductible_percentage": 100
            }
          ],
          "total": 100,
          "total_with_tax": 119,
          "total_tax": 19
        }
      ],
      "taxes": [
        {
          "rate": 19,
          "base": 100,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100,
          "reverse_charge": false
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_discount": 0,
      "total_paid": 0,
      "total_due": 119,
      "paid_in_full": false,
      "exchange_rate": null,
      "attachment_count": 1,
      "has_attachment": true,
      "metadata": {
        "source": "manual"
      },
      "created_at": "2025-10-03T08:00:00.000Z",
      "updated_at": "2025-10-03T08:00:00.000Z"
    },
    {
      "id": "exp_7595a27b5d35015c3ef0c3fe",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
      "type": "invoice",
      "is_draft": false,
      "voided_at": null,
      "supplier": {
        "name": "Orbital Power Systems GmbH",
        "address": "Energieweg 8",
        "address_2": null,
        "post_code": "10115",
        "city": "Berlin",
        "state": null,
        "country": "Germany",
        "country_code": "DE",
        "tax_number": "DE987654321",
        "company_number": "HRB 98765",
        "email": "accounts@orbital-power.example",
        "phone": "+493012345678",
        "peppol_id": "0088:9876543210982",
        "is_tax_subject": true
      },
      "supplier_document_number": "AP-CUSTOM-001",
      "date": "2025-10-03",
      "date_received": "2025-10-03",
      "date_due": "2025-11-02",
      "date_service": null,
      "date_service_to": null,
      "currency_code": "EUR",
      "transaction_type": "domestic",
      "reference": "DE00-2025-001",
      "note": "Supplier provided totals only",
      "summary_classification": "service",
      "items": [],
      "taxes": [
        {
          "rate": 19,
          "base": 45.22,
          "amount": 8.59,
          "is_deductible": true,
          "deductible_percentage": 100,
          "reverse_charge": false
        },
        {
          "rate": 0,
          "base": 125.63,
          "amount": 0,
          "is_deductible": true,
          "deductible_percentage": 100,
          "reverse_charge": false
        }
      ],
      "total": 170.85,
      "total_with_tax": 179.44,
      "total_discount": 0,
      "total_paid": 0,
      "total_due": 179.44,
      "paid_in_full": false,
      "exchange_rate": null,
      "attachment_count": 0,
      "has_attachment": false,
      "metadata": {
        "source": "manual"
      },
      "created_at": "2025-10-03T08:00:00.000Z",
      "updated_at": "2025-10-04T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Example:

DefaultSearch

---

Get expenses by financial category

GET/expenses/report

Return finalized expense net amounts grouped by financial category. Depending on expense-recognition settings and line overrides, recognized amounts use document dates or generated daily service-period schedules.

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_fromstring<date>required

Report start date in YYYY-MM-DD format. Must be the first calendar day of a month.

date_tostring<date>required

Report end date in YYYY-MM-DD format. Must be the final calendar day of a month.

basisstringoptional

recognized returns expense recognized inside each period. deferred returns the remaining future expense 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"

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getExpenseCategoryReport({
  date_from: "2026-01-01",
  date_to: "2026-12-31"
});

console.log(response);

Response

Returns

basisstring

group_bystring

calculation_modestring

periodsarray of objectsShow child attributes

seriesarray of objectsShow child attributes

totalsarray of numbers

totalnumber

currency_codestring

date_fromstring

date_tostring

json

Copy

{
  "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_office",
      "financial_category_id": "fcat_office",
      "name": "Office expenses",
      "color": "#2563eb",
      "values": [
        1200,
        850
      ],
      "total": 2050
    },
    {
      "key": "uncategorized",
      "financial_category_id": null,
      "name": "Uncategorized",
      "color": null,
      "values": [
        50,
        125
      ],
      "total": 175
    }
  ],
  "totals": [
    1250,
    975
  ],
  "total": 2225,
  "currency_code": "EUR",
  "date_from": "2026-01-01",
  "date_to": "2026-02-28"
}

---

Get expense recognition settings

GET/expenses/recognition/settings

Get expense 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.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getRecognitionSettings();

console.log(response);

Response

Returns

default_methodstring

json

Copy

{
  "default_method": "off"
}

---

Get expense recognition job by ID

GET/expenses/recognitions/{id}

Returns recognition job status, extraction results, warnings, reconciliation, and advisory payment suggestion. Entity-scoped.

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

idstringrequired

Expense recognition job ID

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getRecognition("erj_6595a27b5d35015c3ef0c3fd");

console.log(response);

Response

Returns

idstring

Recognition job ID

Other parametersExpand all

entity_idstring

expense_idstring

file_metadata_idstring

statusstring

providerstringnullable

modelstringnullable

parser_versionstringnullable

attemptsinteger

max_attemptsinteger

pages_processedintegernullable

page_countintegernullable

warningsarray of objectsnullableShow child attributes

provenanceobjectnullableShow child attributes

reconciliationobjectnullableShow child attributes

payment_suggestionobjectnullableShow child attributes

extracted_draftobjectnullableShow child attributes

error_codestringnullable

error_messagestringnullable

request_idstringnullable

source_filenamestringnullable

source_mime_typestring

source_bytesinteger

source_content_sha256string

simulation_modestringnullable

source_replacedboolean

expense_updated_at_snapshotstring<date-time>

queued_atstring<date-time>

started_atstring<date-time>nullable

completed_atstring<date-time>nullable

created_atstring<date-time>

updated_atstring<date-time>

json

Copy

{
  "id": "erj_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
  "file_metadata_id": "fil_6595a27b5d35015c3ef0c3fd",
  "status": "queued",
  "attempts": 0,
  "max_attempts": 3,
  "source_mime_type": "application/pdf",
  "source_bytes": 48321,
  "source_content_sha256": "f5c4c9c33d9b42e4f130cb593f17741b30e0fb23ac95a6d91d01bf438467a17c",
  "simulation_mode": null,
  "source_replaced": false,
  "expense_updated_at_snapshot": "2026-07-11T08:00:00.000Z",
  "queued_at": "2026-07-11T08:00:00.000Z",
  "created_at": "2026-07-11T08:00:00.000Z",
  "updated_at": "2026-07-11T08:00:00.000Z"
}

---

Get expense by ID

GET/expenses/{id}

Get expense by ID

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

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.get("inv_6595a27b5d35015c3ef0c3fd");

console.log(response);

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Orbital Power Systems GmbH",
    "address": "Energieweg 8",
    "address_2": null,
    "post_code": "10115",
    "city": "Berlin",
    "state": null,
    "country": "Germany",
    "country_code": "DE",
    "tax_number": "DE987654321",
    "company_number": "HRB 98765",
    "email": "accounts@orbital-power.example",
    "phone": "+493012345678",
    "peppol_id": "0088:9876543210982",
    "is_tax_subject": true
  },
  "supplier_document_number": "OPS-2025-001",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": "2025-11-02",
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": "Ground facility maintenance — March billing period",
  "summary_classification": null,
  "items": [
    {
      "name": "Ground facility maintenance",
      "description": "Monthly ground facility maintenance",
      "quantity": 1,
      "unit": "service",
      "classification": "service",
      "price": 100,
      "gross_price": 119,
      "discounts": [],
      "taxes": [
        {
          "rate": 19,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_tax": 19
    }
  ],
  "taxes": [
    {
      "rate": 19,
      "base": 100,
      "amount": 19,
      "is_deductible": true,
      "deductible_percentage": 100,
      "reverse_charge": false
    }
  ],
  "total": 100,
  "total_with_tax": 119,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 119,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 1,
  "has_attachment": true,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-03T08:00:00.000Z"
}

---

Update expense recognition settings

PATCH/expenses/recognition/settings

Update expense 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

default_methodstringoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.updateRecognitionSettings({
  default_method: "service_period_daily"
});

console.log(response);

Example:

UseServicePeriodDailyDisableGeneratedRecognition

Response

Returns

default_methodstring

json

Copy

{
  "default_method": "off"
}

---

Update expense

PATCH/expenses/{id}

Update expense

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

Body parameters

is_draftbooleanoptional

supplier_idstringoptionalnullable

supplierobjectoptionalnullableShow child attributes

save_supplierbooleanoptionalnullable

supplier_document_numberstringoptionalnullable

datestring<date>optionalnullable

date_receivedstring<date>optionalnullable

date_duestring<date>optionalnullable

date_servicestring<date>optionalnullable

date_service_tostring<date>optionalnullable

currency_codestringoptionalnullable

transaction_typestringoptionalnullable

referencestringoptionalnullable

notestringoptionalnullable

itemsarray of objectsoptionalnullableShow child attributes

taxesarray of objectsoptionalnullableShow child attributes

totalnumberoptionalnullable

total_with_taxnumberoptionalnullable

total_discountnumberoptionalnullable

expected_total_with_taxnumberoptionalnullable

calculation_modestringoptionalnullable

exchange_rateobjectoptionalnullableShow child attributes

summary_classificationstringoptionalnullable

metadataobjectoptionalnullable

typestringoptional

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.update("inv_6595a27b5d35015c3ef0c3fd", {
  is_draft: false,
  supplier_document_number: "OPS-2025-099",
  date: "2025-10-12",
  date_received: "2025-10-13",
  currency_code: "EUR",
  summary_classification: "service",
  taxes: [
    {
      rate: 22,
      base: 80,
      amount: 17.6
    }
  ],
  total: 80,
  total_with_tax: 97.6
});

console.log(response);

Example:

Post draft documentUpdate note

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Orbital Power Systems GmbH",
    "address": "Energieweg 8",
    "address_2": null,
    "post_code": "10115",
    "city": "Berlin",
    "state": null,
    "country": "Germany",
    "country_code": "DE",
    "tax_number": "DE987654321",
    "company_number": "HRB 98765",
    "email": "accounts@orbital-power.example",
    "phone": "+493012345678",
    "peppol_id": "0088:9876543210982",
    "is_tax_subject": true
  },
  "supplier_document_number": "OPS-2025-001",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": "2025-11-02",
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": "Ground facility maintenance — March billing period",
  "summary_classification": null,
  "items": [
    {
      "name": "Ground facility maintenance",
      "description": "Monthly ground facility maintenance",
      "quantity": 1,
      "unit": "service",
      "classification": "service",
      "price": 100,
      "gross_price": 119,
      "discounts": [],
      "taxes": [
        {
          "rate": 19,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_tax": 19
    }
  ],
  "taxes": [
    {
      "rate": 19,
      "base": 100,
      "amount": 19,
      "is_deductible": true,
      "deductible_percentage": 100,
      "reverse_charge": false
    }
  ],
  "total": 100,
  "total_with_tax": 119,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 119,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 1,
  "has_attachment": true,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-20T00:00:00.000Z"
}

---

Void expense

POST/expenses/{id}/void

Voids a posted expense and frees its supplier_document_number for reuse by a new expense from the same supplier. A voided expense can be restored unless that number has since been reused by another active expense from the same supplier.

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

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.void("inv_6595a27b5d35015c3ef0c3fd");

console.log(response);

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
  "type": "invoice",
  "is_draft": false,
  "voided_at": "2025-10-20T12:00:00.000Z",
  "supplier": {
    "name": "Orbital Power Systems GmbH",
    "address": "Energieweg 8",
    "address_2": null,
    "post_code": "10115",
    "city": "Berlin",
    "state": null,
    "country": "Germany",
    "country_code": "DE",
    "tax_number": "DE987654321",
    "company_number": "HRB 98765",
    "email": "accounts@orbital-power.example",
    "phone": "+493012345678",
    "peppol_id": "0088:9876543210982",
    "is_tax_subject": true
  },
  "supplier_document_number": "OPS-2025-001",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": "2025-11-02",
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": "Ground facility maintenance — March billing period",
  "summary_classification": null,
  "items": [
    {
      "name": "Ground facility maintenance",
      "description": "Monthly ground facility maintenance",
      "quantity": 1,
      "unit": "service",
      "classification": "service",
      "price": 100,
      "gross_price": 119,
      "discounts": [],
      "taxes": [
        {
          "rate": 19,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_tax": 19
    }
  ],
  "taxes": [
    {
      "rate": 19,
      "base": 100,
      "amount": 19,
      "is_deductible": true,
      "deductible_percentage": 100,
      "reverse_charge": false
    }
  ],
  "total": 100,
  "total_with_tax": 119,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 119,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 1,
  "has_attachment": true,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-03T08:00:00.000Z"
}

---

Delete draft expense

DELETE/expenses/{id}

Only draft expenses can be deleted; posted expenses must be voided instead.

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

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.expenses.delete("inv_6595a27b5d35015c3ef0c3fd");

console.log('Deleted successfully');

---

Delete expense attachment

DELETE/expenses/{id}/attachments/{fileId}

Delete expense attachment

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

idstringrequired

fileIdstringrequired

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.expenses.deleteExpenseAttachment('EXPENSES_ID', 'FILE_ID');

console.log('Deleted successfully');

---

Retry recognition after a transient failure

POST/expenses/recognitions/{id}/retry

Re-queues a failed recognition job only after an allowed transient provider or source-service error and when attempts remain below max_attempts. Bad or unsupported content should be uploaded as a new expense instead.

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

idstringrequired

Expense recognition job ID

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.retryRecognition("erj_6595a27b5d35015c3ef0c3fd");

console.log(response);

---

Get the latest recognition job for an expense

GET/expenses/{id}/recognition

Returns the latest recognition job linked to the expense, or job: null for manually created expenses. This makes recognition state durable across navigation.

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

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getLatestRecognition("inv_6595a27b5d35015c3ef0c3fd");

console.log(response);

Response

Returns

jobobjectnullableShow child attributes

json

Copy

{
  "job": {
    "id": "erj_6595a27b5d35015c3ef0c3fd",
    "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
    "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
    "file_metadata_id": "fil_6595a27b5d35015c3ef0c3fd",
    "status": "queued",
    "attempts": 0,
    "max_attempts": 3,
    "source_mime_type": "application/pdf",
    "source_bytes": 48321,
    "source_content_sha256": "f5c4c9c33d9b42e4f130cb593f17741b30e0fb23ac95a6d91d01bf438467a17c",
    "simulation_mode": null,
    "source_replaced": false,
    "expense_updated_at_snapshot": "2026-07-11T08:00:00.000Z",
    "queued_at": "2026-07-11T08:00:00.000Z",
    "created_at": "2026-07-11T08:00:00.000Z",
    "updated_at": "2026-07-11T08:00:00.000Z"
  }
}

---

Restore (un-void) an expense

POST/expenses/{id}/restore

Reverses a void, re-activating the expense. Fails with 409 if its supplier_document_number has since been reused by another active expense from the same supplier.

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

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.restoreExpense("inv_6595a27b5d35015c3ef0c3fd");

console.log(response);

Response

Returns

idstring

Other parametersExpand all

numberstring

entity_idstring

supplier_idstringnullable

typestring

is_draftboolean

voided_atstring<date-time>nullable

deleted_atstring<date-time>nullable

supplierobjectnullableShow child attributes

supplier_document_numberstringnullable

datestringnullable

date_receivedstringnullable

date_duestringnullable

date_servicestringnullable

date_service_tostringnullable

currency_codestringnullable

transaction_typestringnullable

referencestringnullable

notestringnullable

summary_classificationstringnullable

taxesarray of objectsShow child attributes

totalnumbernullable

total_with_taxnumbernullable

total_convertednumbernullable

total_with_tax_convertednumbernullable

total_discountnumber

creation_sourcestring

total_paidnumber

total_duenumber

paid_in_fullboolean

date_yearinteger

exchange_rateobjectnullableShow child attributes

metadatastringnullable

created_atstring<date-time>

updated_atstring<date-time>

itemsarray of objectsShow child attributes

attachment_countinteger

has_attachmentboolean

json

Copy

{
  "id": "exp_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "supplier_id": "sup_6595a27b5d35015c3ef0c3fd",
  "type": "invoice",
  "is_draft": false,
  "voided_at": null,
  "supplier": {
    "name": "Orbital Power Systems GmbH",
    "address": "Energieweg 8",
    "address_2": null,
    "post_code": "10115",
    "city": "Berlin",
    "state": null,
    "country": "Germany",
    "country_code": "DE",
    "tax_number": "DE987654321",
    "company_number": "HRB 98765",
    "email": "accounts@orbital-power.example",
    "phone": "+493012345678",
    "peppol_id": "0088:9876543210982",
    "is_tax_subject": true
  },
  "supplier_document_number": "OPS-2025-001",
  "date": "2025-10-03",
  "date_received": "2025-10-03",
  "date_due": "2025-11-02",
  "date_service": null,
  "date_service_to": null,
  "currency_code": "EUR",
  "transaction_type": "domestic",
  "reference": "DE00-2025-001",
  "note": "Ground facility maintenance — March billing period",
  "summary_classification": null,
  "items": [
    {
      "name": "Ground facility maintenance",
      "description": "Monthly ground facility maintenance",
      "quantity": 1,
      "unit": "service",
      "classification": "service",
      "price": 100,
      "gross_price": 119,
      "discounts": [],
      "taxes": [
        {
          "rate": 19,
          "amount": 19,
          "is_deductible": true,
          "deductible_percentage": 100
        }
      ],
      "total": 100,
      "total_with_tax": 119,
      "total_tax": 19
    }
  ],
  "taxes": [
    {
      "rate": 19,
      "base": 100,
      "amount": 19,
      "is_deductible": true,
      "deductible_percentage": 100,
      "reverse_charge": false
    }
  ],
  "total": 100,
  "total_with_tax": 119,
  "total_discount": 0,
  "total_paid": 0,
  "total_due": 119,
  "paid_in_full": false,
  "exchange_rate": null,
  "attachment_count": 1,
  "has_attachment": true,
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-10-03T08:00:00.000Z",
  "updated_at": "2025-10-03T08:00:00.000Z"
}

---

Upload expense attachment

POST/expenses/{id}/attachments

Upload expense attachment

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

idstringrequired

Body parameters

filestring<binary>required

File to upload

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/image.png');
const file = new File([fileBuffer], 'image.png', { type: 'image/png' });

const response = await sdk.expenses.uploadExpenseAttachment('ID', {
  file
});

console.log(response);

Response

Returns

idstring

Other parametersExpand all

entity_idstring

business_unit_idstringnullable

invoice_idstringnullable

estimate_idstringnullable

credit_note_idstringnullable

advance_invoice_idstringnullable

expense_idstringnullable

categorystring

urlstring

secureUrlstring

publicIdstring

formatstring

widthintegernullable

heightintegernullable

bytesinteger

filenamestringnullable

mime_typestring

metadatastringnullable

cache_keystringnullable

created_atstring<date-time>

updated_atstring<date-time>

secure_urlstring

public_idstring

json

Copy

{
  "id": "file_9595a27b5d35015c3ef0c3fa",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
  "category": "attachment",
  "url": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
  "secureUrl": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
  "publicId": "si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
  "secure_url": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
  "public_id": "si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
  "format": "pdf",
  "width": null,
  "height": null,
  "bytes": 245678,
  "filename": "supplier-invoice.pdf",
  "mime_type": "application/pdf",
  "metadata": {},
  "created_at": "2025-10-03T08:05:00.000Z",
  "updated_at": "2025-10-03T08:05:00.000Z"
}

---

List expense attachments

GET/expenses/{id}/attachments

List expense attachments

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

idstringrequired

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getExpenseAttachments('EXPENSES_ID');

console.log(response);

Response

Returns

dataarray of objectsShow child attributes

paginationobjectShow child attributes

Pagination metadata including cursors and result counts

json

Copy

{
  "data": [
    {
      "id": "file_9595a27b5d35015c3ef0c3fa",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "invoice_id": null,
      "estimate_id": null,
      "credit_note_id": null,
      "advance_invoice_id": null,
      "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
      "category": "attachment",
      "url": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
      "secureUrl": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
      "publicId": "si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
      "secure_url": "https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
      "public_id": "si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf",
      "format": "pdf",
      "width": null,
      "height": null,
      "bytes": 245678,
      "filename": "supplier-invoice.pdf",
      "mime_type": "application/pdf",
      "metadata": {},
      "created_at": "2025-10-03T08:05:00.000Z",
      "updated_at": "2025-10-03T08:05:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

---

List payments affecting an expense

GET/expenses/{id}/payments

List payments affecting an expense

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

idstringrequired

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.getExpensePayments('EXPENSES_ID');

console.log(response);

Response

Returns

dataarray of objectsShow child attributes

paginationobjectShow child attributes

Pagination metadata including cursors and result counts

json

Copy

{
  "data": [
    {
      "id": "pmt_abc123def456",
      "invoice_id": null,
      "credit_note_id": null,
      "advance_invoice_id": null,
      "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
      "applied_to_expense_id": null,
      "amount": 122,
      "amount_converted": 122,
      "currency_code": "EUR",
      "type": "bank_transfer",
      "date": "2025-10-10T00:00:00.000Z",
      "reference": "DE00-2025-001",
      "tag": null,
      "note": "Supplier payment",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "metadata": {},
      "deleted_at": null,
      "created_at": "2025-10-10T08:00:00.000Z",
      "updated_at": "2025-10-10T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

---

Create a payment for an expense

POST/expenses/{id}/payments

Create a payment for an expense

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

idstringrequired

Body parameters

amountnumberrequired

Payment amount in the linked document currency's major unit; for EUR, 29.90 means €29.90, not 2,990 cents.

typestringrequired

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "advance"

Other parametersExpand all

datestringoptional

tagstringoptionalnullable

referencestringoptionalnullable

notestringoptionalnullable

metadataobjectoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.expenses.createExpensePayment('EXPENSES_ID', {
  amount: 122,
  type: "bank_transfer",
  date: "2025-10-10",
  reference: "DE00-2025-001",
  note: "Supplier payment"
});

console.log(response);

Response

Returns

idstring

Other parametersExpand all

invoice_idstringnullable

credit_note_idstringnullable

advance_invoice_idstringnullable

expense_idstringnullable

applied_to_expense_idstringnullable

amountnumber

currency_codestring

amount_convertednumber

typestring

datestring<date-time>

tagstringnullable

referencestringnullable

notestringnullable

entity_idstring

metadataobjectnullable

deleted_atstring<date-time>nullable

created_atstring<date-time>

updated_atstring<date-time>

InvoiceobjectnullableShow child attributes

CreditNoteobjectnullableShow child attributes

AdvanceInvoiceobjectnullableShow child attributes

ExpenseobjectnullableShow child attributes

AppliedToExpenseobjectnullableShow child attributes

json

Copy

{
  "id": "pmt_abc123def456",
  "invoice_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "expense_id": "exp_6595a27b5d35015c3ef0c3fd",
  "applied_to_expense_id": null,
  "amount": 122,
  "amount_converted": 122,
  "currency_code": "EUR",
  "type": "bank_transfer",
  "date": "2025-10-10T00:00:00.000Z",
  "reference": "DE00-2025-001",
  "tag": null,
  "note": "Supplier payment",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "metadata": {},
  "deleted_at": null,
  "created_at": "2025-10-10T08:00:00.000Z",
  "updated_at": "2025-10-10T08:00:00.000Z"
}

---