> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear suscripción

> Crea una suscripción recurrente asociada a un cliente.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="customer_id" type="string" required placeholder="9dd4158b-0e45-42bc-b56f-a4c1f856814d">
  ID del cliente que asumirá los cobros. [Crea primero el cliente](/client/customers/create).
</ParamField>

<ParamField body="name" type="string" required placeholder="Plan OnePay Pro">
  Nombre público de la suscripción.
</ParamField>

<ParamField body="description" type="string" placeholder="<p>Plan mensual</p>">
  Descripción rica que se mostrará en correos y facturas.
</ParamField>

<ParamField body="currency" type="string" required default="COP">
  Moneda en formato ISO-4217. Actualmente soportamos `COP`.
</ParamField>

<ParamField body="amount_in_cents" type="number" required placeholder="44900000">
  Valor a cobrar en cada ciclo expresado en centavos.
</ParamField>

<ParamField body="reference_price_in_cents" type="string" placeholder="44900000">
  Precio de referencia que se mostrará en UI. Puede diferir del `amount_in_cents` cuando usas pagos complejos.
</ParamField>

<ParamField body="cicle_frequency" type="string" required placeholder="monthly">
  Frecuencia: `daily`, `weekly`, `monthly`, `annual`.
</ParamField>

<ParamField body="cicles" type="number" placeholder="12">
  Número máximo de ciclos. Usa `null` para renovaciones indefinidas.
</ParamField>

<ParamField body="start_date" type="date" placeholder="2025-01-05T00:00:00Z">
  Fecha en la que deseas iniciar los cobros. Si se omite se usa la fecha actual.
</ParamField>

<ParamField body="internal_id" type="string" placeholder="SaaS-Plan-2025">
  Identificador que usas en tus sistemas.
</ParamField>

<ParamField body="plan_id" type="string" placeholder="9ddfcfc1-7b5e-490c-9731-4aabd986908e">
  ID del plan preconfigurado que deseas usar. [Ver cómo crear planes](/client/plans/create).
</ParamField>

<ParamField body="payment_mode" type="string" default="request" placeholder="request | auto_debit">
  Define si se cobrará automáticamente (`auto_debit`) o vía solicitudes (`request`).
</ParamField>

<ParamField body="suggest_auto_debit" type="boolean" default={false}>
  Si es `true`, el checkout sugerirá activar débito automático.
</ParamField>

<ParamField body="remember_to_pay_before" type="number" placeholder="3">
  Días de anticipación para recordatorios de pago.
</ParamField>

<ParamField body="cancel_after_no_payment_before" type="number" placeholder="2">
  Número de ciclos consecutivos fallidos antes de cancelar la suscripción.
</ParamField>

<ParamField body="metadata" type="object">
  Pares clave/valor para enriquecer la suscripción.
</ParamField>

