Membresías

Las membresías representan los diferentes niveles de acceso y beneficios que un club puede ofrecer a sus miembros. Cada membresía está vinculada a una lista de precios específica en Medusa, permitiendo precios diferenciados por nivel.

Las membresías en Cannahub se implementan sobre los Customer Groups de Medusa, con metadata adicional para beneficios, límites y configuración visual.

El modelo de Membresía

Propiedades

  • Name
    id
    Type
    string
    Description

    Identificador único (customer group ID de Medusa).

  • Name
    name
    Type
    string
    Description

    Nombre de la membresía.

  • Name
    description
    Type
    string
    Description

    Descripción de la membresía y sus beneficios.

  • Name
    price
    Type
    number
    Description

    Precio mensual/anual de la membresía.

  • Name
    currency
    Type
    string
    Description

    Moneda del precio (ARS, USD).

  • Name
    benefits
    Type
    array
    Description

    Lista de beneficios incluidos.

  • Name
    limits
    Type
    object
    Description

    Límites de compra y acceso.

    • Name
      monthlyPurchase
      Type
      number
      Description

      Límite de compra mensual en gramos.

    • Name
      productAccess
      Type
      array
      Description

      IDs de categorías accesibles.

  • Name
    priceListId
    Type
    string
    Description

    ID de la lista de precios asociada.

  • Name
    isActive
    Type
    boolean
    Description

    Si la membresía está activa para nuevas suscripciones.

  • Name
    sortOrder
    Type
    number
    Description

    Orden de visualización.

  • Name
    color
    Type
    string
    Description

    Color representativo en hex.

Ejemplo de membresía

{
  "id": "cgrp_premium_01",
  "name": "Premium",
  "description": "Membresía premium con acceso completo al catálogo y precios exclusivos.",
  "price": 15000,
  "currency": "ARS",
  "benefits": [
    "Acceso completo al catálogo",
    "Precios exclusivos (5-10% descuento)",
    "Prioridad en nuevos lanzamientos",
    "Envío gratis en pedidos +$30.000",
    "Acceso a eventos exclusivos",
    "Atención prioritaria"
  ],
  "limits": {
    "monthlyPurchase": 60,
    "productAccess": ["flores", "extracciones", "edibles"]
  },
  "priceListId": "plist_premium",
  "isActive": true,
  "sortOrder": 2,
  "color": "#8B5CF6"
}

Tipos de Membresía Comunes

NivelPrecioDescuentoLímite MensualCaracterísticas
Básica$8.0000%30gAcceso al catálogo básico
Premium$15.0005-10%60gCatálogo completo + eventos
VIP$25.00010-15%100gTodo + atención prioritaria
GET/api/memberships

Listar membresías

Este endpoint retorna todas las membresías disponibles para el club actual.

Parámetros Opcionales

  • Name
    active
    Type
    boolean
    Description

    Filtrar solo membresías activas.

  • Name
    limit
    Type
    integer
    Description

    Límite de resultados (default: 10).

Request

GET
/api/memberships
curl -G https://api.cannahub.tech/api/memberships \
  -H "Authorization: Bearer {token}" \
  -d active=true

Response

{
  "memberships": [
    {
      "id": "cgrp_basica_01",
      "name": "Básica",
      "price": 8000,
      "currency": "ARS",
      "benefits": ["Acceso al catálogo"],
      "isActive": true,
      "sortOrder": 1
    },
    {
      "id": "cgrp_premium_01",
      "name": "Premium",
      "price": 15000,
      "currency": "ARS",
      "benefits": ["Acceso completo", "Descuentos"],
      "isActive": true,
      "sortOrder": 2
    }
  ],
  "count": 2
}
GET/api/memberships/:id

Obtener membresía

Retorna los detalles completos de una membresía específica.

Request

GET
/api/memberships/:id
curl https://api.cannahub.tech/api/memberships/cgrp_premium_01 \
  -H "Authorization: Bearer {token}"

Response

{
  "membership": {
    "id": "cgrp_premium_01",
    "name": "Premium",
    "description": "Membresía premium...",
    "price": 15000,
    "currency": "ARS",
    "benefits": [...],
    "limits": {
      "monthlyPurchase": 60
    },
    "priceListId": "plist_premium",
    "isActive": true
  }
}
POST/api/memberships

Crear membresía

Crea una nueva membresía/tipo de suscripción para el club.

Campos Requeridos

  • Name
    name
    Type
    string
    Description

    Nombre de la membresía.

  • Name
    price
    Type
    number
    Description

    Precio de la membresía.

  • Name
    benefits
    Type
    array
    Description

    Lista de beneficios (mínimo 1).

Request

