Conventions used in this cookbook

Identifiers

Field	Role
id (UUID)	Internal Ublo id — persist after create
customReference	Short Ublo reference (e.g. U000014, O000002)
externalId / foreignId	Your business key for import/export sync

In the examples, UUIDs are placeholders:

00000000-0000-4000-8000-000000000001

Replace them with the IDs returned by your mutations.

Money

In the analyzed UI captures, monetary amounts are integers in euro cents:

API value	Business reading
100000	€1,000.00
20000	€200.00
300000	€3,000.00

Always confirm the scale on your environment with a read (getUnit / tenant account) after writing.

Fragments

The admin UI often sends large fragments (UnitV2Fields, etc.). For an integration, trim field selection to the strict minimum — the schema allows this partial selection.

GraphQL mutations

Examples target RootMutationType fields from the backend schema (operation names = argument names = schema). Admin UI GraphQL documents may use a different operation name (upsert…, …NoReturn) while resolving the same field — do not rely on those frontend aliases for an API integration.

Errors

Typical example:

{
  "data": null,
  "errors": [
    {
      "message": "Validation failed",
      "extensions": { "code": "VALIDATION_ERROR" }
    }
  ]
}

Handle extensions.code in your logic (validation, permissions, not found…).

Example sources

See Source legend.