POST/api/mod/productos/{espacio}/promotions

Crea una promoción

Una regla de descuento: cuándo aplica (predicado) y cuánto rebaja (metodo). Se aplica sola en cada cotización que la cumpla.

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Productos.

CAMPO	TIPO	REQUERIDO	QUÉ ES
nombre	string	SÍ	Sale como regla en cada descuento.
metodo	object	no	Cuánto descuenta: ver metodo. Por defecto, 0 %.
predicado	object	no	Cuándo aplica: ver predicado. Vacío: siempre.
codigo	string	no	Su código, como etiqueta. Para exigirlo, ponlo en el predicado.
estado	string	no	activo o inactivo. Por defecto activo.
grupo_exclusividad	string	no	Las del mismo grupo no se suman: aplica la de mayor prioridad.
prioridad	integer	no	Mayor gana. Por defecto 0.
limite_usos	integer	no	Cuántas ventas confirmadas pueden usarla. Sin él, sin límite.
starts_at · ends_at	string	no	Su vigencia, en ISO 8601.
campaign_id	string	no	Una campaña con presupuesto: agotado, la promoción deja de aplicar.

La promoción creada.

CAMPO	TIPO	QUÉ ES
id · nombre	string	El id y el nombre.
codigo	string \| null	Su código, como etiqueta.
estado	string	activo o inactivo. Solo activo descuenta.
grupo_exclusividad	string \| null	Una sola promoción por grupo en cada cotización.
prioridad	integer	Mayor gana dentro de su grupo.
limite_usos	integer \| null	Cuántas ventas pueden usarla. null: sin límite.
starts_at · ends_at	string \| null	Su vigencia, en ISO 8601.
predicado · metodo	object	Cuándo aplica y cuánto descuenta: ver metodo y predicado.
campaign_id	string \| null	Su campaña, si tiene.
created_at	number	Segundos desde 1970, con decimales.

CAMPO	TIPO	QUÉ ES
metodo	"percentage" \| "fixed"	percentage: valor es un porcentaje (10 = 10 %), redondeado a unidades. fixed: valor es el importe a descontar. Por defecto percentage.
target	"item" \| "order"	item: rebaja líneas del carrito. order: rebaja el subtotal y lo reparte entre las líneas. Por defecto order.
allocation	"each" \| "once"	Solo con item: each rebaja cada línea que encaja; once, solo la primera. Por defecto each.
valor	number \| string	El porcentaje o el importe. Por defecto 0.

CAMPO	TIPO	QUÉ ES
field · cmp · value	una condición	`field` es `subtotal`, `cantidad_total`, `variant_ids`, `codigos_promo` o `canal`. `cmp` es `eq`, `gt`, `gte`, `lt` o `lte` para cifras; `contains` para las listas (`variant_ids`, `codigos_promo`); `in` para que `canal` esté en una lista.
op · clauses	"and" \| "or", array	Une varias condiciones. Se pueden anidar.
{}	vacío	Sin condición: aplica a todos los carritos.

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Productos	módulo no habilitado para este espacio.
403	La clave es de solo lectura	Tu cuenta es de solo lectura en este espacio.
422	Falta un campo obligatorio o uno no es de su tipo (detail es una lista)	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

codigo no se exige solo: una promoción con código pero sin condición sobre codigos_promo se aplica a todos los carritos.
Para rebajar un producto concreto, usa target: "item" y la condición {"field": "variant_ids", "cmp": "contains", "value": "<variant_id>"}: el descuento cae solo en esa línea.
No se edita: para cambiarla, bórrala y créala otra vez. Más ejemplos en la guía.