LogoLogo
CommunitySupport PortalYouTubeStart a free trial
  • Welcome
  • Commerce Engine
  • Orchestration Engine
  • API Documentation
  • Release Notes
  • Changelog
  • Emporix API
    • List of API Services
  • OpenAPI Generator
  • Standard Practices
    • General Info
    • Mixins
    • Query Parameter
    • Translations
    • Custom ID
    • Upsert
    • B2B Token
  • API Guides and References
    • Authorization
      • OAuth Service
        • API Reference
          • Customer Token
          • Anonymous Token
          • Service Access Token
          • Models
        • View Raw API Specification
    • Artificial Intelligence
      • AI Service
        • AI Tutorials
        • API Reference
          • Text Generation
          • AI Completions
          • Models
        • View Raw API Specification
    • Configuration
      • Configuration Service
        • Language Tutorials
        • API Reference
          • Tenant configurations
          • Client configurations
          • Global configurations
          • Models
        • View Raw API Specification
      • Country Service
        • Country Tutorial
        • API Reference
          • Countries
          • Regions
          • Models
        • View Raw API Specification
      • Currency Service
        • Currency Tutorial
        • API Reference
          • Currencies
          • Currency exchange
          • Models
        • View Raw API Specification
      • Unit Handling Service
        • Unit Handling Tutorial
        • API Reference
          • Unit management
          • Type management
          • Unit conversion
          • Models
        • View Raw API Specification
      • Site Settings Service
        • Site Settings Tutorial
        • API Reference
          • Mixins
          • Site settings
          • Models
        • View Raw API Specification
      • Indexing Service
        • Indexing Tutorial
        • API Reference
          • Configuration
          • Public Configuration
          • Reindex
          • Models
        • View Raw API Specification
    • Catalogs and Categories
      • Catalog Service
        • Catalog Tutorials
        • API Reference
          • List catalogs
          • Catalog management
          • Models
        • View Raw API Specification
      • Category Service
        • Category Tutorials
        • API Reference
          • Category Resources
          • Category Assignment Resources
          • Assignment Resources
          • Category Tree Resources
          • Models
        • View Raw API Specification
    • Products, Labels and Brands
      • Product Service
        • Product Tutorial
        • API Reference
          • Products
          • Product Templates
          • Models
        • View Raw API Specification
      • Label Service
        • Label Tutorial
        • API Reference
          • Label
          • Media
          • Models
        • View Raw API Specification
      • Brand Service
        • Brand Tutorial
        • API Reference
          • Brands
          • Media
          • Models
        • View Raw API Specification
    • Prices and Taxes
      • Price Service
        • Price Tutorials
        • API Reference
          • Price lists
          • Price matching
          • Price models
          • Prices
          • Prices assigned to price lists
          • Models
        • View Raw API Specification
      • Tax Service
        • Tax Tutorials
        • API Reference
          • Taxes
          • Tax calculation
          • Models
        • View Raw API Specification
    • Users and Permissions
      • IAM Service
        • IAM Tutorial
        • API Reference
          • Access Controls
          • Group Assignments
          • Groups
          • Permissions
          • Resources
          • Roles
          • Access Control Templates
          • Users
          • Management Dashboard Users
          • Models
        • View Raw API Specification
      • Session-context Service
        • Session-context Tutorial
        • API Reference
          • Session management
          • Session context modification
          • Own session management
          • Own session context modification
          • Models
        • View Raw API Specification
    • Companies and Customers
      • Customer Management
        • Customer Management Tutorial
        • API Reference
          • Locations
          • Contact Assignments
          • Legal Entities
          • Models
        • View Raw API Specification
      • Customer Service (Customer Managed)
        • API Reference
          • Addresses
          • Authentication and authorization
          • Account and profile
          • Double opt In
          • Credentials
          • Models
        • View Raw API Specification
      • Customer Service (Tenant Managed)
        • API Reference
          • Account and profile
          • Addresses
          • Models
        • View Raw API Specification
      • Customer Segments
        • Segments Tutorial
        • API Reference
          • Segments
          • Customers Assignments
          • Items Assignments
          • Models
        • View Raw API Specification
      • Approval Service
        • Approval Tutorials
        • API Reference
          • Approvals
          • Approval
          • Search
          • Models
        • View Raw API Specification
    • Delivery and Shipping
      • Shipping Service
        • Shipping Tutorial
        • API Reference
          • Customer Group Relations
          • Delivery Windows
          • Shipping Cost
          • Shipping Methods
          • Shipping Zones
          • Shipping Groups
          • Sites
          • Delivery Times Management
          • Delivery Times Slots Management
          • Delivery Cycles
          • Models
        • View Raw API Specification
      • Delivery Providers Service
        • API Reference
          • Delivery Orders
          • Delivery Plan
          • Models
        • View Raw API Specification
    • Rewards and Promotions
      • Coupon Service
        • Coupon Tutorial
        • API Reference
          • Coupon Management
          • Coupon Validation
          • Coupon Redemption
          • Referral Coupon Management
          • Models
        • View Raw API Specification
      • Reward-points Service
        • Reward-points Tutorial
        • API Reference
          • Redeem Options Management
          • Signed In Customer Reward Points
          • Reward Points Management
          • Models
        • View Raw API Specification
    • Quotes
      • Quote Service
        • Quote Tutorial
        • API Reference
          • Quote management
          • Quote history
          • Quote pdf
          • Quote reason
          • Models
        • View Raw API Specification
    • Checkout
      • Cart Service
        • Cart Tutorial
        • API Reference
          • Carts
          • Cart items
          • Discounts
          • Models
        • View Raw API Specification
      • Payment-gateway Service
        • Payment-gateway Tutorial
        • API Reference
          • Payment
          • Payment frontend
          • Payment mode
          • Transaction
          • Payment mode frontend
          • Models
        • View Raw API Specification
      • Checkout Service
        • Checkout Tutorial
        • API Reference
          • Checkouts
          • Models
        • View Raw API Specification
      • Fee Service
        • Fee Tutorial
        • API Reference
          • Fee management
          • Item Fee management
          • Product Fees management
          • Item Fee search
          • Models
        • View Raw API Specification
      • Shopping List
        • API Reference
          • Shopping Lists
          • Models
        • View Raw API Specification
    • Orders
      • Availability Service
        • Availability Tutorial
        • API Reference
          • Locations
          • Availabilities
          • Models
        • View Raw API Specification
      • Order Service
        • Order Tutorial
        • API Reference
          • Orders (tenant Managed)
          • Orders (customer Managed)
          • Models
        • View Raw API Specification
      • Pick-pack Service
        • API Reference
          • Orders
          • Assignees
          • Order cycles
          • Recalculations
          • Events
          • Models
        • View Raw API Specification
      • Invoice Service
        • Invoice Tutorial
        • API Reference
          • Invoice Jobs
          • Models
        • View Raw API Specification
      • Returns Service
        • Returns Tutorial
        • API Reference
          • Returns
          • Models
        • View Raw API Specification
      • SEPA Export Service
        • API Reference
          • Files
          • Jobs
          • Models
        • View Raw API Specification
    • Utilities
      • Schema Service
        • Schema Tutorial
        • API Reference
          • Schema
          • Type
          • Reference
          • Custom Schema Type
          • Custom Instance
          • Models
        • View Raw API Specification
      • Sequential-id Service
        • Sequential-id Tutorial
        • API Reference
          • Sequential IDs management
          • Models
        • View Raw API Specification
    • Media
      • Media Service
        • Media Tutorial
        • API Reference
          • Assets
          • Models
        • View Raw API Specification
    • Webhooks
      • Webhook Service
        • Webhooks Tutorial
        • API Reference
          • Config
          • Events
          • Svix Emporix Shared Account
          • Models
        • View Raw API Specification
      • Events-Availability
      • Events-Cart
      • Events-Catalog
      • Events-Category
      • Events-Client Management
      • Events-Customer
      • Events-Index
      • Events-Order
      • Events-Price
      • Events-Product
      • Events-Quote
      • Events-Product
    • Integrations
      • Identity Providers
        • Auth0
      • Workflow Automation
        • Emporix and Make
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. API Guides and References
  2. Configuration
  3. Unit Handling Service
  4. API Reference

