#
Units

#
What are units?

Units are practically unit measures: they are your currencies or any other units of measurement used to track money, material, tickets, and anything else. Units are defined by a symbol, modes (numerical types, i.e., integers or floats), and precision (number of decimal places).

#
Enabling units in your workspace

Before you can start creating accounts and transactions with a unit, you need to create, or if they already exist, link them to your workspace. All ISO units and some crypto units are pre-created, so you only have to link them.

#
Precision

Every unit in Modernbanc can have a different number of decimal places. This is called the precision. For example, many currencies allow up to 2 decimal places. This means you can have values like 1.00 or 0.99. But for Bitcoin, you can go up to 8 decimal places, so you can have values like 0.00000001.

#
API Formatting

In Modernbanc, we want to make sure you can send and receive money amounts in the way that best fits your system. That's why we have unit_link.mode and unit_link.precision. Mode and precision allow us to understand your preferred API request and response format for amounts.

Here's how it works:

  1. For Whole Numbers: Let's say you prefer to deal with 100 instead of $1.00. You'd set your unit_link.mode to integers and precision to 2. When you send us 200, we understand it as 2.00. And we'll always send back amounts to you in this format too!
  2. For Decimal Numbers: If you like the traditional format, like $2.00, set your unit_link.mode to floats and precision to 2. Send us 2.00 and we'll understand it as just that. And remember, we'll always reply with amounts in the same format.

#
Usage: unit links

  • Navigate to the Settings tab or press G and then S.
  • Select the Units tab, or press G and then U.
  • Select the unit you want to link to your workspace, and click the Enable button on the right side of the unit.
  • Navigate to the Settings tab or press G and then S.
  • Select the Units tab, or press G and then U.
  • You can view which units are linked to your workspace at the top of the list.
  • Linked units will show information about the link, and unlinked units will have an Enable button on the right.
  • Navigate to the Settings tab or press G and then S.
  • Select the Units tab, or press G and then U.
  • Currently, you can only update if a unit link is enabled or disabled.
    • To disable a unit link, click the ... button and select Disable.
    • To enable a unit link, click the Enable button.
  • Navigate to the Settings tab or press G and then S. - Select the Units tab, or press G and then U. - To delete a unit link, click the ... button on the right of the unit, and select Disable. - Deleting a unit link will not delete the unit itself, only the link to the workspace.

#
Usage: units

#
Create unit

The create unit endpoint has an extra parameter create_link which will automatically create a unit link for you. This is useful if you want to create a unit and link it to your workspace in one request.

curl --location --request POST 'https://api.modernbanc.com/v1/units?create_link=true' \
--header 'Content-Type: application/json' \
--data-raw '{
    "identifier": "exa",
    "name" : "Example Units",
    "default_precision" : 2,
    "default_mode": "floats"
}'

Currency units

Custom units

#
Update unit

curl --location --request PUT 'https://api.modernbanc.com/v1/units/exa' \
--header 'x-workspace: mdb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "updated example unit",
    "symbol": "ex.",
    "color": "#800B19",
    "background": "#000000"
}'

#
Delete unit

In order to delete a unit, it must not be linked to any workspaces. Delete the unit link with your workspace, and then you can call this endpoint to delete the unit.

curl --location --request DELETE 'https://api.modernbanc.com/v1/units/exa' \
--header 'x-workspace: docs'