Shipping Rules

What shipping rules do

A shipping rule tells Arcus which carrier and service to suggest when you rate-shop a package. Rules match on the order’s source channel, total weight, item count, destination, and product category. The first matching rule’s suggested service is surfaced as the Suggested badge on every rate row, and (when configured) the label is purchased automatically when you Pack with Mighty. Shipping rules are managed in Settings > Shipping & Fulfillment > Shipping Rules, or via the API at /v1/shipping-rules.

Rule conditions

Every condition is optional. When set, all conditions are combined with AND. A rule with no conditions matches every package.

Condition	Field	Behavior
Source channel	`sales_channel_id`	Matches orders from that sales channel. NULL = any channel.
Weight band	`min_weight` / `max_weight`	Inclusive bounds in pounds. Default 0 to 999999, so an unset band matches every weight.
Item-count band	`item_count_min` / `item_count_max`	Inclusive bounds on the total item quantity in the package. NULL = no item-count filter.
Destination	`destination_country` / `destination_state` / `destination_zip_prefix`	Match the ship-to country, state, or ZIP prefix.
Product category	`product_category_id`	Matches when at least one item in the package belongs to that category.

Priority and the category override

Rules are evaluated in priority order (lower number runs first). When two rules have the same priority, the older one (earliest created_at) wins. A category-scoped rule (one with product_category_id set) always wins over a non-category rule, even when the non-category rule has a higher priority. This is the “any product in this category always ships by this carrier” pattern.

The order header override

If the order itself carries an explicit shipping method (default_shipping_method), that method overrides every rule. The sales rep’s choice at order entry always wins over an automated rule.

Auto-buy and cost absorption

A rule can do more than suggest. Two per-rule behaviors:

auto_buy — when the rule matches and resolves to exactly one carrier service, Pack with Mighty purchases the label automatically. Ambiguous rules (multiple allowed services) never auto-buy.
absorb_cost — whether your business absorbs the carrier cost (true), charges it to the customer (false), or defers to the entity-wide default (null). When the cost is charged, a freight line is added to the order. When absorbed, the carrier cost posts to your Freight Out expense account and the customer is not billed.

The entity-wide defaults sit behind those two per-rule choices:

Who pays the carrier is the Shipping charge policy in Settings > Shipping & Fulfillment > Shipping: Absorb (your business pays the carrier), the default, or Charge customer (pass actual cost on). A rule’s own absorb_cost overrides it.
Whether labels are bought automatically by default is the Auto-buy by default setting in Settings > Shipping & Fulfillment > Mighty Packing.

Suggested rates in the API

The rate-shop response includes a suggestion block and tags each rate row:

{
  "suggestion": {
    "source": "rule",
    "rule_id": "9f3c...",
    "rule_name": "Phone-In / 1-3.5 lb / 1 item",
    "preferred_service_token": "usps_priority",
    "auto_buy": true,
    "absorb_cost": false
  },
  "rates": [
    {
      "service_token": "usps_priority",
      "amount": 9.45,
      "is_suggested": true,
      "suggested_priority": 1,
      "is_default": false
    },
    {
      "service_token": "usps_ground_advantage",
      "amount": 6.10,
      "is_suggested": false,
      "suggested_priority": null,
      "is_default": true
    }
  ]
}

is_suggested — the rate matches a service the rule suggested.
suggested_priority — 1..N rank within the suggestion (1 = primary).
is_default — the cheapest rate row.

source is header_override when the order’s shipping method drove the suggestion, rule when a shipping rule matched, or none when no rule matched.

Creating a rule via the API

POST /v1/shipping-rules creates one rule. name is required, and rule names are unique within your entity. A carrier-routing rule (one with no outcome) also needs at least one of shipping_tokens, flat_rate or free_shipping_threshold, or the call returns 400 with code: ambiguous_rule_outcome.

Field	What it does
`name`	The rule’s name (required)
`priority`	Lower runs first. Default 10.
`is_active`	Default `true`. An inactive rule never matches.
`location_id`	Scopes the rule to one location. `null` or omitted means the whole entity.
`sales_channel_id`, `product_category_id`	The channel and category conditions above
`min_weight`, `max_weight`	The weight band, in pounds
`item_count_min`, `item_count_max`	The item-count band
`shipping_tokens`	The carrier service tokens the rule allows. The first is the primary suggestion when `preferred_service_token` is unset.
`preferred_service_token`, `preferred_carrier`	The primary suggested service and carrier
`free_shipping_threshold`, `flat_rate`	Optional. `flat_rate` is the rate offered when no carrier rates come back and your no-rates fallback is set to use a flat rate.
`auto_buy`, `absorb_cost`	The per-rule behaviors above. `auto_buy` defaults to `false`.
`outcome`, `condition`, `actions`	Set these to create a freight rule instead of a carrier-routing rule. The presence of `outcome` marks it as a freight rule.
`external_source`, `external_id`	Migration provenance, described below

curl -X POST https://api.arcuserp.com/v1/shipping-rules \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Phone-In / 1-3.5 lb / 1 item",
    "priority": 20,
    "min_weight": 1,
    "max_weight": 3.5,
    "item_count_min": 1,
    "item_count_max": 1,
    "shipping_tokens": ["usps_priority"],
    "preferred_service_token": "usps_priority",
    "auto_buy": true
  }'

Requires the settings:write scope. Supply Idempotency-Key to make the create safely retryable.

Importing rules without duplicates

When you supply external_source (and external_id), Arcus stamps the calling API key on the rule as its import source, and a unique index on the source and ID makes a re-import idempotent: posting the same imported rule again returns 409 instead of creating a duplicate. A location_id that does not belong to your entity is refused with 400.

Get Started

Concepts

Guides

SDKs

Collections

What shipping rules do

Rule conditions

Priority and the category override

The order header override

Auto-buy and cost absorption

Suggested rates in the API

Creating a rule via the API

Importing rules without duplicates

​What shipping rules do

​Rule conditions

​Priority and the category override

​The order header override

​Auto-buy and cost absorption

​Suggested rates in the API

​Creating a rule via the API

​Importing rules without duplicates

What shipping rules do

Rule conditions

Priority and the category override

The order header override

Auto-buy and cost absorption

Suggested rates in the API

Creating a rule via the API

Importing rules without duplicates