Ir al contenido

Crear suscripción

KUTI le cobra a tu cliente cada periodo sobre su Yape afiliado. Máximo S/ 2,500 por periodo.

POSThttps://api.kuti.pe/v1/subscriptions
Monto fijo: al crearla se cobra el primer periodo. Si tu cliente ya tiene su medio de pago guardado queda ACTIVE; si no, nace INCOMPLETE y latest_cycle.checkout_url trae el enlace para que lo guarde y pague.

Parámetros del body

Campo
Descripción
customer
objectrequerido
El cliente: { "id": "cus_…" } o sus datos (se reutiliza o se crea).Ej: { "id": "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3" }
description
stringrequerido
Lo que ve tu cliente en cada cobro.Ej: Plan Pro
frequency
stringrequerido
DAILY, WEEKLY, MONTHLY o YEARLY.Ej: MONTHLY
billing_mode
stringopcional
fixed (por defecto) = mismo monto cada periodo. variable = tú envías el monto de cada periodo; no lleva amount ni items y al crearla no se cobra nada.
amount
stringopcional
Total por periodo, como string decimal (máximo 2500.00). Si envías items, el total es su suma.Ej: 99.00
items
arrayopcional
Líneas del cobro, en vez de amount.
description
stringopcional
Nombre de la línea.Ej: Plan Pro
unit_amount
stringrequerido
Precio unitario.Ej: 79.00
quantity
integeropcional
Por defecto 1.
interval
integeropcional
Cada cuántos frequency. Por defecto 1 (2 + MONTHLY = cada dos meses).
start_date
stringopcional
YYYY-MM-DD. Por defecto, hoy. Una fecha futura solo se acepta si tu cliente ya tiene su Yape afiliado.Ej: 2026-10-05
day_of_month
integeropcional
Solo MONTHLY. Por defecto, el día de start_date.
last_day_of_month
booleanopcional
Solo MONTHLY: cobrar el último día de cada mes.
day_of_week
integeropcional
Solo WEEKLY. 1 = lunes. Por defecto, el día de start_date.
end_date
stringopcional
YYYY-MM-DD. Sin fecha = hasta que la canceles.
charge_time
stringopcional
Hora de cobro, hora de Perú (HH:mm). No puede caer entre la 01:00 y las 03:00.Ej: 09:00
retry_policy
objectopcional
Qué hacer cuando un débito falla. Por defecto [1, 3, 5] y past_due.
interval_days
arrayopcional
Días entre intentos. [] = no reintentar. Máximo 5 reintentos y 30 días.Ej: [1, 3, 5]
on_exhausted
stringopcional
past_due o cancel.
send_via
arrayopcional
Por dónde le enviamos el enlace si tiene que afiliar: EMAIL, WHATSAPP. Sin enviar = correo; [] = lo envías tú.
external_reference
stringopcional
Tu propio id.Ej: cliente-4821
metadata
objectopcional
Pares string→string libres.

Language

Credentials

Header

Authorization

Secret key de developer · ejemplos con SDK oficial

API Request
$ npm install @kuti-pe/node
import { KutiClient } from "@kuti-pe/node";

const kuti = new KutiClient({ secretKey: process.env.KUTI_SECRET_KEY! });

const result = await kuti.subscriptions.create({
  customer: { id: "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3" },
  description: "Plan Pro",
  amount: "99.00",
  frequency: "MONTHLY",
  chargeTime: "09:00",
});
console.log(result.status);
SDK oficial · guía en /sdks
Response

Elige un ejemplo de respuesta:

application/json
201Created
{
  "success": true,
  "message": "Subscription created and active",
  "data": {
    "id": "sub_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "merchant_id": "mer_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "livemode": false,
    "customer": {
      "id": "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
      "name": "María López",
      "email": "maria@example.pe",
      "phone": "+51987654567"
    },
    "description": "Plan Pro",
    "billing_mode": "fixed",
    "amount": {
      "amount": "99.00",
      "currency": "PEN"
    },
    "setup_url": null,
    "items": [
      {
        "description": "Plan Pro",
        "unit_amount": "99.00",
        "quantity": 1,
        "amount": "99.00"
      }
    ],
    "frequency": "MONTHLY",
    "interval": 1,
    "day_of_month": 5,
    "last_day_of_month": false,
    "day_of_week": null,
    "start_date": "2026-10-05",
    "end_date": null,
    "charge_time": "09:00",
    "next_charge_at": "2026-11-05T14:00:00.000Z",
    "status": "ACTIVE",
    "payment_method": {
      "id": "pm_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
      "type": "YAPE",
      "phone_last4": "4567",
      "status": "ACTIVE"
    },
    "retry_policy": {
      "interval_days": [
        1,
        3,
        5
      ],
      "on_exhausted": "past_due"
    },
    "latest_cycle": {
      "id": "subc_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
      "billing_period": "2026-10",
      "due_date": "2026-10-05",
      "amount": {
        "amount": "99.00",
        "currency": "PEN"
      },
      "status": "PAID",
      "attempts": 1,
      "last_failure_code": null,
      "next_attempt_at": null,
      "payment_intent_id": "pi_01J8Z3K4M5N6P7Q8R9S0T1U2V5",
      "checkout_url": null,
      "paid_at": "2026-10-05T14:00:03.000Z"
    },
    "external_reference": "cliente-4821",
    "metadata": {},
    "cancelled_at": null,
    "created_at": "2026-10-05T14:00:00.000Z",
    "updated_at": "2026-10-05T14:00:03.000Z"
  }
}