Shipping rules

Shipping automation rules decide which carrier account is used to fulfill each booking. They run at booking time when a shipment is created or confirmed without an explicit carrier_account_id, walking the merchant's applicable ruleset to pick a target.

This page covers the mechanics specific to shipping rules. The shared concepts (rulesets, priority evaluation, the rule object shape) are on the Automation page.

Ruleset scoping

Shipping rulesets are scoped by (merchant, pickup country, entity_type). When a shipment arrives, the engine finds the applicable ruleset by matching:

• Merchant. The shipment's merchant.
• Pickup country. Typically the pickup country (some tenant configurations use dropoff country instead).
• Entity type. FORWARD or REVERSE.

If no ruleset matches, no rule fires and the shipment ends up unassigned (see What if no rule matches).

Rule sequence

Rules within a ruleset are evaluated in sequence, and the first rule that matches a shipment wins. The sequence matters: if two rules could both match the same shipment, the one earlier in the sequence is the one that gets applied.

The most specific rules should sit at the top of the sequence, and the most general at the bottom.

Imagine a merchant with three carriers:

• A bike courier. Fast same-day delivery, but only in London.
• A national express courier. Same-day delivery across the country.
• A default courier. Standard delivery, all routes.

To use all three well, the rules should be sequenced like this:

1. Same-day deliveries to London → bike courier
2. Same-day deliveries → national express courier
3. Any shipment → default courier

The risks of getting the sequence wrong:

• Catch-all at the top. Every shipment matches rule 3 first and goes to the default courier. The same-day carriers are never used.
• Broader rule above the more specific one. All same-day shipments (including London ones) match rule 2 first and go to the national express. The bike courier never gets used, even when it's a better fit.

The catch-all at the bottom matters. Without it, shipments that don't match any other rule won't be assigned to a carrier. Most merchants put a catch-all at the lowest priority pointing to their default carrier.

Conditions

Shipping rules match on shipment data:

• Geography. Pickup country / city / postcode, dropoff country / city / postcode, route (origin-destination pairs).
• Weight. Total parcel weight, weight bands.
• Item attributes. Count, value, restricted commodity flag, dangerous goods.
• Order attributes. Order total, currency, payment mode (COD vs prepaid).
• Configured types. Delivery type, order type.
• Custom attributes. Any attributes.* field on the shipment, against per-tenant custom-attribute keys. Useful for non-standard routing dimensions: a cold_chain: true attribute can route heat-sensitive shipments to carriers with refrigerated networks; a vip: true attribute can route flagship-tier orders to a premium carrier.

Conditions are AND-combined within a rule. For OR-logic, write multiple rules with different condition sets.

Eligibility filtering

When a rule's conditions match, its target carrier accounts go through viability checks before being selected:

• Account active. Inactive accounts are skipped.
• Merchant access. The merchant must be on the account's permitted list.
• Network profile. Both pickup and dropoff must fall inside the account's network profile.
• Capacity profile. Neither daily nor in-flight threshold may be exceeded.

If a rule's targets all fail eligibility, the engine falls through to the next rule. This makes capacity profiles useful: a primary rule routes to a primary carrier. When that carrier's capacity is exhausted, the next rule takes over, typically a secondary carrier with looser conditions.

Choosing the best

A single rule can be assigned multiple carrier accounts at once. When it is, the rule includes a setting that tells Carriyo how to pick the best account for each shipment that matches:

• Cheapest. Carriyo picks the eligible account with the lowest cost, based on each account's Costing profile. Requires the Carrier Costing feature on your subscription. Use this when several carriers are equally acceptable and you want to minimize spend.
• Fastest (coming soon). Carriyo picks the eligible account with the shortest expected transit time. Useful when speed matters more than cost.
• Round-robin. Carriyo rotates through the accounts in turn, distributing shipments evenly. Useful for balancing volume across carriers, or spreading risk across multiple carriers on the same route without preferring one.

Rule limits

A rule can have a daily limit: the maximum number of shipments it can be applied to in a day. Once the limit is reached, the rule is skipped for the rest of the day and the next matching rule is used instead.

This is useful when a carrier has a daily volume cap, or when you want to limit how many shipments go to a particular carrier (for example, while testing a new one).

The counter resets at midnight in the tenant's configured timezone.

What if no rule matches

If no rule matches (or every matching rule's accounts are ineligible), the shipment is not assigned to any carrier account. It sits in the Dashboard waiting for ops to assign one manually. Fix the underlying issue (capacity, network coverage, or a missing rule), then reprocess the shipment.

The aging report and the integration monitor show these shipments so they don't sit forever.

Editing rules

Rules are managed in the Dashboard. Changes take effect immediately for new shipments; there's no deployment step. To prepare a change without affecting live traffic, create the new rule with the active flag turned off. Turn it on (and the old one off) when you're ready to switch.

How it fits with other modules

• Automation. The parent module with shared ruleset and rule concepts.
• Carrier configuration. The carrier accounts and their capacity, network, and costing profiles that shipping rules reason over.
• Service levels. The checkout-time sister rule type.
• Booking flow. Where in the shipping pipeline the engine fires.