Saltar al contenido principal

Descuentos y Cupones

La API de Descuentos permite gestionar cupones promocionales (de tipo porcentaje o de monto fijo) y descuentos por volumen (descuentos por cantidad de productos comprados).

Cupones​

Los cupones se aplican al carrito o checkout para reducir el monto total a pagar.

Crear cupón​

POST /api/v1/discounts/coupons

Payload de entrada:

{
  "code": "SUMMER20",
  "type": "percentage",
  "value": 2000,
  "currency": "PEN",
  "min_order_amount": 10000,
  "max_uses": 500,
  "max_uses_per_customer": 1,
  "applicable_to": "all",
  "applicable_ids": [],
  "starts_at": "2026-06-01T00:00:00Z",
  "expires_at": "2026-08-31T23:59:59Z"
}

Nota sobre valores:

  • type: Puede ser percentage (porcentaje) o fixed_amount (monto fijo).
  • value: Si es percentage, se expresa en puntos básicos (2000 = 20.00%). Si es fixed_amount, se expresa en centavos (5000 = S/ 50.00).
  • applicable_to: Puede ser all (toda la tienda), products (productos específicos) o collections (colecciones específicas).
  • applicable_ids: Arreglo de UUIDs si applicable_to es products o collections.

Respuesta 201 Created:

{
  "id": "2e0a2d21-f046-40d3-852f-423089c73ba3",
  "code": "SUMMER20",
  "type": "percentage",
  "value": 2000,
  "currency": "PEN",
  "min_order_amount": 10000,
  "max_uses": 500,
  "max_uses_per_customer": 1,
  "applicable_to": "all",
  "applicable_ids": [],
  "starts_at": "2026-06-01T00:00:00Z",
  "expires_at": "2026-08-31T23:59:59Z",
  "is_active": true,
  "uses_count": 0,
  "created_at": "2026-06-02T20:45:00Z"
}

Listar cupones​

GET /api/v1/discounts/coupons

Retorna la lista de cupones creados para el tenant. Soporta filtros habituales de paginación.

Obtener cupón por ID o código​

  • Por ID: GET /api/v1/discounts/coupons/:id
  • Por Código: GET /api/v1/discounts/coupons/code/:code

Actualizar cupón​

PATCH /api/v1/discounts/coupons/:id

Payload de entrada:

{
  "value": 2500,
  "min_order_amount": 12000,
  "expires_at": "2026-09-15T00:00:00Z"
}

Respuesta 200 OK: Retorna el cupón actualizado.

Desactivar cupón (Soft Delete)​

DELETE /api/v1/discounts/coupons/:id

Desactiva el cupón para evitar que continúe aplicándose en nuevas compras.

Respuesta 204 No Content

Validar cupón​

Evalúa las reglas de negocio de un cupón y verifica si es aplicable para los parámetros del checkout actual.

POST /api/v1/discounts/coupons/validate

Payload de entrada:

{
  "code": "SUMMER20",
  "order_amount": 15000,
  "customer_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "product_ids": ["c0a80101-0000-0000-0000-000000000001"]
}

Respuesta 200 OK:

{
  "valid": true,
  "discount_amount": 3000,
  "reason": ""
}

Aplicar cupón​

Registra el uso del cupón tras finalizar una orden, lo que incrementa el contador de usos del cupón.

POST /api/v1/discounts/coupons/:id/apply

Payload de entrada:

{
  "customer_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "order_id": "42c3d0b2-4d2b-42fa-9d10-8b1b8b6a7a50",
  "discount_amount": 3000
}

Respuesta 200 OK:

{
  "success": true
}

Descuentos por Volumen​

Los descuentos por volumen aplican automáticamente rebajas según la cantidad de items de un mismo producto en el carrito.

Crear descuento por volumen​

POST /api/v1/discounts/volume

Payload de entrada:

{
  "product_id": "c0a80101-0000-0000-0000-000000000001",
  "min_quantity": 5,
  "type": "percentage",
  "value": 1000,
  "currency": "PEN"
}

Respuesta 201 Created:

{
  "id": "e4a2d10b-f046-40d3-852f-423089c73ba3",
  "product_id": "c0a80101-0000-0000-0000-000000000001",
  "min_quantity": 5,
  "type": "percentage",
  "value": 1000,
  "currency": "PEN"
}

Listar descuentos por volumen​

GET /api/v1/discounts/volume

Retorna la lista de descuentos por volumen configurados para el tenant.

Eliminar descuento por volumen​

DELETE /api/v1/discounts/volume/:id

Respuesta 204 No Content