Skip to content
Space Invoices Documentation

Business Units

Business Units

Manage entity-owned business units used for document branding, defaults, and integrations.

Endpoints
IntroductionPOST/business-unitsGET/business-unitsGET/business-units/{id}PATCH/business-units/{id}DELETE/business-units/{id}

The Business Unit object

object

Attributes

idstring
Other attributes
entity_idstring
namestring
addressstringnullable
address_2stringnullable
post_codestringnullable
citystringnullable
statestringnullable
countrystringnullable
country_codestringnullable
emailstringnullable
phonestringnullable
websitestringnullable
settingsobject
numbering_indexinteger
logo_file_idstringnullable
signature_file_idstringnullable
is_activeboolean
deleted_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
Examplejson
{
  "id": "unit_7595a27b5d35015c3ef0c3fe",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "name": "Starward Berlin Office",
  "address": "Friedrichstraße 95",
  "address_2": "Floor 2",
  "post_code": "10117",
  "city": "Berlin",
  "state": "Berlin",
  "country": "Germany",
  "country_code": "DE",
  "email": "berlin@starward.example",
  "phone": "+49 30 12345678",
  "website": "https://berlin.starward.example",
  "settings": {
    "pdf_template": "modern",
    "primary_color": "#1D4ED8",
    "logo_scale_percent": 110,
    "default_invoice_note": "Issued by {entity_name} / {unit_name}",
    "default_invoice_payment_terms": "Payment due in 15 days.",
    "document_footer": "Questions? Contact {entity_email}.",
    "default_document_signature": "Starward Berlin Office team",
    "bank_accounts": [
      {
        "type": "iban",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bank_name": "Commerzbank AG",
        "name": "Starward Berlin Office Account",
        "is_default": true
      }
    ],
    "delivery_note_hide_prices": false,
    "credit_note_negative_values": true,
    "show_payment_amounts": true,
    "email_defaults": {
      "invoice_subject": "Invoice {document_number} from {entity_name}",
      "invoice_body": "Hello {customer_name},\n\nPlease find your invoice attached."
    },
    "translations": {
      "default_invoice_note": {
        "de-DE": "Ausgestellt von {entity_name} / {unit_name}"
      },
      "default_invoice_payment_terms": {
        "de-DE": "Zahlbar innerhalb von 15 Tagen."
      },
      "document_footer": {
        "de-DE": "Fragen? Kontaktieren Sie {entity_email}."
      },
      "default_document_signature": {
        "de-DE": "Starward Berlin Office Team"
      },
      "email_defaults": {
        "invoice_subject": {
          "de-DE": "Rechnung {document_number} von {entity_name}"
        },
        "invoice_body": {
          "de-DE": "Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."
        }
      }
    }
  },
  "numbering_index": 2,
  "logo_file_id": "file_6595a27b5d35015c3ef0c3ff",
  "signature_file_id": "file_8595a27b5d35015c3ef0c400",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-09-01T00:00:00.000Z",
  "deleted_at": null
}

Create a business unit

POST/business-units

Create a business unit

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 parameters
addressstringoptionalnullable
address_2stringoptionalnullable
post_codestringoptionalnullable
citystringoptionalnullable
statestringoptionalnullable
countrystringoptionalnullable
country_codestringoptionalnullable
emailstringoptionalnullable
phonestringoptionalnullable
websitestringoptionalnullable
settingsobjectoptionalnullable
logo_file_idstringoptionalnullable
signature_file_idstringoptionalnullable
import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.businessUnits.create({
  name: "Starward Berlin Office"
});

console.log(response);
Example:
Response

Returns

idstring
Other parameters
entity_idstring
namestring
addressstringnullable
address_2stringnullable
post_codestringnullable
citystringnullable
statestringnullable
countrystringnullable
country_codestringnullable
emailstringnullable
phonestringnullable
websitestringnullable
settingsobject
numbering_indexinteger
logo_file_idstringnullable
signature_file_idstringnullable
is_activeboolean
deleted_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
json
{
  "id": "unit_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "name": "Starward Berlin Office",
  "address": null,
  "address_2": null,
  "post_code": null,
  "city": null,
  "state": null,
  "country": null,
  "country_code": null,
  "email": null,
  "phone": null,
  "website": null,
  "settings": {},
  "numbering_index": 1,
  "logo_file_id": null,
  "signature_file_id": null,
  "is_active": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z",
  "deleted_at": null
}
Example:

List business units

GET/business-units

List business units

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.

include_archivedbooleanoptionalnullable

Include archived business units in the response.

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

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

console.log(response);
Response

Returns

