Cambia el precio de las suscripciones existentes

Cuando un cliente cambia su suscripción, tú debes cambiar el ítem de suscripción para que refleje la nueva selección. Por ejemplo, un cliente puede cambiar a un nivel prémium o a un plan inferior de nivel básico, lo que te pedirá que reemplaces el precio subyacente de ese ítem de suscripción. Puedes hacerlo usando varios métodos diferentes.

Recuperar los identificadores

Independientemente del método que elijas, deberás proporcionar identificadores para los objetos que estás actualizando. Usa el método de suscripciones de listas con un filtro pertinente (como la ID de cliente) para encontrar la suscripción y el ítem que se actualizará.

curl -G https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}}

Devuelve el conjunto de suscripciones para el cliente especificado, desde donde puedes recuperar el ID de suscripción (id), cualquier ID de ítem de suscripción (items.data.id) y el ID de precio de los ítems de suscripción (items.data.price.id).

{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "su_1NXPiE2eZvKYlo2COk9fohqA",
      "object": "subscription",
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false
      },
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_OK3pbS1dvdQYJP",
            "object": "subscription_item",
            "billing_thresholds": null,
            "created": 1690208774,
            "metadata": {},
            "price": {
              "id": "price_1NOhvg2eZvKYlo2CqkpQDVRT",
              "object": "price"
            }
          }
        ]
      }
    }
  ]
}

Actualizar la suscripción

Actualiza una suscripción e incluye los siguientes parámetros:

• item ID: debes especificar el ítem de suscripción para reemplazar el precio actual por el nuevo precio. De lo contrario, si actualizas la suscripción con un nuevo precio, se agregará un nuevo ítem de suscripción y ambos precios estarán activos en la suscripción.
• item price: proporciona el identificador del precio de reemplazo.
• item quantity: la actualización de un precio de suscripción revierte automáticamente la cantidad al valor predeterminado de 1. Si la cantidad de suscripción vigente es distinta de 1 y deseas conservar ese valor, debes incluirla en la actualización.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}}

Como alternativa, puedes eliminar el ítem de suscripción actual y crear un nuevo ítem de suscripción con el precio actualizado.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][deleted]"=true \
  -d "items[1][price]"={{NEW_PRICE_ID}}

Actualizar el ítem de la suscripción

Actualiza un ítem de suscripción con los siguientes parámetros:

• precio: Proporciona el identificador del precio de reemplazo.
• cantidad: Actualizar el precio de una suscripción revierte automáticamente la cantidad al valor predeterminado de 1. Si la cantidad de suscripción existente es diferente de 1 y deseas conservar ese valor, debes incluirlo en la actualización.

Usa esta opción si no tienes que hacer ningún otro cambio a nivel de la suscripción.

curl https://api.stripe.com/v1/subscription_items/si_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d price={{NEW_PRICE_ID}}

Períodos de facturación

Si ambos precios tienen los mismos períodos de facturación (combinación de interval e interval_count), la suscripción conserva las mismas fechas de facturación. Si los precios tienen diferentes períodos de facturación, el nuevo precio se factura en el nuevo intervalo, a partir del día del cambio. Por ejemplo, cambiar a un cliente de una suscripción mensual a otra no cambia las fechas de facturación. Sin embargo, cambiar a un cliente de una suscripción mensual a una anual cambia la fecha de facturación a la fecha del cambio. Cambiar a un cliente de una suscripción mensual a otra mientras se introduce un período de prueba, también mueve la fecha de facturación (hasta la finalización de la prueba).

Calendarios de suscripciones

Si vas a cambiar una suscripción al final de su ciclo de facturación, considera la posibilidad de usar un calendario de suscripciones para gestionar la transición. Cuando utilices los calendarios de suscripciones, asegúrate de seguir las prácticas recomendadas para evitar sobreescribir suscripciones.

Cobro por consumo con medidores de cobro

Los detalles sobre las actualizaciones de mitad de ciclo de los precios asociados a un medidor de cobro se describen en la sección de modelos de precios. Especificar clear_usage cuando se actualiza un precio con un medidor de cobro no tiene ningún efecto.

Cobro por consumo con registros de consumo Legacy

Si tienes un precio por consumo medido respaldado por registros de consumo heredados y actualizas a un nuevo precio de registros de consumo, el consumo se transfiere al precio nuevo.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}} \
  -d "items[0][clear_usage]"=true

Prorrata

Cambiar de suscripción suele implicar un prorrateo para aplicar el nuevo precio a los días restantes del período de cobro. Puedes anticiparle a tu cliente los gastos adicionales que pudieran resultar de un cambio de precio. Para ello, facilítale la vista previa de un prorrateo. Como alternativa, puedes deshabilitar los prorrateos.

Pago inmediato

Stripe intenta inmediatamente el pago cuando se restablece la delimitación del ciclo de facturación de una suscripción. Aprende más sobre cómo restablecer la delimitación del ciclo de facturación de una suscripción.

Si la facturación se hace de inmediato, pero el pago requerido falla, la solicitud de cambio de suscripción se realizará correctamente y el estado de la suscripción será past_due.

Para cobrar a un cliente de inmediato por un cambio en una suscripción en el mismo ciclo de cobro, establece proration_behavior como always_invoice. Esta configuración calcula el prorrateo y genera de inmediato una factura después de hacer el cambio. Combina esta configuración con las actualizaciones pendientes para que la suscripción no se actualice a menos que el pago se realice correctamente en la nueva factura.

Prorrateos de crédito

Se emiten prorrateos en forma de crédito cuando los clientes reducen sus suscripciones o cancelan items antes de que finalice su período de facturación. Stripe ofrece dos métodos para calcular estos prorrateos, según la configuración de facturación_mode de tu suscripción. Consulta Prorrateos de crédito para obtener más información.

Gestionar precios y cantidades de importe cero

Si realizaste la suscripción de un cliente a un precio de importe cero (por ejemplo, como prueba), cambiar el precio a un importe distinto de cero genera una factura y restablece el período de facturación a la fecha del cambio.

Si realizaste la suscripción de un cliente a un precio con un importe distinto de cero y una cantidad de cero, cambiar la cantidad a un número distinto de cero no genera una factura ni restablece el período de facturación.