Units of Measure

Units of Measure (UOM) define how quantities are measured (kg, liters, pieces, etc.). UOM conversions allow the system to convert between units automatically.

List Units of Measure

curl -X GET "https://api.sushigo.com/api/v1/units-of-measure?is_active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

is_active

boolean

Filter by active status

is_decimal

boolean

Filter by decimal support (true = allows decimals, false = integer only)

per_page

integer

default:"15"

Items per page

Response

data

array

Show Unit of Measure Object

integer

UOM ID

code

string

Unique code (e.g., KG, L, PZA)

name

string

Full name (e.g., Kilogramo)

symbol

string

Display symbol (e.g., kg, L, pz)

precision

integer

Decimal places for quantities (0-6)

is_decimal

boolean

Allows decimal quantities

is_active

boolean

Active status

created_at

string

Created timestamp

updated_at

string

Updated timestamp

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 3,
      "code": "KG",
      "name": "Kilogramo",
      "symbol": "kg",
      "precision": 3,
      "is_decimal": true,
      "is_active": true,
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-10T08:00:00+00:00"
    },
    {
      "id": 5,
      "code": "PZA",
      "name": "Pieza",
      "symbol": "pz",
      "precision": 0,
      "is_decimal": false,
      "is_active": true,
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-10T08:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 12
  }
}

Create Unit of Measure

curl -X POST "https://api.sushigo.com/api/v1/units-of-measure" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BOT",
    "name": "Botella",
    "symbol": "bot",
    "precision": 0,
    "is_decimal": false,
    "is_active": true
  }'

Request Body

code

string

required

Unique UOM code (max 20 chars, e.g., KG, L, PZA)

name

string

required

Full name (max 100 chars, e.g., Kilogramo, Litro)

symbol

string

required

Display symbol (max 10 chars, e.g., kg, L, pz)

precision

integer

default:"2"

Decimal places (0-6). For integer-only units, use 0.

is_decimal

boolean

default:"true"

Allow decimal quantities. Set to false for countable items (pieces, bottles, etc.)

is_active

boolean

default:"true"

Active status

Response

Returns the created UOM object with status 201.

Errors

422 - Validation error (duplicate code, invalid precision)
403 - Insufficient permissions

Get Unit of Measure

curl -X GET "https://api.sushigo.com/api/v1/units-of-measure/3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

integer

required

Unit of measure ID

Response

Returns the UOM object with all fields.

Errors

404 - UOM not found

Update Unit of Measure

curl -X PUT "https://api.sushigo.com/api/v1/units-of-measure/3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "precision": 4
  }'

Path Parameters

integer

required

Unit of measure ID

Request Body

All fields are optional. Only provided fields will be updated.

code

string

UOM code (must be unique)

name

string

Full name

symbol

string

Display symbol

precision

integer

Decimal places (0-6)

is_decimal

boolean

Allow decimals

is_active

boolean

Active status

Response

Returns the updated UOM object with status 200.

Errors

404 - UOM not found
422 - Validation error
403 - Insufficient permissions

Delete Unit of Measure

curl -X DELETE "https://api.sushigo.com/api/v1/units-of-measure/15" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

integer

required

Unit of measure ID

Response

{
  "status": 200,
  "message": "Unit of measure deleted successfully"
}

Errors

404 - UOM not found
409 - Cannot delete - UOM is in use by item variants
403 - Insufficient permissions

UOMs in use by item variants cannot be deleted. The system will also soft-delete all related UOM conversions when a UOM is deleted.

List UOM Conversions

curl -X GET "https://api.sushigo.com/api/v1/uom-conversions?from_uom_id=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

from_uom_id

integer

Filter by source UOM ID

to_uom_id

integer

Filter by target UOM ID

is_active

boolean

Filter by active status

per_page

integer

default:"15"

Items per page

Response

data

array

Show UOM Conversion Object

integer

Conversion ID

from_uom_id

integer

Source UOM ID

to_uom_id

integer

Target UOM ID

factor

number

Conversion factor (1 from_uom = factor × to_uom)

tolerance

number

Acceptable variance (0-1, e.g., 0.02 = 2%)

is_active

boolean

Active status

from_uom

object

Source UOM details (id, code, name, symbol)

to_uom

object

Target UOM details (id, code, name, symbol)

created_at

string

Created timestamp

updated_at

string

Updated timestamp

Example Response

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "from_uom_id": 3,
      "to_uom_id": 2,
      "factor": 1000.0,
      "tolerance": 0.01,
      "is_active": true,
      "from_uom": {
        "id": 3,
        "code": "KG",
        "name": "Kilogramo",
        "symbol": "kg"
      },
      "to_uom": {
        "id": 2,
        "code": "GR",
        "name": "Gramo",
        "symbol": "g"
      },
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-10T08:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 8
  }
}

Reading Conversion Factors: A factor of 1000 from KG to GR means: 1 KG = 1000 GRTo convert the other direction, use the reciprocal: 1 GR = 0.001 KG

