Shipping rules

Automate carrier and service selection with IF/THEN rules evaluated on every shipment.

Shipping rules automate decisions at shipment creation: choosing a carrier, pinning a service, auto-insuring, switching the label format, and more. They are evaluated in priority order, before quoting.

Endpoints

Method	Path	Description
`GET`	`/v1/shipping-rules`	List rules (ordered by priority)
`POST`	`/v1/shipping-rules`	Create a rule
`GET`	`/v1/shipping-rules/:id`	Get a rule
`PUT`	`/v1/shipping-rules/:id`	Update a rule
`DELETE`	`/v1/shipping-rules/:id`	Delete (soft delete)
`PATCH`	`/v1/shipping-rules/reorder`	Bulk-update priorities
`POST`	`/v1/shipping-rules/preview`	Dry run: evaluate without persisting

Body parameters (create and update)

PropType

prioritynumber

Evaluation order (1–9999). Unique per organization.

Typenumber

conditionsobject

all/any tree of { field, op, value } conditions. See the table below.

Typeobject

actionsobject[]

Actions applied when the rule fires. See the actions table.

Typeobject[]

name?string

A descriptive name for the rule.

Typestring

isActive?boolean

Inactive rules are not evaluated.

Typeboolean

Defaulttrue

curl -X POST https://api.sendit.mx/v1/shipping-rules \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DHL for heavy shipments to Jalisco",
    "priority": 10,
    "conditions": {
      "all": [
        { "field": "parcel.weight", "op": ">=", "value": 5 },
        { "field": "to.state", "op": "==", "value": "JAL" }
      ]
    },
    "actions": [{ "type": "select_carrier", "carrierCode": "DHL" }]
  }'

{
  "success": true,
  "data": {
    "id": "clxrule1",
    "name": "DHL for heavy shipments to Jalisco",
    "priority": 10,
    "isActive": true,
    "conditions": { "all": [ { "field": "parcel.weight", "op": ">=", "value": 5 }, { "field": "to.state", "op": "==", "value": "JAL" } ] },
    "actions": [{ "type": "select_carrier", "carrierCode": "DHL" }],
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

The sections below detail the conditions and actions syntax.

Write conditions

Conditions nest with all (AND) and any (OR):

{
  "all": [
    { "field": "parcel.weight", "op": ">=", "value": 5 },
    { "any": [
      { "field": "to.state", "op": "in", "value": ["CDMX", "JAL", "NLE"] },
      { "field": "to.isResidential", "op": "==", "value": false }
    ]}
  ]
}

Available fields

Field	Type	Description
`parcel.weight`	number	Weight in kg
`parcel.length` / `width` / `height`	number	Dimensions in cm
`parcel.packagingType`	string	Packaging type
`to.country`	string	Destination country (ISO)
`to.state`	string	Destination state
`to.postalCode`	string	Destination postal code
`to.isResidential`	boolean	Residential delivery
`order.totalPrice`	number	Order total (MXN)
`order.channel`	string	`SHOPIFY`, `WOOCOMMERCE`, …
`shipment.declaredValue`	number	Declared value
`shipment.isInternational`	boolean	Cross-border shipment

Operators

==, !=, >, >=, <, <=, in, not_in, contains, starts_with

Define actions

Action	Fields	Effect
`select_carrier`	`carrierCode`	Quote only this carrier
`select_service`	`carrierCode`, `serviceCode`	Pin a specific service
`exclude_carrier`	`carrierCode`	Exclude a carrier
`add_insurance`	`declaredValue`	Auto-insure
`set_label_format`	`format`	Override the label format: `PDF`, `ZPL`, or `PNG`
`add_signature_required`	—	Require a delivery signature
`tag`	`tags: string[]`	Tag the shipment

Priority and cascading

Rules are evaluated in ascending priority order. Every matching rule fires, and later rules can override earlier ones:

Priority 1: select_carrier DHL
Priority 2: select_service DHL EXPRESS   ← refines what priority 1 set

Test before you activate

preview evaluates a hypothetical shipment without writing anything:

curl -X POST https://api.sendit.mx/v1/shipping-rules/preview \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shipment": {
      "parcel": { "weight": 8, "length": 40, "width": 30, "height": 20 },
      "to": { "country": "MX", "state": "JAL", "postalCode": "44100" },
      "shipment": { "declaredValue": 5000, "isInternational": false }
    }
  }'

{
  "success": true,
  "data": {
    "finalActions": {
      "carrierCode": "DHL",
      "serviceCode": "EXPRESS"
    },
    "evaluations": [
      { "ruleId": "clxrule1", "fired": true, "actionsApplied": [{ "type": "select_carrier", "carrierCode": "DHL" }] },
      { "ruleId": "clxrule2", "fired": true, "actionsApplied": [{ "type": "select_service", "carrierCode": "DHL", "serviceCode": "EXPRESS" }] }
    ]
  }
}

evaluations[] shows the exact cascade: which rule fired, which conditions it evaluated, and which actions it applied. The same information is recorded on every real shipment for auditing.

Limits and utilities

Up to 100 active rules per organization.
Priority is unique per organization (1–9999).
For debugging, skip all rules on a request with the SendIt-Rules: skip header.