Rate Simulation

The rate simulation endpoint lets you test your shipping configuration with a custom cart and destination. It returns the same rates your customers would see, plus detailed traces showing which rules fired and why.

Using the Test Rates panel (UI)

The quickest way to simulate rates is through the Test Rates panel in the ShipRules AI dashboard:

Click the Test Rates button in the toolbar.
Set a destination address (country, state, city, postal code).
Add cart items with prices, weights, quantities, tags, and SKUs.
Click Simulate.

The panel shows:

Rates — the shipping options that would appear at checkout.
Method evaluations — every method that was considered, whether it’s visible or hidden, and its final rate.
Rule traces — for each method, which rules were evaluated, which conditions matched, and the final action.

Using the API

POST /simulate

Request body

{
  "destination": {
    "country": "US",
    "province": "AK",
    "city": "Anchorage",
    "postalCode": "99501",
    "name": "Jane Smith",
    "address1": "123 Main St",
    "address2": "",
    "address3": "",
    "phone": "555-1234",
    "company": ""
  },
  "items": [
    {
      "name": "Widget Pro",
      "sku": "WIDGET-001",
      "quantity": 2,
      "grams": 500,
      "price": 2999,
      "vendor": "Acme Co",
      "productId": "prod_123",
      "variantId": "var_456",
      "properties": {
        "tag": "electronics,fragile"
      },
      "requiresShipping": true
    }
  ],
  "currency": "USD",
  "locale": "en"
}

Response

{
  "rates": [
    {
      "serviceName": "Standard Shipping",
      "serviceCode": "standard",
      "description": "5-7 business days",
      "totalPrice": 1499,
      "currency": "USD"
    }
  ],
  "methodEvaluations": [
    {
      "methodId": "method_abc",
      "methodName": "Standard Shipping",
      "visible": true,
      "rate": {
        "serviceName": "Standard Shipping",
        "serviceCode": "standard",
        "description": "5-7 business days",
        "totalPrice": 1499,
        "currency": "USD"
      },
      "ruleTraces": [
        {
          "ruleId": "rule_xyz",
          "action": "adjust_add",
          "matched": true,
          "conditions": [
            {
              "conditionType": "destination_state",
              "operator": "equals",
              "value": "AK,HI",
              "scope": "any_product_in_order",
              "matched": true
            }
          ]
        }
      ]
    },
    {
      "methodId": "method_def",
      "methodName": "Express Shipping",
      "visible": false,
      "rate": null,
      "ruleTraces": [
        {
          "ruleId": "rule_uvw",
          "action": "hide",
          "matched": true,
          "conditions": [
            {
              "conditionType": "destination_state",
              "operator": "equals",
              "value": "AK,HI",
              "scope": "any_product_in_order",
              "matched": true
            }
          ]
        }
      ]
    }
  ],
  "blendedRates": []
}

Understanding rule traces

Each method evaluation includes a ruleTraces array. Each trace shows:

Field	Meaning
`ruleId`	The rule that was evaluated
`action`	What the rule would do (hide, free, adjust_add, etc.)
`matched`	Whether all conditions were satisfied
`conditions`	Each condition’s type, operator, value, scope, and whether it matched
`matchedItems`	(Optional) Which specific cart items matched item-level conditions

Use traces to debug why a rate is unexpected:

Method hidden unexpectedly? Look for a hide rule with matched: true.
Rate wrong amount? Check for adjustment rules and their matched status.
Method missing entirely? It might have a Show rule where no conditions matched.