dataarray of objects
paginationobject
json
{
  "data": [
    {
      "id": "unit_6595a27b5d35015c3ef0c3fd",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "name": "Starward Berlin Office",
      "address": null,
      "address_2": null,
      "post_code": null,
      "city": null,
      "state": null,
      "country": null,
      "country_code": null,
      "email": null,
      "phone": null,
      "website": null,
      "settings": {},
      "numbering_index": 1,
      "logo_file_id": null,
      "signature_file_id": null,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z",
      "deleted_at": null
    },
    {
      "id": "unit_7595a27b5d35015c3ef0c3fe",
      "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
      "name": "Starward Berlin Office",
      "address": "Friedrichstraße 95",
      "address_2": "Floor 2",
      "post_code": "10117",
      "city": "Berlin",
      "state": "Berlin",
      "country": "Germany",
      "country_code": "DE",
      "email": "berlin@starward.example",
      "phone": "+49 30 12345678",
      "website": "https://berlin.starward.example",
      "settings": {
        "pdf_template": "modern",
        "primary_color": "#1D4ED8",
        "logo_scale_percent": 110,
        "default_invoice_note": "Issued by {entity_name} / {unit_name}",
        "default_invoice_payment_terms": "Payment due in 15 days.",
        "document_footer": "Questions? Contact {entity_email}.",
        "default_document_signature": "Starward Berlin Office team",
        "bank_accounts": [
          {
            "type": "iban",
            "iban": "DE89370400440532013000",
            "bic": "COBADEFFXXX",
            "bank_name": "Commerzbank AG",
            "name": "Starward Berlin Office Account",
            "is_default": true
          }
        ],
        "delivery_note_hide_prices": false,
        "credit_note_negative_values": true,
        "show_payment_amounts": true,
        "email_defaults": {
          "invoice_subject": "Invoice {document_number} from {entity_name}",
          "invoice_body": "Hello {customer_name},\n\nPlease find your invoice attached."
        },
        "translations": {
          "default_invoice_note": {
            "de-DE": "Ausgestellt von {entity_name} / {unit_name}"
          },
          "default_invoice_payment_terms": {
            "de-DE": "Zahlbar innerhalb von 15 Tagen."
          },
          "document_footer": {
            "de-DE": "Fragen? Kontaktieren Sie {entity_email}."
          },
          "default_document_signature": {
            "de-DE": "Starward Berlin Office Team"
          },
          "email_defaults": {
            "invoice_subject": {
              "de-DE": "Rechnung {document_number} von {entity_name}"
            },
            "invoice_body": {
              "de-DE": "Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."
            }
          }
        }
      },
      "numbering_index": 2,
      "logo_file_id": "file_6595a27b5d35015c3ef0c3ff",
      "signature_file_id": "file_8595a27b5d35015c3ef0c400",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-09-01T00:00:00.000Z",
      "deleted_at": null
    }
  ],
  "pagination": {
    "total": 2,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Get a business unit

GET/business-units/{id}

Get a business unit

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

Query parameters

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

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

console.log(response);
Response

Returns

idstring
Other parameters
entity_idstring
namestring
addressstringnullable
address_2stringnullable
post_codestringnullable
citystringnullable
statestringnullable
countrystringnullable
country_codestringnullable
emailstringnullable
phonestringnullable
websitestringnullable
settingsobject
numbering_indexinteger
logo_file_idstringnullable
signature_file_idstringnullable
is_activeboolean
deleted_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
json
{
  "id": "unit_7595a27b5d35015c3ef0c3fe",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "name": "Starward Berlin Office",
  "address": "Friedrichstraße 95",
  "address_2": "Floor 2",
  "post_code": "10117",
  "city": "Berlin",
  "state": "Berlin",
  "country": "Germany",
  "country_code": "DE",
  "email": "berlin@starward.example",
  "phone": "+49 30 12345678",
  "website": "https://berlin.starward.example",
  "settings": {
    "pdf_template": "modern",
    "primary_color": "#1D4ED8",
    "logo_scale_percent": 110,
    "default_invoice_note": "Issued by {entity_name} / {unit_name}",
    "default_invoice_payment_terms": "Payment due in 15 days.",
    "document_footer": "Questions? Contact {entity_email}.",
    "default_document_signature": "Starward Berlin Office team",
    "bank_accounts": [
      {
        "type": "iban",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bank_name": "Commerzbank AG",
        "name": "Starward Berlin Office Account",
        "is_default": true
      }
    ],
    "delivery_note_hide_prices": false,
    "credit_note_negative_values": true,
    "show_payment_amounts": true,
    "email_defaults": {
      "invoice_subject": "Invoice {document_number} from {entity_name}",
      "invoice_body": "Hello {customer_name},\n\nPlease find your invoice attached."
    },
    "translations": {
      "default_invoice_note": {
        "de-DE": "Ausgestellt von {entity_name} / {unit_name}"
      },
      "default_invoice_payment_terms": {
        "de-DE": "Zahlbar innerhalb von 15 Tagen."
      },
      "document_footer": {
        "de-DE": "Fragen? Kontaktieren Sie {entity_email}."
      },
      "default_document_signature": {
        "de-DE": "Starward Berlin Office Team"
      },
      "email_defaults": {
        "invoice_subject": {
          "de-DE": "Rechnung {document_number} von {entity_name}"
        },
        "invoice_body": {
          "de-DE": "Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."
        }
      }
    }
  },
  "numbering_index": 2,
  "logo_file_id": "file_6595a27b5d35015c3ef0c3ff",
  "signature_file_id": "file_8595a27b5d35015c3ef0c400",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-09-01T00:00:00.000Z",
  "deleted_at": null
}

Update a business unit

PATCH/business-units/{id}

Update a business unit

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

namestringoptional
addressstringoptionalnullable
address_2stringoptionalnullable
post_codestringoptionalnullable
citystringoptionalnullable
statestringoptionalnullable
countrystringoptionalnullable
country_codestringoptionalnullable
emailstringoptionalnullable
phonestringoptionalnullable
websitestringoptionalnullable
settingsobjectoptionalnullable
logo_file_idstringoptionalnullable
signature_file_idstringoptionalnullable
import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.businessUnits.update("inv_6595a27b5d35015c3ef0c3fd", {
  name: "Starward Berlin HQ"
});

console.log(response);
Example:
Response

Returns

idstring
Other parameters
entity_idstring
namestring
addressstringnullable
address_2stringnullable
post_codestringnullable
citystringnullable
statestringnullable
countrystringnullable
country_codestringnullable
emailstringnullable
phonestringnullable
websitestringnullable
settingsobject
numbering_indexinteger
logo_file_idstringnullable
signature_file_idstringnullable
is_activeboolean
deleted_atstring<date-time>nullable
created_atstring<date-time>
updated_atstring<date-time>
json
{
  "id": "unit_7595a27b5d35015c3ef0c3fe",
  "entity_id": "ent_6595a27b5d35015c3ef0c3fd",
  "name": "Starward Berlin HQ",
  "address": "Friedrichstraße 95",
  "address_2": "Floor 2",
  "post_code": "10117",
  "city": "Berlin",
  "state": "Berlin",
  "country": "Germany",
  "country_code": "DE",
  "email": "berlin@starward.example",
  "phone": "+49 30 12345678",
  "website": "https://berlin.starward.example",
  "settings": {
    "pdf_template": "minimal",
    "primary_color": "#0F172A",
    "logo_scale_percent": 110,
    "default_invoice_note": "Issued by {entity_name} / {unit_name}",
    "default_invoice_payment_terms": "Payment due in 15 days.",
    "document_footer": "Questions? Contact {entity_email}.",
    "default_document_signature": "Starward Berlin Office team",
    "bank_accounts": [
      {
        "type": "iban",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "bank_name": "Commerzbank AG",
        "name": "Starward Berlin Office Account",
        "is_default": true
      }
    ],
    "delivery_note_hide_prices": false,
    "credit_note_negative_values": true,
    "show_payment_amounts": true,
    "email_defaults": {
      "invoice_subject": "Invoice {document_number} from {entity_name}",
      "invoice_body": "Hello {customer_name},\n\nPlease find your invoice attached."
    },
    "translations": {
      "default_invoice_note": {
        "de-DE": "Ausgestellt von {entity_name} / {unit_name}"
      },
      "default_invoice_payment_terms": {
        "de-DE": "Zahlbar innerhalb von 15 Tagen."
      },
      "document_footer": {
        "de-DE": "Fragen? Kontaktieren Sie {entity_email}."
      },
      "default_document_signature": {
        "de-DE": "Starward Berlin Office Team"
      },
      "email_defaults": {
        "invoice_subject": {
          "de-DE": "Rechnung {document_number} von {entity_name}"
        },
        "invoice_body": {
          "de-DE": "Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."
        }
      }
    }
  },
  "numbering_index": 2,
  "logo_file_id": "file_6595a27b5d35015c3ef0c3ff",
  "signature_file_id": "file_8595a27b5d35015c3ef0c400",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-09-01T00:00:00.000Z",
  "deleted_at": null
}

Archive a business unit

DELETE/business-units/{id}

Archive a business unit

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

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

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

console.log('Deleted successfully');