Grupos (Products)

¿Qué es un grupo?

Los grupos son el paso inicial y opcional para organizar tus suscripciones: te permiten agrupar planes relacionados y darles orden. Un grupo puede contener varios planes (precios).

Son ideales cuando manejas varios negocios o productos distintos: creas un grupo por cada uno y asocias sus planes al grupo correspondiente.

{info} Nombre alternativo (estilo Stripe). Cada ruta de esta página existe también bajo product, con el mismo comportamiento y la misma respuesta. Usa el que prefieras:

Nombre original Alias
GET /api/v1/subscriptions/group GET /api/v1/subscriptions/product
POST /api/v1/subscriptions/group POST /api/v1/subscriptions/product
PUT /api/v1/subscriptions/group/{id} PUT /api/v1/subscriptions/product/{id}
DELETE /api/v1/subscriptions/group/{id} DELETE /api/v1/subscriptions/product/{id}

Listar grupos

Descripción: Devuelve todos tus grupos.

GET /api/v1/subscriptions/group

{warning} A diferencia de casi todos los listados de la API, este no está paginado y no viene envuelto en data: la respuesta es directamente el arreglo de grupos, en snake_case. Tampoco separa por ambiente: verás los grupos de prueba y los de producción juntos.

curl -X GET \
'/api/v1/subscriptions/group' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

{success} Respuesta satisfactoria code: 200

[
{
"id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
"name": "Streaming",
"description": "Planes de streaming",
"active": true,
"user_id": 42,
"office_id": 1,
"commerce_id": 315,
"created_at": "2026-07-31 10:15:00"
}
]

Es el mismo alias en el listado: GET /api/v1/subscriptions/product devuelve exactamente esto.

Crear grupo

Descripción: Crea un grupo con nombre y sucursal. Opcionalmente puedes darle una description.

POST /api/v1/subscriptions/group

Nombre del campo Descripción Reglas
name Nombre del grupo. Lo verás al organizar tus planes. No puede repetirse dentro de tu comercio ['required', 'string', 'max:255', 'unique:subscription_groups,name']
description Para qué es el grupo. Solo de uso interno ['nullable', 'string', 'max:500']
office Sucursal a la que pertenece el grupo. Debe ser una de tus sucursales ['required', 'exists:offices,id'] 
curl -X POST \
'/api/v1/subscriptions/group' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-type: application/json' \
-H 'Idempotency-Key: 9b1f0e34-6b2a-4a7e-9d0a-000000000001' \
-d '{
    "name": "Streaming",
    "description": "Planes de streaming",
    "office": 1
}'

{success} Respuesta satisfactoria code: 200

{
"saved": true,
"group": {
"id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
"name": "Streaming",
"description": "Planes de streaming",
"plansCount": 0,
"createdAt": "2026-07-31 10:15:00"
}
}

{danger} El nombre ya existe en tu comercio, o la sucursal no es tuya code: 422

{
"message": "El campo name ya está en uso.",
"errors": {
"name": ["El campo name ya está en uso."],
"office": ["El office seleccionado no es válido."]
}
}

{info} El objeto group de la respuesta viene en camelCase (plansCount, createdAt), mientras que el listado devuelve snake_case. No es un error: son dos serializaciones distintas del mismo recurso.

Actualizar grupo

Descripción: Cambia el nombre o la descripción del grupo. El nuevo nombre no puede repetirse dentro de tu comercio. La sucursal del grupo no se puede cambiar.

PUT /api/v1/subscriptions/group/{group-id}

Nombre del campo Descripción Reglas
name Nuevo nombre. Único dentro de tu comercio, ignorando este mismo grupo ['required', 'string', 'max:255', 'unique:subscription_groups,name']
description Nueva descripción. Envía null para borrarla ['sometimes', 'nullable', 'string', 'max:500'] 
curl -X PUT \
'/api/v1/subscriptions/group/9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-type: application/json' \
-d '{
    "name": "Streaming",
    "description": "Planes de streaming mensual"
}'

{success} Respuesta satisfactoria code: 200

{
"saved": true,
"group": {
"id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
"name": "Streaming",
"description": "Planes de streaming mensual",
"plansCount": 3,
"createdAt": "2026-07-31 10:15:00"
}
}

{danger} El grupo no es de tu comercio code: 403

Eliminar grupo

Descripción: Elimina un grupo por su id.

DELETE /api/v1/subscriptions/group/{group-id}

{warning} No podrás eliminar un grupo que tenga planes asociados. Elimina o reasigna primero sus planes.

curl -X DELETE \
'/api/v1/subscriptions/group/9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

{success} Respuesta satisfactoria code: 200

{
"deleted": true
}

{danger} El grupo todavía tiene planes code: 400

{
"deleted": false,
"message": "El grupo tiene planes asociados y no puede eliminarse."
}

Alias product

Las mismas operaciones, con el nombre de Stripe. Comportamiento, parámetros y respuestas son idénticos a los de arriba.

Crear — POST /api/v1/subscriptions/product

Actualizar — PUT /api/v1/subscriptions/product/{product-id}

Eliminar — DELETE /api/v1/subscriptions/product/{product-id}