Unit management

PreviousAPI ReferenceNextType management

Was this helpful?

LogoLogo

Resources

  • Emporix.com
  • Developer Policy
  • Terms of Use

Find us

  • LinkedIn

© 2025 Emporix. All Rights Reserved.

Manage Units

Deleting units in bulk by codes

delete

Deletes the units with the given codes. After successful deletion, units will not be visible and executable for other parts of the system after 5 minutes.

The codes are defined in the request body as an array of strings.

Example: ["g", "kg", "dag", "test"]


Required scopes

  • unithandling.unit_manage

Authorizations
Path parameters
tenantstringRequired

The tenant name.

Example: testtenant
Responses
204
The units have been successfully deleted.
400
The units cannot be deleted due to no payload.
application/json
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
application/json
500
Unexpected server error
application/json
delete
DELETE /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Retrieving unit by code

get

Retrieves the unit with the given code.

  • If the Accept-Language is set to * each internationalized field is returned as a map that contains all of translations in a format of key:value pairs, where the key is the language code and value is the translation.

  • The Accept-Language can contain the priority list of languages which should be returned. Always one language is returned as a single string field.

  • If the Accept-Language header is empty default language defined in the Configuration service is taken.

  • If the unit name matches none of the specified languages, an empty string is returned in the name field.

