Suscripciones
Lista, consulta, cancela y gestiona las suscripciones de tus links recurrentes.
Las suscripciones se crean cuando un comprador paga uno de los planes de tu link recurrente. El dinero de cada ciclo se te transfiere automáticamente (precio − comisión de Stripe − USD 1) y podés enterarte de cada cobro por el webhook subscription.payment.completed.
El objeto Subscription
{
"id": "66f1c1e2c8a4b0d1f2e3a4b7",
"stripeSubscriptionId": "sub_1P...",
"paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b6",
"paymentLinkPriceId": "66f1c1e2c8a4b0d1f2e3a4c1",
"price": {
"amountCents": 900,
"currency": "usd",
"interval": "month",
"intervalCount": 1,
"trialPeriodDays": null
},
"status": "active",
"customerEmail": "cliente@ejemplo.com",
"reference": "MEMBRESIA",
"currentPeriodStart": "2026-01-02T12:00:00.000Z",
"currentPeriodEnd": "2026-02-02T12:00:00.000Z",
"canceledAt": null,
"cancelAtPeriodEnd": false,
"trialStart": null,
"trialEnd": null,
"sandbox": false,
"createdAt": "2026-01-02T12:00:00.000Z"
}Estados posibles (status): active, trialing, past_due, canceled, unpaid, pending, incomplete.
Listar suscripciones
GET /api/v1/subscriptions
| Query param | Descripción |
|---|---|
status | Filtra por estado. |
payment_link_id | Filtra por link. |
sandbox | true/false. Sin el parámetro devuelve ambos entornos. |
limit | Tamaño de página (default 10, máx 100). |
starting_after / ending_before | Paginación por cursor (id de suscripción). |
curl "https://api.vexorpay.com/api/v1/subscriptions?status=active" \
-H "Authorization: Bearer vxp_u_tu_clave"La respuesta usa el formato de lista con data, has_more y total_count.
Ver una suscripción
GET /api/v1/subscriptions/{id}
En sandbox, mandá ?sandbox=true (si no, una suscripción de prueba no se encuentra).
curl "https://api.vexorpay.com/api/v1/subscriptions/66f1c1e2c8a4b0d1f2e3a4b7" \
-H "Authorization: Bearer vxp_u_tu_clave"Cancelar una suscripción
POST /api/v1/subscriptions/{id}/cancel
Programa la cancelación al final del período (cancel_at_period_end: true): el cliente conserva el acceso hasta que termine el ciclo pago y no se le vuelve a cobrar. Es idempotente: cancelar una suscripción ya cancelada responde 200 con su estado actual.
curl https://api.vexorpay.com/api/v1/subscriptions/66f1c1e2c8a4b0d1f2e3a4b7/cancel \
-X POST \
-H "Authorization: Bearer vxp_u_tu_clave" \
-H "Content-Type: application/json" \
-d '{}'En sandbox, el body es { "sandbox": true }.
Abrir el portal del cliente
POST /api/v1/subscriptions/{id}/portal
Devuelve { "url": "https://billing.stripe.com/..." } para que el suscriptor gestione su método de pago, vea facturas o cancele por su cuenta. Redirigí al comprador a esa URL.
curl https://api.vexorpay.com/api/v1/subscriptions/66f1c1e2c8a4b0d1f2e3a4b7/portal \
-X POST \
-H "Authorization: Bearer vxp_u_tu_clave" \
-H "Content-Type: application/json" \
-d '{}'Errores
| Error | HTTP | Causa |
|---|---|---|
unauthorized | 401 | Falta el header Authorization. |
invalid_key | 401 | La API key es inválida o fue revocada. |
validation_error | 400 | status inválido en el listado. |
invalid_request | 400 | La suscripción no tiene un customer de Stripe asociado (portal). |
subscription_not_found | 404 | No existe esa suscripción, o es de otro modo (sandbox). |
rate_limited | 429 | Superaste el límite de 100 requests por minuto. |