read.internal.shipping_simulation

Simulate shipping for a destination postal code and a basket (SKUs and/or explicit boxes): the taxed weight per method, the eligible options ordered by effective price (with the full price beside the free one), and the methods that are OUT with a structured reason — over_weight_limit (carrying the divisor), over_dimension_limit, no_zone_for_postal_code, no_bracket_for_weight, no_rates_for_zone, method_inactive, pickup_method_not_simulated. A sku_id this tenant does not have REFUSES the whole simulation: unknown_sku_ids names them and every other field comes back empty (no zone, no option, zero weight) — read it first, because an empty option list is otherwise indistinguishable from ‘we do not deliver there’. A SKU that exists and weighs 0 g is quoted normally. Internal face only: it reads the store’s operational configuration, so it answers to an authenticated operator and never anonymously.

• Surface: GET /v1/read/internal/shipping_simulation · MCP tool read.internal.shipping_simulation
• Auth: ★ Internal read (operator) — a tenant credential is REQUIRED; requires the logistics.read scope. The tenant is resolved from the CALLER’s identity, never from store. Personal fields come back MASKED for an actor without pii.read (the shape is unchanged).

Params (JSON Schema)

{
  "properties": {
    "items": {
      "items": {
        "properties": {
          "height_cm": {
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "length_cm": {
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "qty": {
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "type": "integer"
          },
          "sku_id": {
            "minLength": 1,
            "type": "string"
          },
          "weight_grams": {
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          },
          "width_cm": {
            "maximum": 9007199254740991,
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "maxItems": 50,
      "minItems": 1,
      "type": "array"
    },
    "postal_code": {
      "minLength": 1,
      "type": "string"
    },
    "subtotal": {
      "maximum": 9007199254740991,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "postal_code"
  ],
  "type": "object"
}

Result (200)

Open (unknown) — this capability does not declare an output schema.

Errors

validation_failed (400) · not_found (404) · unauthorized (401) · forbidden (403)