<ParamField body="trial" type="object">
  Configuración del periodo de prueba.

  <Expandable title="Propiedades">
    <ParamField body="trial.has_trial" type="boolean" default={false}>
      Activa o desactiva el trial.
    </ParamField>

    <ParamField body="trial.trial_days" type="number" placeholder="14">
      Número de días del periodo de prueba.
    </ParamField>

    <ParamField body="trial.start_trial_date" type="date" placeholder="2025-01-05T00:00:00Z">
      Fecha desde la que se debe contar el trial.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="complex_payments" type="array">
  Pagos con valores especiales por ciclo (ej. matrículas o cargos iniciales).

  <Expandable title="items">
    <ParamField body="complex_payments[].amount_in_cents" type="number" placeholder="134700000">
      Valor que se cobrará en el ciclo indicado.
    </ParamField>

    <ParamField body="complex_payments[].apply_on_cicle" type="number" placeholder="1">
      Ciclo en el que aplica este pago.
    </ParamField>

    <ParamField body="complex_payments[].for_cicles" type="number" placeholder="1">
      Cantidad de ciclos que usarán este monto.
    </ParamField>

    <ParamField body="complex_payments[].label" type="string" placeholder="Noviembre - Diciembre">
      Texto descriptivo.
    </ParamField>

    <ParamField body="complex_payments[].target_price" type="string" placeholder="44900000">
      Precio base esperado para el ciclo posterior.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  **Métodos de pago permitidos**

  El método de pago disponible depende de la configuración de tu cuenta. Comunícate con el equipo de soporte para habilitar métodos adicionales.

  | Método                    | Campo requerido | Descripción                                     |
  | ------------------------- | --------------- | ----------------------------------------------- |
  | Cuenta bancaria (ACH)     | `account_id`    | Débito directo desde cuenta bancaria registrada |
  | Tarjeta de crédito/débito | `card_id`       | Cargo a tarjeta tokenizada                      |

  Solo uno de los dos (`account_id` o `card_id`) debe estar presente en la petición.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/subscriptions \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: subscription-001" \
    -d '{
      "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "name": "Plan Premium Mensual",
      "description": "<p>Acceso completo a todas las funcionalidades</p>",
      "currency": "COP",
      "amount_in_cents": 44900000,
      "reference_price_in_cents": "44900000",
      "cicle_frequency": "monthly",
      "cicles": null,
      "start_date": "2025-03-01T00:00:00Z",
      "payment_mode": "request",
      "suggest_auto_debit": true,
      "remember_to_pay_before": 3,
      "cancel_after_no_payment_before": 2,
      "trial": {
        "has_trial": true,
        "trial_days": 14,
        "start_trial_date": "2025-02-15T00:00:00Z"
      },
      "metadata": {
        "salesforce_id": "OP-554",
        "plan_type": "premium"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/subscriptions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'subscription-001'
    },
    body: JSON.stringify({
      customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
      name: 'Plan Premium Mensual',
      description: '<p>Acceso completo a todas las funcionalidades</p>',
      currency: 'COP',
      amount_in_cents: 44900000,
      reference_price_in_cents: '44900000',
      cicle_frequency: 'monthly',
      cicles: null,
      start_date: '2025-03-01T00:00:00Z',
      payment_mode: 'request',
      suggest_auto_debit: true,
      remember_to_pay_before: 3,
      cancel_after_no_payment_before: 2,
      trial: {
        has_trial: true,
        trial_days: 14,
        start_trial_date: '2025-02-15T00:00:00Z'
      },
      metadata: {
        salesforce_id: 'OP-554',
        plan_type: 'premium'
      }
    })
  });
  const subscription = await response.json();
  console.log(subscription.id);
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime

  url = "https://api.onepay.la/v1/subscriptions"
  headers = {
      "Authorization": "Bearer sk_test_xxx",
      "Content-Type": "application/json",
      "x-idempotency": "subscription-001"
  }
  data = {
      "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "name": "Plan Premium Mensual",
      "description": "<p>Acceso completo a todas las funcionalidades</p>",
      "currency": "COP",
      "amount_in_cents": 44900000,
      "reference_price_in_cents": "44900000",
      "cicle_frequency": "monthly",
      "cicles": None,
      "start_date": "2025-03-01T00:00:00Z",
      "payment_mode": "request",
      "suggest_auto_debit": True,
      "remember_to_pay_before": 3,
      "cancel_after_no_payment_before": 2,
      "trial": {
          "has_trial": True,
          "trial_days": 14,
          "start_trial_date": "2025-02-15T00:00:00Z"
      },
      "metadata": {
          "salesforce_id": "OP-554",
          "plan_type": "premium"
      }
  }

  response = requests.post(url, headers=headers, json=data)
  subscription = response.json()
  print(subscription["id"])
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  curl_setopt_array($ch, [
      CURLOPT_URL => "https://api.onepay.la/v1/subscriptions",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer sk_test_xxx",
          "Content-Type: application/json",
          "x-idempotency: subscription-001"
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
          "name" => "Plan Premium Mensual",
          "description" => "<p>Acceso completo a todas las funcionalidades</p>",
          "currency" => "COP",
          "amount_in_cents" => 44900000,
          "reference_price_in_cents" => "44900000",
          "cicle_frequency" => "monthly",
          "cicles" => null,
          "start_date" => "2025-03-01T00:00:00Z",
          "payment_mode" => "request",
          "suggest_auto_debit" => true,
          "remember_to_pay_before" => 3,
          "cancel_after_no_payment_before" => 2,
          "trial" => [
              "has_trial" => true,
              "trial_days" => 14,
              "start_trial_date" => "2025-02-15T00:00:00Z"
          ],
          "metadata" => [
              "salesforce_id" => "OP-554",
              "plan_type" => "premium"
          ]
      ])
  ]);

  $response = curl_exec($ch);
  $subscription = json_decode($response, true);

  echo $subscription["id"];

  curl_close($ch);
  ?>
  ```
</RequestExample>

### Response

<ResponseField name="id" type="string">
  Identificador único de la suscripción (UUID).
</ResponseField>

<ResponseField name="name" type="string">
  Nombre comercial de la suscripción.
</ResponseField>

<ResponseField name="status" type="string">
  Estado actual (`active`, `unpaid`, `pass_due`, `canceled`, `finished`, `frozen`).
</ResponseField>

<ResponseField name="description" type="string">
  Descripción enriquecida (puede contener HTML).
</ResponseField>

<ResponseField name="internal_id" type="string">
  Identificador interno que usas en tu sistema.
</ResponseField>

<ResponseField name="plan_id" type="string">
  ID del plan asociado, si aplica.
</ResponseField>

<ResponseField name="coupon_id" type="string">
  ID del cupón aplicado.
</ResponseField>

<ResponseField name="reference_price_in_cents" type="string">
  Precio de referencia en centavos como string.
</ResponseField>

<ResponseField name="currency" type="string">
  Moneda en formato ISO-4217 (ej. `COP`).
</ResponseField>

<ResponseField name="amount_in_cents" type="number">
  Valor base cobrado en cada ciclo.
</ResponseField>

<ResponseField name="cicle_frequency" type="string">
  Frecuencia de cobro: `weekly`, `monthly`, `annual`, etc.
</ResponseField>

<ResponseField name="cicles" type="number">
  Cantidad máxima de ciclos; `null` para indefinido.
</ResponseField>

<ResponseField name="current_cicle" type="number">
  Ciclo actual procesado.
</ResponseField>

<ResponseField name="allows" type="object">
  Configuración de métodos de pago permitidos para la suscripción.
</ResponseField>

<ResponseField name="suggest_auto_debit" type="boolean">
  Indica si se sugiere activar débito automático durante el onboarding del cliente.
</ResponseField>

<ResponseField name="start_date" type="date">
  Fecha programada de inicio.
</ResponseField>

<ResponseField name="end_date" type="date">
  Fecha de finalización si aplica.
</ResponseField>

<ResponseField name="trial" type="object">
  Información de periodo de prueba (`has_trial`, `trial_days`, `start_trial_date`).
</ResponseField>

<ResponseField name="payment_mode" type="string">
  Modo de cobro (`request`, `auto_debit`, etc.).
</ResponseField>

<ResponseField name="remember_to_pay_before" type="number">
  Días de anticipación para recordatorios de pago.
</ResponseField>

<ResponseField name="cancel_after_no_payment_before" type="number">
  Número de ciclos fallidos antes de cancelar automáticamente.
</ResponseField>

<ResponseField name="complex_payments" type="array">
  Pagos con valores diferenciados por ciclo.
</ResponseField>

<ResponseField name="metadata" type="object">
  Atributos personalizados que acompañan la suscripción.
</ResponseField>

<ResponseField name="customer" type="object">
  Resumen del cliente asociado.
</ResponseField>

<ResponseField name="plan" type="object">
  Información del plan enlazado, cuando existe.
</ResponseField>

<ResponseField name="created_at" type="date">
  Fecha de creación de la suscripción.
</ResponseField>

<ResponseField name="updated_at" type="date">
  Fecha de última actualización.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
    "name": "OnePay Pro",
    "status": "created",
    "description": "<p>Plan mensual con onboarding asistido</p>",
    "internal_id": "SaaSSpectre",
    "plan_id": null,
    "coupon_id": null,
    "reference_price_in_cents": "44900000",
    "currency": "COP",
    "amount_in_cents": 44900000,
    "cicle_frequency": "monthly",
    "cicles": null,
    "current_cicle": 0,
    "allows": {
      "cards": true,
      "accounts": true,
      "card_extra": false,
      "realtime": false,
      "pse": true,
      "transfiya": true
    },
    "suggest_auto_debit": true,
    "start_date": "2025-01-05T00:00:00.000000Z",
    "end_date": null,
    "payment_mode": "request",
    "trial": {
      "has_trial": false,
      "start_trial_date": null,
      "trial_days": 0
    },
    "remember_to_pay_before": 3,
    "cancel_after_no_payment_before": 2,
    "complex_payments": [],
    "features": [],
    "metadata": {
      "salesforce_id": "OP-554"
    },
    "created_at": "2025-01-02T19:24:48.000000Z",
    "updated_at": "2025-01-02T19:24:48.000000Z",
    "customer": {
      "id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "first_name": "Empresa",
      "last_name": "SAS",
      "email": "empresa@empresa.com",
      "phone": "+573221234567",
      "document": "1234567890",
      "document_type": "RUT"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "message": "Hay errores de validación. (y 2 errores más)",
    "code": 10001,
    "code_name": "validation_error",
    "errors": {
      "customer_id": [
        "El campo customer id es obligatorio."
      ],
      "amount_in_cents": [
        "El campo amount in cents es obligatorio."
      ],
      "cicle_frequency": [
        "Debes especificar una frecuencia válida."
      ]
    }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>