Ir al contenido
Rechercher dans la documentation…⌘K
Dashboard
v1.0.0 (v1)
FR·EN·ES
API/Reference/SubscriptionPlans

SubscriptionPlans

Los SubscriptionPlans definen las tarifas recurrentes que usted ofrece a sus clientes. Cada plan especifica un importe, una moneda y una frecuencia de facturación. Después, un plan se asocia a una o varias Subscriptions para activar los cobros automáticos.

Casos de uso típicos: suscripción mensual a un SaaS, tarifa anual con descuento, oferta trimestral con período de prueba gratuito.

Importe inmutable tras la creación

El importe de un plan (amount) no se puede modificar tras la creación. Para cambiar la tarifa, cree un nuevo plan y migre a sus suscriptores mediante PATCH /subscriptions/{id}/. Solo el name y la description son modificables mediante PATCH.

Endpoints

MéthodeEndpointDescription
POST/subscription-plans/Crear un plan
GET/subscription-plans/Listar los planes
GET/subscription-plans/{id}/Recuperar un plan
PATCH/subscription-plans/{id}/Modificar (solo nombre y descripción)
DELETE/subscription-plans/{id}/Desactivar (imposible si hay suscriptores activos)

Esquema del objeto

ResponseObjeto SubscriptionPlan
Estructura completa devuelta por todos los endpoints de este recurso.
json
{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel",
  "description": "Accès complet à toutes les fonctionnalités Growth",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": {
    "tier": "growth"
  },
  "livemode": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Crear un SubscriptionPlan

Crea un nuevo plan de precios. El plan está disponible de inmediato para asociarlo a una Subscription.

POSTCuerpo de la solicitud
nameRequis
stringex :Plan Growth mensual

Nombre del plan. Visible para el cliente en las páginas de pago, las facturas y los correos de renovación.

Elija un nombre claro que refleje el valor ofrecido: aparece directamente en las comunicaciones enviadas a sus suscriptores.

amountRequis
integercentimesex :15000

Importe que se cobra en cada período de facturación, en céntimos. Este campo es inmutable tras la creación.

Exprese siempre en céntimos. 15 000 XAF = 15000. Para las monedas con decimales (EUR, USD), 15 EUR = 1500. Para modificar una tarifa, cree un nuevo plan y migre a sus suscriptores.

currencyRequis
stringISO 4217ex :XAF

Código ISO 4217 de la moneda del plan. Debe corresponder a una moneda activada en su App. Inmutable tras la creación.

intervalRequis
string

Unidad del período de facturación. Valores: day, week, month, year.

Combinado con interval_count, este campo define la frecuencia exacta de facturación. Ejemplos: interval: “month” + interval_count: 3 = facturación trimestral; interval: “year” + interval_count: 1 = facturación anual.

interval_countOptionnel
integerdéfaut :1

Multiplicador del intervalo. Determina la frecuencia real de facturación en combinación con interval.

En savoir plus

Ejemplos: interval: “month”, interval_count: 1 → mensual; interval: “month”, interval_count: 3 → trimestral; interval: “month”, interval_count: 6 → semestral.

trial_period_daysOptionnel
integerex :14

Duración del período de prueba gratuito en días. Durante este período, no se realiza ningún cobro. La Subscription pasa al estado trialing hasta el fin de la prueba.

En savoir plus

Este campo define el período de prueba por defecto del plan. Se puede sobrescribir por suscriptor pasando trial_period_days directamente al crear la Subscription.

descriptionOptionnel
string

Descripción del plan. Se muestra en la página de selección de plan y en los correos de bienvenida.

metadataOptionnel
object

Datos libres: identificador interno, nivel de precios, referencia de CRM, etc.

En savoir plus

Los metadatos del plan se incluyen en los webhooks subscription.created y subscription.canceled. Útil para identificar el nivel durante el aprovisionamiento automático de accesos.

Crear un plan mensual con prueba

bash
curl -X POST https://api.sangho.ga/v1/subscription-plans/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Growth Mensuel",
    "amount": 15000,
    "currency": "XAF",
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 14,
    "description": "Accès complet à toutes les fonctionnalités Growth",
    "metadata": { "tier": "growth" }
  }'
Response201 Created
El plan está activo de inmediato y puede asociarse a nuevas Subscriptions.
json
{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel",
  "description": "Accès complet à toutes les fonctionnalités Growth",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": { "tier": "growth" },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Listar los SubscriptionPlans

Devuelve todos los planes de su App, ordenados por fecha de creación descendente.

GETParámetros de consulta (query)
activeOptionnel
boolean

Filtrar por estado. true devuelve únicamente los planes activos, false los planes desactivados.

currencyOptionnel
stringISO 4217

Filtrar por moneda. Útil si ofrece planes en varias monedas.

intervalOptionnel
string

Filtrar por intervalo de facturación: day, week, month o year.

pageOptionnel
integerdéfaut :1
Número de página.
page_sizeOptionnel
integerdéfaut :20
Resultados por página. Máximo: 100.

Modificar un SubscriptionPlan

Solo el name y la description son modificables tras la creación. El amount, la currency, el interval y el interval_count son inmutables.

PATCHCuerpo de la actualización (PATCH)
nameOptionnel
string

Nuevo nombre del plan. Se refleja en los futuros correos de renovación.

descriptionOptionnel
string

Nueva descripción. Pase null para eliminarla.

metadataOptionnel
object
Combinación con los metadatos existentes.

Desactivar un SubscriptionPlan

Desactiva el plan pasando active a false. Un plan desactivado ya no se puede asociar a nuevas Subscriptions, pero las suscripciones en curso siguen funcionando con normalidad.

Imposible si hay suscriptores activos

La desactivación falla con un error 409 Conflict si el plan aún tiene Subscriptions en estado active o trialing. Migre primero a sus suscriptores a un nuevo plan antes de desactivar el anterior.

Listar los planes activos

bash
curl "https://api.sangho.ga/v1/subscription-plans/?active=true&interval=month" \
  -H "Authorization: Bearer sk_prod_xxxx"

Modificar un plan

bash
curl -X PATCH https://api.sangho.ga/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Growth Mensuel — Nouveau",
    "metadata": { "tier": "growth", "legacy": null }
  }'
Response200 OK — Plan actualizado
json
{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel — Nouveau",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "active": true,
  "metadata": { "tier": "growth" },
  "updated_at": "2026-04-01T09:00:00Z"
}

Desactivar un plan

bash
curl -X DELETE https://api.sangho.ga/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"
Response200 OK — Desactivado
El plan queda desactivado. Las Subscriptions existentes siguen funcionando hasta su cancelación.
Falla con 409 si aún hay Subscriptions activas o trialing asociadas a este plan.
json
{
  "id": "plan_xxxxxxxxxxxx",
  "active": false,
  "updated_at": "2026-04-10T12:00:00Z"
}