Units Type API

Create, read, update, and delete units type records using the NetSuite REST API. Units types define units of measurement for items (ea, box, case, etc.).

---

Endpoints

Method	Endpoint	Description
GET	/record/v1/unitsType	List all units types
GET	/record/v1/unitsType/{id}	Get specific units type
POST	/record/v1/unitsType	Create new units type
PATCH	/record/v1/unitsType/{id}	Update existing units type
DELETE	/record/v1/unitsType/{id}	Delete units type

Base URL

https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/unitsType

---

Key Fields

Basic Information

Field	Type	Description	Required
id	string	Internal ID (read-only)	-
name	string	Units type name	Yes
isInactive	boolean	Inactive flag	No

Base Unit Definition

Field	Type	Description	Required
pluralName	string	Plural form of name	No
abbreviation	string	Unit abbreviation	No
baseUnit	object	Base unit configuration	No

Unit of Measure Configuration

Field	Type	Description	Required
uom	collection	Units of measure	No

---

Example: Create Units Type

POST /record/v1/unitsType
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "name": "Case",
  "pluralName": "Cases",
  "abbreviation": "cs",
  "isInactive": false,
  "baseUnit": {
    "name": "Each",
    "pluralName": "Each",
    "abbreviation": "ea",
    "conversionRate": 1.0
  },
  "uom": {
    "items": [
      {
        "unitName": "Case",
        "pluralName": "Cases",
        "abbreviation": "cs",
        "conversionRate": 12.0,
        "baseUnit": false
      }
    ]
  }
}

Response

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/unitsType/5"
    }
  ],
  "id": "5",
  "name": "Case",
  "pluralName": "Cases",
  "abbreviation": "cs",
  "isInactive": false,
  "baseUnit": {
    "name": "Each",
    "pluralName": "Each",
    "abbreviation": "ea",
    "conversionRate": 1.0
  },
  "uom": {
    "items": [
      {
        "unitName": "Case",
        "pluralName": "Cases",
        "abbreviation": "cs",
        "conversionRate": 12.0,
        "baseUnit": false
      }
    ]
  }
}

---

Example: Create Weight Units Type

POST /record/v1/unitsType
Content-Type: application/json

{
  "name": "Weight",
  "pluralName": "Weight",
  "isInactive": false,
  "baseUnit": {
    "name": "Pound",
    "pluralName": "Pounds",
    "abbreviation": "lb",
    "conversionRate": 1.0
  },
  "uom": {
    "items": [
      {
        "unitName": "Ounce",
        "pluralName": "Ounces",
        "abbreviation": "oz",
        "conversionRate": 0.0625,
        "baseUnit": false
      },
      {
        "unitName": "Pound",
        "pluralName": "Pounds",
        "abbreviation": "lb",
        "conversionRate": 1.0,
        "baseUnit": true
      },
      {
        "unitName": "Ton",
        "pluralName": "Tons",
        "abbreviation": "ton",
        "conversionRate": 2000.0,
        "baseUnit": false
      }
    ]
  }
}

---

Example: Create Volume Units Type

POST /record/v1/unitsType
Content-Type: application/json

{
  "name": "Volume",
  "pluralName": "Volume",
  "isInactive": false,
  "baseUnit": {
    "name": "Liter",
    "pluralName": "Liters",
    "abbreviation": "L",
    "conversionRate": 1.0
  },
  "uom": {
    "items": [
      {
        "unitName": "Milliliter",
        "pluralName": "Milliliters",
        "abbreviation": "mL",
        "conversionRate": 0.001,
        "baseUnit": false
      },
      {
        "unitName": "Liter",
        "pluralName": "Liters",
        "abbreviation": "L",
        "conversionRate": 1.0,
        "baseUnit": true
      },
      {
        "unitName": "Gallon",
        "pluralName": "Gallons",
        "abbreviation": "gal",
        "conversionRate": 3.785,
        "baseUnit": false
      }
    ]
  }
}

---

Example: Update Units Type

PATCH /record/v1/unitsType/5
Content-Type: application/json

{
  "uom": {
    "items": [
      {
        "unitName": "Case",
        "pluralName": "Cases",
        "abbreviation": "cs",
        "conversionRate": 24.0,
        "baseUnit": false
      }
    ]
  }
}

Partial Updates

With PATCH, only include fields you want to change. All other fields remain unchanged.

---

Query Filters

Find Units Types by Name

GET /record/v1/unitsType?q=name LIKE 'Case%'

Find Active Units Types

GET /record/v1/unitsType?q=isInactive=false

Find Units Types by Abbreviation

GET /record/v1/unitsType?q=abbreviation='cs'

---

Common Use Cases

1. Create Packaging Units Type

