Gestionar suscripciones

Actualiza, cancela, reanuda y lista suscripciones con la API de suscripciones.

Obtener una suscripción

GET /api/v1/subscriptions/:id

Devuelve el objeto de suscripción completo. Úsalo para comprobar el estado, current_period_end, latest_payment_link y (en auto_charge) los detalles de auto_charge.

Ejemplo:

curl https://api.orcarail.com/api/v1/subscriptions/sub_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Listar suscripciones

GET /api/v1/subscriptions

Admite paginación por cursor y filtros.

Parámetros de consulta

Parámetro	Tipo	Descripción
status	string	Filtra por estado: trialing, active, past_due, canceled, paused, completed
collection_method	string	Filtra por send_payment_link o auto_charge
current_period_start	object	Filtra por periodo: gt, gte, lt, lte (marcas de tiempo ISO)
current_period_end	object	Igual que el anterior para el fin del periodo
created	object	Filtra por creación: gt, gte, lt, lte
limit	number	Tamaño de página (por defecto 10, máximo 100)
starting_after	string	Cursor: ID de suscripción a partir del cual empezar
ending_before	string	Cursor: ID de suscripción antes del cual terminar

Ejemplo:

curl "https://api.orcarail.com/api/v1/subscriptions?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Forma de la respuesta:

{
  "object": "list",
  "data": [ { ... subscription objects ... } ],
  "has_more": false
}

Actualizar una suscripción

PATCH /api/v1/subscriptions/:id

Actualización parcial. Envía solo los campos que quieras cambiar.

Campos actualizables

Parámetro	Tipo	Descripción
description	string	Descripción de la suscripción
amount	string	Nuevo importe por periodo
currency	string	Código de moneda
token_id	string	ID del token
network_id	string	ID de la red
collection_method	string	send_payment_link o auto_charge
cancel_at	string | null	Marca de tiempo ISO en la que cancelar, o null para borrarla
cancel_at_period_end	boolean	Cancelar al final del periodo actual
days_until_due	number	Días tras el fin del periodo hasta que vence
trial_end	string	Cuándo termina la prueba (ISO o "now")
metadata	object	Metadatos clave-valor
withdrawal_addresses	object	Tipo de cadena → dirección
pause_collection	object | null	{ "behavior": "void" | "keep_as_draft" } para pausar; null para reanudar

Ejemplo (cancelar al final del periodo):

curl -X PATCH https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true }'

Ejemplo (pausar el cobro):

{
  "pause_collection": { "behavior": "void" }
}

Cancelar una suscripción

DELETE /api/v1/subscriptions/:id

Cancela de inmediato o al final del periodo (si antes definiste cancel_at_period_end). El cuerpo de la petición es opcional.

Cuerpo de la cancelación (opcional)

Parámetro	Tipo	Descripción
cancellation_details	object	Comentarios opcionales
cancellation_details.comment	string	Comentario de texto libre
cancellation_details.feedback	string	Uno de: too_expensive, missing_features, switched_service, unused, other

Ejemplo:

curl -X DELETE https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_details": {
      "comment": "Switching to annual",
      "feedback": "other"
    }
  }'

Reanudar una suscripción

POST /api/v1/subscriptions/:id/resume

Reanuda una suscripción en pausa. No requiere cuerpo. Tras reanudarla, la suscripción vuelve a active y el siguiente ciclo creará un enlace de pago o ejecutará el cobro automático según la configuración.

Ejemplo:

curl -X POST https://api.orcarail.com/api/v1/subscriptions/sub_xxx/resume \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Listar los enlaces de pago de una suscripción

GET /api/v1/subscriptions/:id/payment-links

Devuelve los enlaces de pago (uno por ciclo de facturación) de esta suscripción. Admite paginación (por ejemplo limit, starting_after, ending_before). Úsalo para mostrar el historial de ciclos o el estado del enlace de cada periodo.

Ejemplo:

curl "https://api.orcarail.com/api/v1/subscriptions/sub_xxx/payment-links?limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Próximos pasos

• Crear una suscripción: crea con periodo de prueba o cobro automático
• Webhooks de suscripción: gestiona los eventos de suscripción
• Periodos de prueba: comportamiento del periodo de prueba