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 de 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:

Qué no genera prorrateos

Muchas actualizaciones de suscripciones no afectan la facturación ni generan prorrateos. Realiza estas actualizaciones en cualquier momento sin crear partidas de factura prorrateadas:

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 se producen antes del período de facturación. El 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 las 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 mientras tiene una factura pendiente de pago correspondiente al periodo actual, es posible que reciba un crédito por el tiempo no utilizado del plan de precio más alto, incluso si aún no ha pagado por 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 período de facturación original: crea una factura única de los cargos nuevos de forma manual.
2. Para cobrar de inmediato por el nuevo plan y restablecer el período de facturación: Configura billing_cycle_anchor en now. Para obtener más detalles, consulta Restablecer el período de facturación al momento 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][id]"=sub_item_1 \
  -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][id]"=sub_item_1 \
  -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
          }]
        },
    ] }
  }
}

Cómo cancelar el ítem de suscripción mensual 10 USD:

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

Cuando se elimina un ítem de suscripción, el billing_mode asociado a esa suscripción afecta la forma en que se calcula el prorrateo de la siguiente manera:

# 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. Dado que Stripe prorratea hasta los segundos, los importes prorrateados pueden cambiar entre el momento en que se accede a la vista previa y aquel en que se hace la actualización. Para evitar esto, especifica un valor subscription_details.proration_date al momento de crear una vista previa. Cuando actualices la suscripción, especifica la misma fecha con el parámetro proration_date en la suscripción de forma que el prorrateo se calcule con respecto 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 facturarle al cliente de inmediato un cambio en una suscripción en el mismo período de facturación, configura proration_behavior en always_invoice cuando modifiques la suscripción. De esta manera, se calcula el prorrateo y, luego, se genera de inmediato 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.