About weight fields

Shipium's APIs use multiple weight measurements to ensure accurate shipping cost calculations and carrier integration. Understanding these weight types helps you interpret API responses.

• Physical weight. The actual, physical weight of a package as measured on a scale, including all of its contents and packaging materials. This is the straightforward measurement you obtain by placing your package on a scale.
• Dimensional weight. A calculated weight that accounts for the amount of space a package occupies. Carriers use dimensional weight to ensure they are compensated for the space a package takes up on a truck or airplane, even if the package is lightweight. Dimensional weight is calculated using the formula: (Length × Width × Height) / dimensional factor. The dimensional factor is set by each carrier and can vary by service method.
• Billable weight. The weight carriers use to look up rates in their rate tables and calculate shipping costs. Billable weight is determined by first comparing physical weight and dimensional weight, taking the greater value, then rounding up to the next weight increment in the carrier's rate sheet. For example, if the greater of physical or dimensional weight is 12.5 lbs and the carrier's rate sheet increments by whole pounds, the billable weight would be 13 lbs. This ceiling value is guaranteed to be the same or higher than both physical and dimensional weights.
• Rounded weight. The physical weight of a package rounded according to carrier and Shipium's internal business rules. This weight is primarily used for calculations related to multi-parcel shipments and appears in API responses as actual_weight.

📘

API and UI Terminology Note

The API field actual_weight represents rounded weight, not the raw physical weight measurement. In the Shipium Console, this field is labeled "Rounded Weight" for clarity. Both refer to the same calculated value.

How billable weight is determined

Carriers determine billable weight through a two-step process:

1. Step 1: Compare physical and dimensional weight

   • Physical weight. The measured weight of your package
   • Dimensional weight. The calculated weight based on package dimensions
   • Take the greater of these two values.

2. Step 2: Round up to rate sheet entry

   • The greater weight is rounded up to the next increment in the carrier's rate table.
   • Most carrier rate sheets increment by whole pounds.
   • This ceiling value becomes the billable weight used to calculate your shipping cost.

Example: A package with physical weight of 12.5 lbs and dimensional weight of 10 lbs would have a billable weight of 13 lbs (assuming the rate sheet increments by whole pounds), since 12.5 lbs rounds up to the next rate tier of 13 lbs.

Example 1: Heavy, compact package

• Physical weight: 20.3 lbs
• Dimensional weight: 10 lbs
• Greater weight: 20.3 lbs (physical weight)
• Billable weight: 21 lbs (rounded up to next rate sheet entry)

Example 2: Large, lightweight package

• Physical weight: 10 lbs
• Dimensional weight: 25.4 lbs
• Greater weight: 25.4 lbs (dimensional weight)
• Billable weight: 26 lbs (rounded up to next rate sheet entry)

Example 3: Pillows

A large box of pillows might have a physical weight of only 8 lbs, but if the box dimensions are 24" × 20" × 18" and the carrier's dimensional factor is 139, the dimensional weight would be approximately 62 lbs. Since dimensional weight (62 lbs) is greater than physical weight (8 lbs), the billable weight would be 62 lbs (already a whole number).

API response examples

Single-parcel shipment

The following example is an API response for a single-parcel shipment demonstrating the weight fields.

{
  "carrierServiceMethodId": "fedex-ground",
  "physicalWeight": 12.5,
  "actualWeight": 13.0,
  "dimWeight": 15.2,
  "billableWeight": 16.0,
  "weightUnitForRate": "lb"
}

 

In this example:

• physicalWeight: 12.5 lb measured on scale
• actualWeight: 13.0 lb (physical weight rounded per carrier rules)
• dimWeight: 15.2 lb (calculated from package dimensions)
• billableWeight: 16.0 lb (dimWeight of 15.2 rounded up to next rate sheet entry)

Multi-parcel shipment

The next example is an API response for a multi-parcel shipment demonstrating the weight fields.

{
  "carrierServiceMethodId": "ups-ground",
  "physicalWeight": 24.7,
  "actualWeight": 25.0,
  "dimWeight": 18.3,
  "billableWeight": 25.0,
  "weightUnitForRate": "lb"
}

In this multi-parcel example, the actualWeight (rounded weight of 25.0 lb) is used for comparison with dimensional weight. Since 25.0 lb is greater than 18.3 lb and is already a whole number, the billable weight is 25.0 lb.

How rounded weight is calculated

Rounded weight applies rounding rules based on carrier requirements and Shipium's internal business logic. The specific rounding strategy depends on carrier configuration and shipment type. Contact Shipium support if you need details about current rounding behavior for your integration.

When each weight field is used

Physical weight

• Base measurement for all calculations
• Compared with dimensional weight to determine billable weight
• Used in carrier selection rules
• Displayed in shipment details

Dimensional weight

• Calculated for all shipments based on package dimensions
• Compared with physical weight to determine billable weight
• Critical factor for large, lightweight packages

Rounded weight (actual_weight)

• Returned in all rate calculation API responses
• Used for rating multi-parcel shipments with specific carriers
• Not used for rating single-parcel shipments (informational only)

Billable weight

• The weight tier from the carrier's rate table used for billing
• Always the greater of physical or dimensional weight, rounded up to the next rate sheet increment
• Used by carriers for final cost calculation
• Determines the actual shipping charge

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support

FAQ

Q: Why is actual_weight different from my measured weight?
A: The actual_weight field represents rounded weight, not your raw measurement. It applies rounding rules based on carrier requirements and Shipium's internal business logic, primarily for multi-parcel shipments.

Q: Which weight determines my shipping cost?
A: Billable weight determines your shipping cost. This is the greater value between physical weight and dimensional weight, rounded up to the next increment in the carrier's rate table.

Q: Why is my billable weight higher than both my physical and dimensional weights?
A: Billable weight is rounded up to the next increment in the carrier's rate table. If your physical weight is 12.5 lbs and dimensional weight is 10 lbs, the billable weight will be 13 lbs (rounded up to the next whole pound) because most carrier rate sheets increment by whole pounds. This ensures rates align with the carrier's pricing tiers.

Q: How can I reduce my billable weight?
A: If dimensional weight is driving your billable weight higher, you can reduce costs by using smaller packaging that fits your products more efficiently, avoiding oversized boxes with excess empty space, and consolidating multiple items into single shipments where appropriate. If you're close to a rate tier boundary (e.g., 12.5 lbs), even small reductions in physical weight or package dimensions can drop you to a lower pricing tier.

Q: Does rounded weight affect single-parcel shipments?
A: No. For single-parcel shipments, rounded weight is calculated and included in the API response but is not used for rating. The billable weight (greater of physical weight or dimensional weight, rounded to the rate sheet entry) determines the shipping cost.

Q: Why do carriers use dimensional weight?
A: Carriers use dimensional weight to ensure fair pricing. A large but lightweight package takes up valuable space in trucks and aircraft, reducing the number of packages that can be transported. Dimensional weight ensures carriers are compensated for the space occupied, not just the physical weight.