await createUnitsType({
  name: "Box",
  pluralName: "Boxes",
  abbreviation: "bx",
  baseUnit: {
    name: "Each",
    pluralName: "Each",
    abbreviation: "ea",
    conversionRate: 1.0
  },
  uom: {
    items: [
      {
        unitName: "Box",
        pluralName: "Boxes",
        abbreviation: "bx",
        conversionRate: 6.0,
        baseUnit: false
      },
      {
        unitName: "Case",
        pluralName: "Cases",
        abbreviation: "cs",
        conversionRate: 24.0,
        baseUnit: false
      }
    ]
  }
});

2. Create Length Units Type

await createUnitsType({
  name: "Length",
  pluralName: "Length",
  baseUnit: {
    name: "Meter",
    pluralName: "Meters",
    abbreviation: "m",
    conversionRate: 1.0
  },
  uom: {
    items: [
      {
        unitName: "Centimeter",
        pluralName: "Centimeters",
        abbreviation: "cm",
        conversionRate: 0.01,
        baseUnit: false
      },
      {
        unitName: "Meter",
        pluralName: "Meters",
        abbreviation: "m",
        conversionRate: 1.0,
        baseUnit: true
      },
      {
        unitName: "Kilometer",
        pluralName: "Kilometers",
        abbreviation: "km",
        conversionRate: 1000.0,
        baseUnit: false
      }
    ]
  }
});

3. Update Conversion Rate

await patchUnitsType(unitsTypeId, {
  uom: {
    items: [
      {
        unitName: "Case",
        conversionRate: 36.0  // Changed from 24 to 36
      }
    ]
  }
});

4. Deactivate Obsolete Units Type

await patchUnitsType(oldUnitsTypeId, {
  isInactive: true
});

---

Important Notes

Required Fields

• name - Units type name is required
• All other fields are optional but recommended for proper functionality

Base Unit Concept

• The base unit has a conversion rate of 1.0
• All other units are defined relative to the base unit
• Example: If "Each" is base (1.0), then "Case of 12" would be 12.0

Conversion Rates

• Conversion rate indicates how many base units equal one of this unit
• Example: 1 Case = 12 Each, so Case conversion rate = 12.0
• Example: 1 Ounce = 0.0625 Pounds, so Ounce conversion rate = 0.0625

Unit of Measure (UOM) Collection

• items array contains all units in this units type
• Each unit needs: unitName, pluralName, abbreviation, conversionRate, baseUnit flag
• Exactly one unit must have baseUnit: true

Common Units Types

Count-Based

// Each, Box, Case, Pallet
{
  baseUnit: { name: "Each", conversionRate: 1.0 },
  uom: [
    { unitName: "Each", conversionRate: 1.0 },
    { unitName: "Box", conversionRate: 6.0 },
    { unitName: "Case", conversionRate: 24.0 }
  ]
}

Weight

// Ounce, Pound, Kilogram
{
  baseUnit: { name: "Pound", conversionRate: 1.0 },
  uom: [
    { unitName: "Ounce", conversionRate: 0.0625 },
    { unitName: "Pound", conversionRate: 1.0 },
    { unitName: "Kilogram", conversionRate: 2.205 }
  ]
}

Volume

// Milliliter, Liter, Gallon
{
  baseUnit: { name: "Liter", conversionRate: 1.0 },
  uom: [
    { unitName: "Milliliter", conversionRate: 0.001 },
    { unitName: "Liter", conversionRate: 1.0 },
    { unitName: "Gallon", conversionRate: 3.785 }
  ]
}

Length

// Inch, Foot, Meter
{
  baseUnit: { name: "Meter", conversionRate: 1.0 },
  uom: [
    { unitName: "Inch", conversionRate: 0.0254 },
    { unitName: "Foot", conversionRate: 0.3048 },
    { unitName: "Meter", conversionRate: 1.0 }
  ]
}

Item Integration

• Units types are assigned to items to define how they are sold and purchased
• Items can have different units for purchase, stock, and sale
• Example: Purchase in Cases, stock in Each, sell in Boxes

Inventory Impact

• Conversion rates affect inventory counts
• System automatically converts between units
• Example: Receive 2 Cases = 24 Each in inventory (if Case = 12 Each)

Pricing Considerations

• Different units can have different prices
• Example: Price per Each vs. Price per Case
• System calculates based on conversion rates

Best Practices

• Use standard abbreviations (ea, cs, bx, lb, kg, etc.)
• Keep conversion rates accurate and up-to-date
• Test conversions with sample transactions
• Document custom units types for future reference
• Use consistent naming across similar units types

Limitations

• Cannot delete units types assigned to items
• Changing conversion rates affects historical data interpretation
• Consider creating new units types instead of modifying active ones

Use Case Examples

Manufacturing: Track raw materials in kilograms, produce in units, sell in cases

Distribution: Purchase in pallets, stock in cases, sell in boxes

Retail: Purchase in cases, stock in each, sell in each

Food & Beverage: Track in liters, sell in bottles or gallons

---

See Also

• Inventory Item - Assign units types to items
• Purchase Order - Use units in purchasing
• Sales Order - Use units in sales
• Inventory Adjustment - Adjust inventory with units
• Item Receipt - Receive inventory with units