POST
/api/memberships
curl -X POST https://yourapp.com/api/memberships \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold",
    "metadata": {
      "description": "Membresía Gold con beneficios exclusivos",
      "price": 20000,
      "currency": "ARS",
      "benefits": [
        "Acceso completo",
        "10% descuento",
        "Envío gratis"
      ],
      "limits": {
        "monthlyPurchase": 80
      },
      "priceListId": "plist_gold",
      "isActive": true,
      "sortOrder": 3,
      "color": "#F59E0B"
    }
  }'

Response

{
  "customer_group": {
    "id": "cgrp_gold_01",
    "name": "Gold",
    "metadata": {
      "description": "Membresía Gold...",
      "price": 20000,
      "benefits": [...]
    },
    "created_at": "2024-03-20T15:00:00Z"
  }
}
PUT/api/memberships/:id

Actualizar membresía

Planned - This BFF route is not yet implemented. Currently use the Medusa Reference below.

Actualiza los detalles de una membresía existente.

Request

PUT
/api/memberships/:id
curl -X PUT https://yourapp.com/api/memberships/cgrp_gold_01 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "price": 22000,
      "benefits": [
        "Acceso completo",
        "12% descuento",
        "Envío gratis",
        "Acceso anticipado"
      ]
    }
  }'

Response

{
  "customer_group": {
    "id": "cgrp_gold_01",
    "name": "Gold",
    "metadata": {
      "price": 22000,
      "benefits": [...]
    }
  }
}
POST/api/memberships/:id/members

Asignar membresía a miembro

Planned - This BFF route is not yet implemented. Currently use the Medusa Reference below.

Asigna una membresía a uno o más miembros.

Al asignar una membresía, el miembro automáticamente obtiene acceso a los precios de la lista asociada.

Request

POST
/api/memberships/:id/members
curl -X POST https://yourapp.com/api/memberships/cgrp_premium_01/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ids": [
      "cus_01HQ8ABC456",
      "cus_01HQ8DEF789"
    ]
  }'

Response

{
  "customer_group": {
    "id": "cgrp_premium_01",
    "name": "Premium",
    "customers": [
      { "id": "cus_01HQ8ABC456" },
      { "id": "cus_01HQ8DEF789" }
    ]
  }
}
DELETE/api/memberships/:id/members

Remover membresía de miembro

Planned - This BFF route is not yet implemented. Currently use the Medusa Reference below.

Remueve la membresía de uno o más miembros.

Request

DELETE
/api/memberships/:id/members
curl -X DELETE https://yourapp.com/api/memberships/cgrp_premium_01/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ids": ["cus_01HQ8ABC456"]
  }'

Response

{
  "customer_group": {
    "id": "cgrp_premium_01",
    "name": "Premium"
  }
}

Membresía del Usuario

La membresía actual de un usuario se almacena en su metadata y se incluye en el perfil.

  • Name
    membership.id
    Type
    string
    Description

    ID de la membresía asignada.

  • Name
    membership.name
    Type
    string
    Description

    Nombre de la membresía.

  • Name
    membership.status
    Type
    enum
    Description

    Estado: PAID, PENDING, EXPIRED.

  • Name
    membership.dueDate
    Type
    string
    Description

    Fecha de próximo pago.

  • Name
    membership.expirationDate
    Type
    string
    Description

    Fecha de vencimiento.

  • Name
    membership.price
    Type
    number
    Description

    Precio pagado.

  • Name
    membership.paymentMethod
    Type
    string
    Description

    Método de pago utilizado.

Membresía en perfil de usuario

{
  "id": "cus_01HQ8ABC456",
  "email": "maria@email.com",
  "firstName": "María",
  "membership": {
    "id": "cgrp_premium_01",
    "name": "Premium",
    "status": "PAID",
    "dueDate": "2024-04-20",
    "expirationDate": "2025-03-20",
    "price": 15000,
    "paymentMethod": "MercadoPago"
  }
}

Integración con Listas de Precios

Cada membresía está vinculada a una lista de precios en Medusa que define los precios especiales para ese nivel.

Flujo de Precios

  1. Miembro sin membresía -> Precios base
  2. Miembro con Básica -> Lista "Básica" (sin descuento)
  3. Miembro con Premium -> Lista "Premium" (5-10% descuento)
  4. Miembro con VIP -> Lista "VIP" (10-15% descuento)

Resolución de precios

function getVariantPrice(variant, membership) {
  // Buscar precio en lista de la membresía
  const membershipPrice = variant.prices.find(
    p => p.price_list_id === membership?.priceListId
  )

  if (membershipPrice) {
    return {
      price: membershipPrice.amount,
      discountPrice: membershipPrice.amount,
      discountPercentage: calculateDiscount(
        variant.prices[0].amount,
        membershipPrice.amount
      )
    }
  }

  // Fallback a precio base
  return {
    price: variant.prices[0].amount,
    discountPrice: null,
    discountPercentage: 0
  }
}

Próximos Pasos

API de MiembrosGuía de Membresías (Miembros)API de Productos