Guía de migración de precios de Checkout

La API Prices añade nuevas funciones y flexibilidad a la forma en la que cobras a los clientes. Esta nueva integración ofrece:

• Modelos más unificados para los elementos de Checkout; en lugar de planes, SKU y partidas alineadas, ahora cada elemento es un precio.
• La capacidad de procesar imágenes de productos para artículos recurrentes.
• Crear un producto y un catálogo de precios reutilizables en lugar de ítems de factura puntuales.
• Crea tarifas alineadas para suscripciones.
• Aplicar tipos fiscales dinámicos a las suscripciones y a los pagos puntuales.

¿No quieres migrar? Puedes seguir usando tu integración actual, pero las nuevas funciones no son compatibles. Puedes usar cualquier plan o precio recurrente nuevos que crees en el parámetro de plan de tus llamadas a la API existentes.

Resumen de productos y precios

Los precios son una nueva unidad central de Stripe que funciona con las suscripciones, las facturas y Checkout. Cada precio está vinculado a un único Product, y cada producto puede tener varios precios. Los diferentes bienes físicos o niveles de servicio deben estar representados por productos. El precio de ese producto debe estar representado por precios.

Define los precios base y, en el caso de productos recurrentes, el ciclo de facturación. Esto te permite cambiar y añadir los precios sin necesidad de cambiar los datos de lo que ofreces. Por ejemplo, puede que tengas un único producto «de oro» con precios de 10 USD al mes, 100 USD al año, 9 EUR al mes y 90 EUR al año. O quizás tengas una camiseta azul con un precio de 20 USD y 15 EUR.

Pagos puntuales

Las integraciones para pagos únicos tienen los siguientes cambios:

• En lugar de partidas específicas (que definan, por ejemplo, el nombre, el importe y la divisa), la creación de una sesión de Checkout requiere un producto y, por lo general, un precio.
• Ahora se requiere el modo.

El código del lado del cliente se mantiene igual.

Tabla de asignación

En lugar de definir cada campo en line_items, Checkout utiliza los objetos Product y Price de base para determinar el nombre, la descripción, el importe, la moneda y las imágenes. Puedes crear productos y precios con la API o en el Dashboard.

Código del lado del servidor para elementos alineados

Antes, solo podías crear ítems puntuales alineados. Con precios, puedes seguir configurando ítems alineados, pero también puedes definir precios en forma dinámica con price_data al crear la sesión de Checkout.

Cuando creas la sesión de Checkout con price_data, debes hacer referencia al ID de un producto existente con price_data.product o definir los datos del producto dinámicamente usando price_data.product_data. El siguiente ejemplo muestra el flujo para crear un ítem puntual.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][price_data][currency]"=usd \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Código del lado del servidor para precios puntuales

Con esta nueva integración, puedes crear un producto y un catálogo de precios de antemano en lugar de tener que definir el importe, la moneda y el nombre cada vez que crees una sesión de Checkout.

Puedes crear un producto y un precio con la API Prices o mediante el Dashboard. El ID del precio será necesario para crear una sesión de Checkout. El siguiente ejemplo ilustra cómo se crea un producto o precio a través de la API:

curl https://api.stripe.com/v1/products \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d name=T-shirt \
  -d description="Comfortable cotton t-shirt" \
  -d "images[]"="https://example.com/t-shirt.png"

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Suscripciones

Las integraciones para pagos recurrentes tienen los siguientes cambios:

• Todos los elementos pasan a un solo campo de line_items, en lugar de subscription_data.items.
• Ahora se requiere el modo. Establece mode=subscription si la sesión incluye algún elemento recurrente.

El código del lado del cliente se mantiene igual. Los planes existentes pueden usarse cuando se acepten los precios recurrentes.

Código del lado del servidor con planes

Este es un ejemplo del antes y el después de crear una sesión de Checkout durante el período de prueba usando un plan existente, que puede emplearse de forma intercambiable a un precio determinado. Ahora el plan ha pasado a line_items en lugar de subscription_data.items.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Código del lado del servidor para precios recurrentes con una tasa de instalación

Si tienes planes recurrentes con una tasa de instalación única, crea el producto y el precio que representen el costo único antes de crear la sesión de Checkout. Consulta la tabla de asignaciones para ver cómo se asignan los campos line_items anteriores a la nueva integración. Puedes crear un producto y un precio a través de la API Prices o a través del Dashboard de Stripe. También puedes crear el ítem puntual alineado. El siguiente ejemplo utiliza un ID de precio existente:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \
  -d "line_items[1][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Cambios en el objeto de respuesta

En lugar de enumerar los elementos con display_items, el objeto de la sesión de Checkout utiliza line_items. El campo line_items no procesa por defecto como en el caso de display_items, pero puedes incluirlo usando la opción de ampliar al crear una sesión de Checkout:

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="payment" \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Cambios del webhook

Como puede incluirse line_items, la respuesta del webhook checkout.session.completed ya no enumera elementos de forma predeterminada. El objeto de respuesta más pequeño te permite recibir los webhooks de Checkout más rápido. Puedes recuperar elementos con el nuevo punto de conexión line_items:

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Para obtener más información, consulta completar pedidos con Checkout.