Prorrateos

El aspecto más complejo a la hora de modificar suscripciones existentes son los prorrateos, mediante los que se le cobra al cliente un porcentaje del costo de la suscripción para reflejar un uso parcial. En esta página se explica cómo funcionan los prorrateos con las suscripciones y cómo administrarlos para tus clientes.

Cómo funcionan los prorrateos

Por ejemplo, actualizar o degradar una suscripción puede generar cargos prorrateados. Si un cliente pasa de un plan mensual de USD 10 a una opción de USD 20, se le cobrarán importes prorrateados por el tiempo que utilizó cada opción. Si el cambio se produjera a mitad del período de facturación, al cliente se le cobraría USD 5 adicionales: -USD 5 por el tiempo no utilizado conforme al precio inicial y USD 10 por el tiempo restante conforme al nuevo precio.

El prorrateo garantiza que al cliente se le cobre el importe correcto, pero puede traer aparejados importes de pago diferentes de los previstos. Los prorrateos negativos no se le reembolsan al cliente automáticamente ni los positivos se le cobran de inmediato, aunque ambas acciones pueden realizarse en forma manual.

Puedes previsualizar el prorrateo para ver el importe antes de aplicar los cambios. Para obtener más información sobre cómo funcionan los prorrateos de crédito, lee nuestra guía.

Prorrateos y descuentos

Todas las partidas de factura prorrateadas (prorations = true) se establecen en discountable = false. Los descuentos aplicados a una factura con prorrateos solo se aplican a las partidas de factura y las partidas factura no prorrateadas. Todos los descuentos aplicados anteriormente a la suscripción y que afecten al importe del prorrateo se reflejan en el importe de la partida de factura por prorrateo.

Los no prorrateos muestran ajustes de descuento en discount_amounts.

Qué desencadena los prorrateos

De forma predeterminada, los siguientes casos dan como resultado un prorrateo:

• El cambio a un precio con un costo base diferente.
• El cambio a un precio con un intervalo de cobro diferente.
• La incorporación de un período de prueba a una suscripción activa
• El cambio de la cantidad.
• Suscripciones bajo licencia (por usuario) (porque se les cobra al inicio de cada período de cobro)

Crear manualmente tus propios prorrateos

Para calcular tus propios prorrateos fuera de Stripe y agregarlos a la suscripción, especifica add_invoice_items con un unit_amount negativo (igual al importe del prorrateo calculado) en estos puntos de conexión:

• Crea una suscripción
• Actualiza una suscripción
• Crea un calendario de suscripciones
• Actualiza los calendarios de suscripciones

Cuándo se aplican los prorrateos

Los prorrateos solo se aplican a los cargos que ocurren antes del ciclo de cobro. El modelo de cobro por consumo no está sujeto al prorrateo.

El importe prorrateado se calcula en cuanto la API actualiza la suscripción. El momento de inicio y finalización del período de facturación en curso se utilizan para calcular el costo de la suscripción antes y después del cambio.

Prorrateos y facturas impagas

Stripe calcula los prorrateos según el estado de la suscripción en el momento de la actualización, asumiendo que las facturas anteriores de la suscripción se pagarán eventualmente. Si un cliente cambia su suscripción y tiene una factura impaga para el período actual, es posible que reciba un crédito por el tiempo no utilizado en el plan de mayor precio, incluso si aún no pagó ese tiempo.

Para evitar el crédito por el tiempo impago, puedes deshabilitar los prorrateos cuando la última factura de la suscripción esté impaga. Al actualizar la suscripción, establece proration_behavior en none. Selecciona uno de los siguientes enfoques:

1. Para mantener el ciclo de facturación original: Crea manualmente una factura puntual para los cargos nuevos.
2. Para aceptar pagos de inmediato por el nuevo plan y reiniciar el ciclo de facturación: configura billing_cycle_anchor a now. Para obtener más información, consulta Restablecer el ciclo de facturación a la hora actual.

Cualquiera de estos enfoques puede generar un doble pago si el cliente termina pagando la factura anterior. Para evitarlo, anula la factura no pagada.

Impuestos y prorrateos

Para obtener más información sobre cómo funcionan los impuestos con los prorrateos, consulta la sección Cobra impuestos sobre pagos recurrentes.

Prorrateos de crédito

Credit prorations are issued when customers downgrade their subscriptions or cancel subscription items before the end of their billing period. Stripe offers two approaches for calculating credit prorations, depending on whether you set your subscription’s billing_mode to classic or flexible.

Lógica de cálculo sin prorrateos

In the following scenario, you upgrade a 10 USD monthly subscription to 20 USD with the proration_behavior set to none for 10 days. There’s no previous debit to base it on. Later, you downgrade the subscription to 10 USD per month with the proration_behavior set to always_invoice.

Para configurar este escenario, primero se crea una suscripción de 10 USD por mes el 1 de abril:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_10_monthly

La respuesta incluye la factura creada para esta suscripción:

{
  id: "sub_123",
  latest_invoice: {
    id: "in_123",
    total: 10_00,
    currency: "usd"
    }
}

A continuación, el 11 de abril, actualiza la suscripción a 20 USD por mes sin crear prorrateos:

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_20_monthly \
  -d proration_behavior=none

La última factura no se modifica porque proration_behavior es none:

{
  id: "sub_123",
  latest_invoice: {
    id: "in_123"
  }
}

Finalmente, el 21 de abril, reduces el nivel de la suscripción a 10 USD por mes y creas prorrateos:

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_10_monthly \
  -d proration_behavior=always_invoice