Please, see the examples below.

Authorizations
Path parameters
unitCodestringRequired

The code of the unit.

Example: g
tenantstringRequired

The tenant name.

Example: testtenant
Header parameters
Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Responses
200
Returns the given unit.
application/json
Responseall of
400
Example response
application/json
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
404
The unit has not been found.
application/json
500
Unexpected server error
application/json
get
GET /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "code": "kg",
  "name": "kilogram",
  "type": "mass",
  "baseUnit": true,
  "factor": 1,
  "metadata": {
    "version": 1
  }
}

Deleting a specific unit

delete

Deletes the unit with the given code. After successful deletion, unit will not be visible and executable for other parts of the system after 5 minutes.


Required scopes

  • unithandling.unit_manage

Authorizations
Path parameters
unitCodestringRequired

The code of the unit.

Example: g
tenantstringRequired

The tenant name.

Example: testtenant
Responses
204
The unit has been successfully deleted.
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
application/json
404
The unit has not been found.
application/json
500
Unexpected server error
application/json
delete
DELETE /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

  • GETFinding units by filters with sorting and paging
  • POSTAdding a new unit
  • DELETEDeleting units in bulk by codes
  • GETRetrieving unit by code
  • PUTUpdate unit
  • DELETEDeleting a specific unit

Finding units by filters with sorting and paging

get

Retrieves a list of units conforming with the given filters. Supports sorting and paging.

  • If the Accept-Language is set to * each internationalized field is returned as a map that contains all of translations in a format of key:value pairs, where the key is the language code and value is the translation.

  • The Accept-Language can contain the priority list of languages which should be returned. Always one language is returned as a single string field. Example: 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7'

  • If the Accept-Language header is empty default language defined in the Configuration service is taken.

  • If the unit name matches none of the specified languages, an empty string is returned in the name field.

Please, see the examples below.

Authorizations
Path parameters
tenantstringRequired

The tenant name.

Example: testtenant
Query parameters
paramsstringOptional

Note: params is not a name of query param. Any API model field can be taken as a filtering parameter.

Filtering can be done by each field available in API. Filtering by multiple fields is also allowed. In that case, fields are aggregated with AND logic operator. In the case of string values, the contains approach is taken (filtering by substrings). In the case of boolean and number fields, the equals approach is taken.

Filtering query params examples:

  • type=mass - all units with type that contains mass are returned. For example, in that case all mass units will be returned.
  • type=a - all units with type that contains a are returned. For example, in that case all mass and distance units are returned.
  • factor=1 - all units with factor that equals 1 are returned.
  • baseUnit=true - all units with baseUnit that equals true are returned.
  • type=mass&name=gram - all units with type that contains mass AND name that contains gram are returned. For example, in that case kilogram, gram, decagram units are returned.

