Units (Einheiten)

API wrapper for the account's units at /units (e.g. "Stunde", "Stück", "Paletten"). Articles and document items refer to units.

Access

$billomat->units

Justpilot\Billomat\Api\UnitsApi.

Endpoints

Method	HTTP	Path
list($filters?)	GET	/units
listPage($filters?)	GET	/units
iterateAll($filters?, $pageSize?)	GET	/units (all pages)
get($id)	GET	/units/{id}
getOrFail($id)	GET	/units/{id}

The API is read-only in the SDK. Billomat supports create, update and delete, but the SDK doesn't expose them as methods. If you need them, call $billomat->getHttpClient() directly.

Methods

list(array $filters = []): list<Unit>

foreach ($billomat->units->list() as $unit) {
    printf("#%d %s\n", $unit->id, $unit->name);
}

Filter parameters:

Parameter	Description
name	Substring match on the name; case-insensitive
page, per_page	Pagination — see Pagination and filtering

listPage(array $filters = []): Page<Unit>

One page plus PageInfo (page, perPage, total) in $page->info.

iterateAll(array $filters = [], int $pageSize = 100): Generator<Unit>

Lazy iteration over all pages.

get(int $id): ?Unit

Returns null on 404.

getOrFail(int $id): Unit

Like get(), but throws NotFoundException instead of returning null.

Read model: Unit

final readonly class Unit.

Property	Billomat field	Type
id	id	int
name	name	string
created, updated	created, updated	?\DateTimeImmutable
customfield	customfield	?string — free extra field, see Custom meta attributes
extra	—	array<string,mixed>: fields the SDK doesn't map yet, raw (see Read models)

Pitfalls

• Single-item list quirk. With only one unit in the account Billomat returns an object instead of a list; UnitsApi::list() normalizes this.
• Deleting fails while in use. Billomat rejects DELETE /units/{id} as long as the unit is still assigned to articles (not relevant for the SDK right now, as there is no delete()).

End-to-end example

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Justpilot\Billomat\BillomatClient;

$billomat = BillomatClient::create(
    billomatId: 'mycompany',
    apiKey: getenv('BILLOMAT_API_KEY'),
);

// All units
foreach ($billomat->units->iterateAll() as $unit) {
    printf("[#%d] %s\n", $unit->id, $unit->name);
}

// Search by filter
$matches = $billomat->units->list(['name' => 'stunde']);
printf("%d matches for 'stunde'\n", \count($matches));