# billing_mode = classic
  {
    id: "sub_123",
    latest_invoice: {
      id: "in_456",
      total: -3_34,
      currency: "usd"
    }
  }

# billing_mode = flexible
  {
    id: "sub_123",
    latest_invoice: {
      id: "in_456",
      total: 0,
      currency: "usd"
    }
  }

Lógica de cálculo para cupones aplicados a varios ítems de suscripción

Stripe pondera el cupón amount_off en el prorrateo del crédito para evitar la sobrefacturación.

En el siguiente escenario, un cupón de 5 USD se asigna de manera desigual a una suscripción mensual de 25 USD para un ítem de 10 USD y un ítem de 20 USD.

Para configurar este escenario, crea una suscripción con varios items y un cupón el 1 de febrero:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_20_monthly \
  -d "discounts[0][coupon]"=five_dollars_off

Lo que devuelve esta respuesta:

{
  id: "sub_123",
  latest_invoice: {
    id: "in_123",
    total: 25_00,
    currency: "usd",
    lines: {
      data: [
      {
        id: "ili_1",
        amount: 10_00,
        price: "price_10_monthly",
        discount_amounts: [{
          discount: "di_a",
          amount: 1_66 }] },
      {
        id: "ili_2",
        amount: 20_00,
        price: "price_20_monthly",
        discount_amounts: [{
          discount: "di_a",
          amount: 3_34
          }]
        },
    ] }
  }
}

To cancel the 10 USD monthly subscription item using billing_mode=classic:

curl https://api.stripe.com/v1/subscription_items/si_10_monthly \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d proration_behavior=create_prorations

Para cancelar el mismo ítem usando billing_mode=flexible:

curl https://api.stripe.com/v1/subscription_items/si_10_monthly \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d proration_behavior=create_prorations \
  -d billing_mode=flexible

# billing_mode = classic
  {
    "id": "sub_123",
    "latest_invoice": {
      "id": "in_456",
      "total": -250,
      "currency": "usd"
    }
  }

# billing_mode = flexible
  {
    "id": "sub_123",
    "latest_invoice": {
      "id": "in_789",
      "total": -417,
      "currency": "usd"
    }
  }

Previsualizar un prorrateo

Puedes crear una vista previa de la factura para previsualizar los cambios en una suscripción. Esta llamada API no modifica la suscripción. En cambio, devuelve la próxima factura en función de los parámetros especificados. Cambiar el price o la quantity genera un prorrateo. En este ejemplo, se cambia el price y se establece una fecha para el prorrateo.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

# Set proration date to this moment:
proration_date = Time.now.to_i

subscription = Stripe::Subscription.retrieve('sub_49ty4767H20z6a')

# See what the next invoice would look like with a price switch
# and proration set:
items = [{
  id: subscription.items.data[0].id,
  price: 'price_CBb6IXqvTLXp3f', # Switch to new price
}]

invoice = Stripe::Invoice.create_preview({
  customer: 'cus_4fdAW5ftNQow1a',
  subscription: 'sub_49ty4767H20z6a',
  subscription_details: {
    items: items,
    proration_date: proration_date,
  }
})

Puedes expandir la siguiente respuesta de ejemplo para ver:

• El crédito por el tiempo no utilizado conforme al precio anterior en las líneas 36-38.
• El costo por el tiempo de uso conforme al nuevo precio en las líneas 107-109.
• El nuevo subtotal y el total de la factura en las líneas 276-279.

{
  "id": "upcoming_in_1OujwkClCIKljWvsq5v2ICAN",
  "account_country": "US",
  "account_name": "Test account",
  "amount_due": 3627,
  "amount_paid": 0,
  "amount_remaining": 3627,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,

Usa esta información para confirmar los cambios con el cliente antes de modificar la suscripción. Debido a que Stripe prorratea hasta los segundos, los importes prorrateados pueden cambiar entre el momento en que se previsualizan y el momento en que se realiza la actualización. Para evitarlo, especifica un subscription_proration_date en la factura al previsualizar el cambio. Cuando actualices la suscripción, puedes especificar la misma fecha con el parámetro proration_date en la suscripción para que el prorrateo se calcule al mismo tiempo.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

subscription = Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    items: [
      {
        id: subscription.items.data[0].id,
        price: 'price_CBb6IXqvTLXp3f',
      },
    ],
    proration_date: proration_date,
  }
)

Controla el comportamiento de prorrateo

El prorrateo se controla mediante el parámetro proration_behavior, que tiene tres opciones de parámetros posibles: create_prorations, always_invoice, y none.

Comportamiento predeterminado

El parámetro predeterminado para proration_behavior es create_prorations, que crea partidas de factura de prorrateo cuando corresponda. Estas partidas de prorrateo solo se facturan de inmediato cuando se dan ciertas condiciones.

Crear prorrateos inmediatos

Para cobrar de inmediato a un cliente por un cambio en una suscripción en el mismo ciclo de cobro, establece proration_behavior en always_invoice cuando modifiques la suscripción. De este modo, se calcula el prorrateo y, luego, se genera inmediatamente una factura.

Deshabilitar prorrateos

Para deshabilitar los prorrateos por solicitud, establece el parámetro proration_behavior en none. Ningún parámetro desactiva todos los prorrateos futuros de una suscripción. Para deshabilitar los prorrateos de manera indefinida, establece proration_behavior en none para cada solicitud que genere prorrateos:

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "items[0][id]"="si_1AkFf6LlRB0eXbMtRFjYiJ0J" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -d "proration_behavior"="none"

Si se han deshabilitado los prorrateos, al generarse la siguiente factura, se les facturará a los cliente el importe total conforme al nuevo precio.