Rate Types Reference

Every shipping rule has a rate type. The type controls how the final rate is calculated from the cart. All amounts are in cents.

Modifiers (surcharges and discounts) can be layered on top of any rate type. They apply in order after the base rate is calculated.

Rate types

Type	Config fields	Calculation	Example
flat_rate	amount	Returns amount directly.	amount: 995 always returns $9.95.
weight_based	brackets (array of minGrams, maxGrams, amount)	Finds the bracket where cart weight falls between minGrams and maxGrams (inclusive) and returns that bracket’s amount. If weight is below the first bracket, uses the first bracket. If it exceeds all brackets, uses the last.	0-500g = $5, 501-2000g = $10, 2001g+ = $15.
per_weight	amountPerKg	amountPerKg × (totalWeight / 1000), rounded to nearest cent. Returns 0 for an empty cart.	$8/kg. A 2.5 kg order costs $20.
per_weight_tiered	firstKgAmount, additionalKgAmount	firstKgAmount for the first kg. For each additional kg above 1 kg (rounded up), adds additionalKgAmount. Returns 0 for an empty cart.	First kg $10, each extra kg $4. A 2.3 kg order = $10 + (2 × $4) = $18.
per_item_tiered	firstItemAmount, additionalItemAmount	firstItemAmount for the first item. For each item beyond the first, adds additionalItemAmount. Returns 0 for an empty cart.	First item $6, each extra item $2. A 4-item order = $6 + (3 × $2) = $12.
percentage	percent	totalCartPrice × (percent / 100), rounded to nearest cent. Returns 0 for a zero-value cart.	10% of a $50 order = $5 shipping.
free	none	Always returns 0.	Free shipping.

Modifiers

Any rate type can have an optional modifiers array. Modifiers apply in the order they are defined, each one adjusting the running total from the previous step.

Modifier type	Effect
surcharge_flat	Adds a fixed amount.
surcharge_percentage	Multiplies the current rate by 1 + (amount / 100).
discount_flat	Subtracts a fixed amount.
discount_percentage	Multiplies the current rate by 1 - (amount / 100).

Modifiers can have their own conditions. If a modifier’s conditions don’t all pass, that modifier is skipped. The final rate is clamped to a minimum of 0.

Conflict resolution

When multiple rules match the same cart and share a service code, the conflict resolution strategy on your settings determines which rate wins. The default is highest. Other options are lowest, first_match and sum.