apps-registry/workloads/docs-portal/docs/playbooks/incidente-precios-medusa.md

Incidente: precios null en detalle de producto (Medusa Store API sin region_id) (2026-08)

!!! info "Origen" Migrado desde apps-registry/docs/playbooks/incidente-medusa-precios-region-id-2026-08.md. Contenido técnico preservado sin cambios de fondo — solo formato adaptado a MkDocs Material.

Ventana del incidente	2026-08-12, resuelto el mismo día (commit 60072cf)
Servicio afectado	medusa-svc (Store API), consumido por el frontend Next.js de ARI Shopping
Impacto	En el listado de productos (/catalog) los precios se mostraban correctamente, pero en la página de detalle de producto individual varios artículos mostraban "Consultar precio" en vez del monto real

Hipótesis inicial descartada: regiones COP duplicadas

La primera hipótesis fue que existían regiones "Colombia (COP)" duplicadas en Medusa, causando ambigüedad al resolver el precio. Se descartó con evidencia directa en Postgres, consultando la tabla region incluyendo soft-deletes:

SELECT id, name, currency_code, created_at, updated_at, deleted_at FROM region ORDER BY created_at;

               id                |   name   | currency_code |         created_at         |         updated_at         | deleted_at
----------------------------------+----------+---------------+----------------------------+----------------------------+------------
 reg_01KZT86WPAH7A7ZZRDSX3350V2  | Colombia | cop           | 2026-08-12 05:48:03.151+00 | 2026-08-12 05:48:03.151+00 |
(1 row)

Una sola fila, creada una sola vez, nunca actualizada, nunca borrada. No había ni hubo nunca una región duplicada — la hipótesis de deduplicación quedó descartada con esta consulta.

Causa raíz real

El backend de Medusa no tenía ninguna región configurada. El frontend pedía precios al Store API (/store/products) usando el parámetro currency_code=cop, pero el validador StoreGetProductsParams de Medusa v2 (.strict()) no acepta ese campo — devolvía 400 Unrecognized fields: 'currency_code' en cada carga de /catalog.

Se probó también country_code, que tampoco funcionó — Medusa respondía:

Missing required pricing context to calculate prices - region_id

!!! danger "Nota de arquitectura" Medusa v2 requiere explícitamente un region_id válido para poder calcular precios (calculated_price) vía Store API; ni currency_code ni country_code son parámetros válidos para ese fin.

Fix aplicado

Commit 60072cf — "fix: usar region_id en vez de currency_code para precios de Medusa" (PR #5, mergeado en 04dc6bd):

1. Se creó la región "Colombia" (moneda COP) vía Admin API — no existía ninguna región configurada previamente.
2. Se modificó el frontend para pedir precios usando region_id explícito en vez de currency_code, vía una nueva variable de entorno MEDUSA_REGION_ID:

# workloads/ecommerce/frontend.yaml
         - name: MEDUSA_BACKEND_URL
           value: http://medusa-svc:9000
+        - name: MEDUSA_REGION_ID
+          value: reg_01KZT86WPAH7A7ZZRDSX3350V2

# workloads/ecommerce/lib/headless/providers/medusa.ts
   const params = new URLSearchParams({
     limit: String(limit),
-    currency_code: "cop",
+    // El validador de /store/products no acepta currency_code (400
+    // "Unrecognized fields"); el precio calculado solo se resuelve con
+    // region_id.
+    region_id: regionId(),

No hubo migración de precios entre regiones — no existían datos previos que migrar; la región se creó de cero como parte de este mismo fix. MEDUSA_REGION_ID no ha cambiado desde el commit original (verificado con git log -p --follow sobre frontend.yaml), y sigue apuntando a la única región que existe en la base.

Lecciones aprendidas

Verificar la causa raíz contra el estado real de la base de datos antes de asumir la primera hipótesis, aun cuando esa hipótesis coincida con la intuición inicial de quien reporta el bug ("puede que haya algo duplicado"). La consulta a region incluyendo deleted_at tomó segundos y evitó documentar una causa raíz incorrecta en este mismo playbook.

Nota de arquitectura: Medusa v2 Store API (StoreGetProductsParams) requiere region_id explícito para resolver precios calculados. currency_code y country_code no son parámetros válidos para ese fin.