Create UOM Conversion

curl -X POST "https://api.sushigo.com/api/v1/uom-conversions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_uom_id": 3,
    "to_uom_id": 2,
    "factor": 1000,
    "tolerance": 0.01,
    "is_active": true
  }'

Request Body

from_uom_id

integer

required

Source UOM ID (must exist)

to_uom_id

integer

required

Target UOM ID (must exist, must differ from source)

factor

number

required

Conversion factor (must be > 0). Formula: to_qty = from_qty × factor

tolerance

number

default:"0"

Acceptable variance (0-1). For example, 0.02 means ±2% variance is acceptable in conversions.

is_active

boolean

default:"true"

Active status

Response

Returns the created conversion with source and target UOM details. Status 201.

Errors

422 - Validation error (invalid UOM IDs, negative factor, same from/to UOM)
403 - Insufficient permissions

Common Conversions:

KG → GR: factor = 1000 (1 kg = 1000 g)
L → ML: factor = 1000 (1 L = 1000 ml)
M → CM: factor = 100 (1 m = 100 cm)
CAJA → PZA: factor = 12 (if 1 box = 12 pieces)

Delete UOM Conversion

curl -X DELETE "https://api.sushigo.com/api/v1/uom-conversions/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

integer

required

UOM conversion ID

Response

{
  "status": 200,
  "message": "UOM conversion deleted successfully"
}

Errors

404 - Conversion not found
403 - Insufficient permissions

Understanding UOM Conversions

Conversion Direction

Conversions are directional. A conversion from KG to GR (factor 1000) allows:

Converting KG → GR (multiply by 1000)
Converting GR → KG (divide by 1000, reciprocal)

The system automatically handles reciprocal conversions. You don’t need to create both directions.

Conversion Chains

The system can chain conversions:

If you have KG → GR and GR → MG
The system can convert KG → MG by multiplying factors: 1000 × 1000 = 1,000,000

Precision and Rounding

The system respects the precision field of the target UOM
For example, if converting to a UOM with precision=2, the result is rounded to 2 decimal places
Use tolerance to define acceptable rounding variance

Use in Stock Movements

When registering stock movements, you can enter quantities in any UOM that has a conversion path to the variant’s base UOM:

Variant base UOM: KG
You enter: 500 GR
Conversion: KG → GR (factor 1000)
System converts: 500 ÷ 1000 = 0.5 KG
Stock updated: +0.5 KG

Missing Conversions: If you try to register a movement with a UOM that has no conversion path to the variant’s base UOM, the operation will fail with a 400 error: “No conversion found between [entry UOM] and [base UOM]”.Always define conversions before using alternate UOMs in stock operations.

Best Practices

Standard UOM Codes

Use standardized codes for consistency:

Weight: KG, GR, MG, TON, LB, OZ
Volume: L, ML, GAL, PT, QT
Length: M, CM, MM, KM, IN, FT
Count: PZA, CAJA, PAQ, DOC

Precision Guidelines

Weight/Volume ingredients: precision = 3 (0.001 kg = 1 gram)
Count items (bottles, pieces): precision = 0 (integer only)
Currency/prices: precision = 2 (cents)

Conversion Setup

Define conversions from smaller to larger units:

GR → KG (factor 0.001) instead of KG → GR
ML → L (factor 0.001) instead of L → ML

This makes factors more intuitive when reading the database.

Testing Conversions

After creating conversions, test them by registering a small opening balance with alternate UOMs. Verify the converted quantity matches expectations.

Authentication

Inventory

Cash Operations

Employees

Operating Units

​List Units of Measure

​Query Parameters

​Response

​Example Response

​Create Unit of Measure

​Request Body

​Response

​Errors

​Get Unit of Measure

​Path Parameters

​Response

​Errors

​Update Unit of Measure

​Path Parameters

​Request Body

​Response

​Errors

​Delete Unit of Measure

​Path Parameters

​Response

​Errors

​List UOM Conversions

​Query Parameters

​Response

​Example Response

​Create UOM Conversion

​Request Body

​Response

​Errors

​Delete UOM Conversion

​Path Parameters

​Response

​Errors

​Understanding UOM Conversions

​Conversion Direction

​Conversion Chains

​Precision and Rounding

​Use in Stock Movements

​Best Practices

Build docs developers (and LLMs) love

List Units of Measure

Query Parameters

Response

Example Response

Create Unit of Measure

Request Body

Response

Errors

Get Unit of Measure

Path Parameters

Response

Errors

Update Unit of Measure

Path Parameters

Request Body

Response

Errors

Delete Unit of Measure

Path Parameters

Response

Errors

List UOM Conversions

Query Parameters

Response

Example Response

Create UOM Conversion

Request Body

Response

Errors

Delete UOM Conversion

Path Parameters

Response

Errors

Understanding UOM Conversions

Conversion Direction

Conversion Chains

Precision and Rounding

Use in Stock Movements

Best Practices