Skip to main content

Order Amount, Quantity, and Piece Count Examples

S
Written by Shipwell TMS Support
Updated this week

Overview

This article explains the key differences between the amount, quantity, and number_of_pieces (also called total_pieces) fields in the v3 order data model. These fields work together to provide a complete description of items in your orders, but each serves a distinct purpose.

Field Definitions

1. Amount (amount)

Type: Complex object with value and unit
​Purpose: Represents the total measurement of goods being ordered in a specific unit of measure.

Example Structure:

{
  "value": 1000.5,
  "unit": "LB" 
}

Use Cases:

  • Weight-based items (e.g., 2,000 LBS of steel)

  • Volume-based items (e.g., 500 GAL of liquid)

  • Length-based items (e.g., 1,000 FT of cable)

  • Area-based items (e.g., 5,000 SQ_FT of flooring)

  • Package-based items (e.g., 50 pallets)

Key Characteristics:

  • Represents total measurement ordered

  • Required for creating an order item

  • Unit can be weight, volume, length, packaging type, or area

2. Quantity (quantity)

Type: Integer
​Purpose: Number of handling units (packages/pallets/containers) being shipped

Use Cases:

  • Pallets, boxes, containers, or other standard shipping units

Key Characteristics:

  • Represents how many packages are being transported

  • Used for logistics planning, loading, unloading, and space requirements

3. Number of Pieces (total_pieces)

Type: Integer
​Purpose: Total count of individual pieces/units within the handling units

Use Cases:

  • Individual items within packages (e.g., 240 pieces in 20 boxes)

  • Units within pallets

  • Countable items for inventory tracking

Key Characteristics:

  • Optional field — only used when piece-level tracking is required

  • Related to piece_type (e.g., "CARTON", "UNIT", "EACH")

How These Fields Work Together

Order Item
├── amount: {value: 5000, unit: "LB"}        ← Total weight ordered
└── shipping_requirements
    ├── quantity: 10                         ← Number of pallets
    └── total_pieces: 240                    ← Individual items

Example 1: Palletized Goods

{
  "amount": {"value": 5000, "unit": "LB"},
  "shipping_requirements": {
    "quantity": 10,
    "packaging_type": "PLT",
    "total_pieces": 240,
    "piece_type": "UNIT"
  }
}

Example 2: Boxed Items

{
  "amount": {"value": 25, "unit": "PKG"},
  "shipping_requirements": {
    "quantity": 25,
    "packaging_type": "PKG",
    "total_pieces": 300,
    "piece_type": "EACH"
  }
}

Example 3: Liquid Bulk

{
  "amount": {"value": 500, "unit": "GAL"},
  "shipping_requirements": {
    "quantity": 1,
    "packaging_type": "FLOOR_LOADED",
    "total_pieces": null
  }
}

Decision Guide: When to Use Each Field

Field

Purpose

Use Cases

amount

Total quantity ordered

Billable quantity, supplier fulfillment, invoice

quantity

Number of handling units

Loading/unloading, dock scheduling, logistics

total_pieces

Count of individual items

Inventory tracking, piece-level picking, reconciliation

Common Mistakes to Avoid

  1. Confusing Amount with Quantity

    {
      "amount": {"value": 10, "unit": "LB"},
      "shipping_requirements": {"quantity": 10, "packaging_type": "PLT"}
    }

    ✅ Correct: amount represents total weight, quantity represents number of packages

  2. Omitting required fields

    {
      "description": "Widgets",
      "shipping_requirements": {"quantity": 5}
    }

    ✅ Correct: Include amount field with value and unit

Summary

  • amount = total measurement ordered

  • quantity = number of handling units

  • total_pieces = individual item count (optional)

  • total_pieces = individual item count (optional)

Did this answer your question?