Order Routing API

POST /v1/orders-api/router/

Aplica o motor de roteamento de pedidos sobre um VTEX OrderForm e retorna as opções de frete geradas, junto com os resultados detalhados das regras de roteamento aplicadas (auditoria por execução).

Diferente da Simulation API, que simula um carrinho a partir de itens, a Order Routing API recebe um orderForm já existente — tipicamente o retornado pela API VTEX /api/checkout/pub/orderForm — e o processa diretamente.

Headers

Request Body

{
  "orderForm": {
    "orderFormId": "abc123def456",
    "items": [
      { "id": "1234", "quantity": 1, "seller": "1" },
      { "id": "5678", "quantity": 2, "seller": "1" }
    ],
    "shippingData": {
      "address": {
        "postalCode": "22071060",
        "country": "BRA"
      }
    },
    "sellers": [{ "id": "1" }],
    "totalizers": [],
    "value": 0
  },
  "leanShipping": false
}

Response

{
  "data": {
    "shippingMethods": [
      {
        "index": 0,
        "label": "Normal",
        "shippingType": "DELIVERY",
        "merchantShippingMethodId": "Normal",
        "value": 2500,
        "deliveryTime": "5bd",
        "estimatedDeliveryDate": "2026-05-07T00:00:00+00:00",
        "selected": false,
        "hasMultiplePackages": false,
        "numberOfPackages": 1,
        "packages": [
          {
            "merchantShippingMethodId": "Normal",
            "itemIds": ["1234", "5678"],
            "shippingType": "DELIVERY",
            "label": "Normal",
            "value": 2500,
            "deliveryTime": "5bd",
            "estimatedDeliveryDate": "2026-05-07T00:00:00+00:00"
          }
        ],
        "availableDeliveryWindows": [],
        "metadata": [],
        "postalCode": "22071060",
        "source": "order_router"
      }
    ],
    "routerResult": [
      {
        "name": "shipping-cap",
        "engine": "default",
        "conditionsMet": true,
        "applied": true,
        "methodsAdded": 0,
        "methodsRemoved": 0,
        "methodsModified": 1
      }
    ],
    "experiment": {
      "routerId": "reserva-rules",
      "experimentId": "reserva-router-test-ab",
      "variantId": "variant-a",
      "cohort": "all-users"
    }
  }
}

Campos da Response

shippingMethods

Opções de frete geradas pelo motor de roteamento. Cada opção representa uma estratégia completa de fulfillment.

packages[]

Cada opção de frete é composta por um ou mais pacotes. Em opções single-package há apenas um item neste array; em multi-package, vários.

routerResult

Trace das regras executadas pelo motor de roteamento — útil para debug e auditoria. Cada item descreve uma regra avaliada, se as condições foram atendidas, se ela efetivamente alterou as opções de frete, e quantos métodos foram adicionados/removidos/modificados.

experiment

Metadados da variante A/B que efetivamente rodou neste request. Presente apenas quando o backend atribuiu o usuário a uma variante (kill switch ligado para o merchant + alguma regra do experimento aplicada). Permite ao cliente taggear eventos de analytics (ex.: Mixpanel checkout_completed) com a variante que afetou a decisão de routing.

Quando o usuário não foi atribuído a uma variante (sem experimento ativo para o merchant, ou kill switch desligado), o campo experiment é omitido da response (não vem com valores vazios).

Tipos de Frete (shippingType)

Notas

• O endpoint é público (não exige JWT), mas o header x-trinio-merchant-id é obrigatório.
• shippingMethods pode vir vazio ([]) caso nenhuma regra produza opções aplicáveis ao orderForm informado.
• routerResult é sempre retornado (mesmo que vazio) e reflete o trace da execução para a request — útil para debug, mas não obrigatório de processar no cliente.
• experiment é retornado somente quando o backend atribuiu uma variante de A/B testing. O cliente deve usar routerId/experimentId/variantId/cohort para taggear eventos de analytics e fechar o loop conversão ↔ variante.
• O orderForm enviado deve ser o objeto VTEX completo. Campos não usados pelas regras do merchant podem ser omitidos, mas items, shippingData.address.postalCode e sellers são tipicamente necessários.

Exemplo: cURL

curl -s -X POST https://prod.trinio.ai/v1/orders-api/router/ \
  -H "Content-Type: application/json" \
  -H "x-trinio-merchant-id: <YOUR_MERCHANT_ID>" \
  -d '{
    "orderForm": {
      "orderFormId": "abc123def456",
      "items": [
        {"id": "1234", "quantity": 1, "seller": "1"},
        {"id": "5678", "quantity": 2, "seller": "1"}
      ],
      "shippingData": {
        "address": {
          "postalCode": "22071060",
          "country": "BRA"
        }
      },
      "sellers": [{"id": "1"}],
      "totalizers": [],
      "value": 0
    },
    "leanShipping": false
  }' | jq .

Erros