Filtering by localized fields:

  • Filtering by localized fields without language key is possible only when Accept-Language header with correct language is provided or when it is not set at all (in that case default language is taken). For example, when Accept-Language' is set to 'en', the request with parameter name=meterreturns all units withnamethat containsmeterin English. For example, in that casemeter, kilometerandmillimeter` units are returned.

  • When Accept-Language header is set to * filtering by localized fields is possible only when fields contains language key. For example, when Accept-Language is set to '*', the request with parameter name.en=meter returns all units with name.en that contains meter in English. For example, in that case meter, kilometer and millimeter units are returned.

Example:
sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: name,factor:asc,metadata.createdAt:desc
pageNumbernumberOptional

The page number to be displayed.

Example: 1
pageSizenumberOptional

Number of units on a single page.

Default: 60
Header parameters
Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-CountstringOptional

Total count flag. If set to true X-Total-Count header is returned.

Example: true
Responses
200
The units were retrieved successfully.
application/json
400
Example response
application/json
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
500
Unexpected server error
application/json
get
GET /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "code": "g",
    "name": "gram",
    "type": "mass",
    "baseUnit": true,
    "factor": 1,
    "metadata": {
      "version": 2,
      "createdAt": "2021-10-25T10:59:24.385Z",
      "modifiedAt": "2021-10-25T10:59:24.385Z"
    }
  },
  {
    "code": "ug",
    "name": "microgram",
    "type": "mass",
    "symbol": "µg",
    "baseUnit": false,
    "factor": 0.000001,
    "metadata": {
      "version": 1,
      "createdAt": "2021-10-25T10:59:24.385Z",
      "modifiedAt": "2021-10-25T10:59:24.385Z"
    }
  }
]

Adding a new unit

post

Creates a new unit. After successful creation, unit will be visible and executable for other parts of the system after 5 minutes.

  • If the Content-Language is set to * the request body payload should contain localized fields not as a string, but as a map in format: key:value, where the key is the language code and value is the translation.

Please see the example (Unit with name as a map) in Request body section.


Required scopes

  • unithandling.unit_manage

Authorizations
Path parameters
tenantstringRequired

The tenant name.

Example: testtenant
Header parameters
Content-LanguagestringRequired

The Content-Language request HTTP header defines language(s) of the payload.

Example: fr
Body
codestringRequired

The unit code.

Example: g
nameone ofRequired

The name of the unit in the form of map (language, value) or string.

stringOptional
or
typestringRequired

The type of unit.

Example: mass
symbolstringOptional

The symbol of unit.

Example: °C
baseUnitbooleanRequired

The base unit flag.

Example: true
factornumberRequired

The conversion factor. The factor value must be greater than zero.

Example: 1
Responses
201
The unit has been successfully created.
application/json
400
Example response
application/json
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
application/json
409
The unit already exists.
application/json
500
Unexpected server error
application/json
post
POST /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: fr
Content-Type: application/json
Accept: */*
Content-Length: 86

{
  "code": "kg",
  "name": "kilogram",
  "type": "mass",
  "baseUnit": true,
  "symbol": "kg",
  "factor": 1
}
{
  "code": "text"
}

Update unit

put

Updates an existing unit. Optimistic locking is applied to prevent update races when unit in the payload contains the optional version field. After successful update, unit will be visible and executable for other parts of the system after 5 minutes.

  • If the Content-Language is set to * the request body payload should contain localized fields not as a string, but as a map in format: key:value, where the key is the language code and value is the translation.

Please see the example (Unit with name as a map) in Request body section.


Required scopes

  • unithandling.unit_manage

Authorizations
Path parameters
unitCodestringRequired

The code of the unit.

Example: g
tenantstringRequired

The tenant name.

Example: testtenant
Header parameters
Content-LanguagestringRequired

The Content-Language request HTTP header defines language(s) of the payload.

Example: fr
Body
all ofOptional
Responses
204
The unit has been updated successfully.
400
The unit cannot be updated due to an incorrect payload.
application/json
401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
application/json
403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.
application/json
404
The unit has not been found.
application/json
500
Unexpected server error
application/json
put
PUT /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: fr
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "code": "kg",
  "name": "kilogram",
  "type": "mass",
  "baseUnit": true,
  "factor": 1,
  "metadata": {
    "version": 1
  }
}

No content