> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkout de Preços Dinâmicos com Pague o Que Quiser
> Crie links de checkout flexíveis com preços variáveis usando um único produto. Ative Pague o Que Quiser para permitir que os clientes escolham seu preço ou definam valores dinâmicos programaticamente.
**Preços dinâmicos** permitem que você ofereça preços variáveis para seus produtos sem criar várias entradas de produtos. Ao ativar **Pague o Que Quiser (PWYW)** em um único produto, você pode definir limites de preço mínimo e máximo e, em seguida, passar valores dinâmicos ao criar links de sessão de checkout.
Essa abordagem é ideal quando você precisa:
* **Preços variáveis** sem gerenciar vários produtos
* **Preços impulsionados pelo cliente** onde os compradores escolhem seu valor
* **Controle de preço programático** onde você define o valor dinamicamente via API
* **Modelos de preços flexíveis** para produtos digitais, doações ou lançamentos experimentais
Pay What You Want está disponível apenas para produtos **Single Payment** (pagamento único). Não pode ser usado com produtos de assinatura.
## Como Funciona
Com Pague o Que Quiser ativado, você pode:
1. **Defina limites de preço**: Especifique um preço mínimo (obrigatório) e, opcionalmente, um preço máximo
2. **Envie valores dinâmicos**: Inclua um campo `amount` no carrinho do produto ao criar sessões de checkout
3. **Deixe os clientes escolherem**: Se nenhum valor for fornecido, os clientes podem inserir o próprio preço (dentro dos limites definidos)
Quando você envia um `amount` no carrinho do produto, esse valor é usado no checkout. Se você omitir o campo `amount`, os clientes podem escolher o próprio preço durante o checkout (conforme seus limites mínimo/máximo).
## Passo 1: Criar um Produto com Pague o Que Quiser
Primeiro, crie um produto de pagamento único no seu painel do Dodo Payments e ative a precificação Pague o Que Quiser.
Navegue até **Products** no seu painel Dodo Payments e clique em **Add Product**.
Preencha as informações obrigatórias do produto:
* **Product Name**: Nome exibido para o seu produto
* **Product Description**: Descrição clara do que os clientes estão comprando
* **Product Image**: Faça upload de uma imagem (PNG/JPG/WebP, até 3 MB)
* **Tax Category**: Selecione a categoria tributária apropriada
Selecione **Pricing Type** como **Single Payment** (pagamento único).
Na seção **Pricing**, habilite o interruptor **Pay What You Want**.
Digite o **Minimum Price** que os clientes devem pagar. Isso é obrigatório e garante que você mantenha um piso de receita.
**Exemplo**: Se o seu mínimo for \$5,00, digite `5.00` (ou `500` centavos).
Opcionalmente, defina um **Maximum Price** para limitar o valor que os clientes podem pagar.
Opcionalmente, insira um **Suggested Price** que será exibido para orientar os clientes. Isso ajuda a ancorar expectativas e pode melhorar o ticket médio.
Clique em **Add Product** para salvar. Anote o ID do produto (por exemplo, `pdt_123abc456def`) para usar nas sessões de checkout.
Você pode encontrar o ID do produto no painel em **Products** → **View Details**, ou usando o [List Products API](/api-reference/products/get-products).
## Passo 2: Criar Sessões de Checkout com Preços Dinâmicos
Depois que seu produto estiver configurado com Pay What You Want, você pode criar sessões de checkout com valores dinâmicos. O campo `amount` no carrinho do produto permite definir o preço programaticamente para cada sessão de checkout.
### Entendendo o Campo de Valor
Ao criar uma sessão de checkout, você pode incluir um campo `amount` em cada item do carrinho do produto:
* **Se `amount` for fornecido**: O checkout usa esse valor exato (deve estar dentro dos seus limites mínimo/máximo)
* **Se `amount` for omitido**: Os clientes podem inserir seu próprio preço durante o checkout (dentro dos seus limites)
O campo `amount` é aplicável apenas a produtos Pay What You Want. Para produtos comuns, esse campo é ignorado.
### Exemplos de Código
```typescript TypeScript theme={null}
import DodoPayments from 'dodopayments';
// Initialize the Dodo Payments client
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});
async function createDynamicPricingCheckout(
productId: string,
amountInCents: number,
returnUrl: string
) {
try {
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
// Dynamic amount in cents (e.g., 1500 = $15.00)
amount: amountInCents
}
],
return_url: returnUrl,
// Optional: Pre-fill customer information
customer: {
email: 'customer@example.com',
name: 'John Doe'
},
// Optional: Add metadata for tracking
metadata: {
order_id: 'order_123',
pricing_tier: 'custom'
}
});
console.log('Checkout URL:', session.checkout_url);
console.log('Session ID:', session.session_id);
return session;
} catch (error) {
console.error('Failed to create checkout session:', error);
throw error;
}
}
// Example: Create checkout with $25.00 (2500 cents)
const session = await createDynamicPricingCheckout(
'prod_123abc456def',
2500, // $25.00 in cents
'https://yoursite.com/checkout/success'
);
// Example: Create checkout with $10.00 (1000 cents)
const session2 = await createDynamicPricingCheckout(
'prod_123abc456def',
1000, // $10.00 in cents
'https://yoursite.com/checkout/success'
);
```
```python Python theme={null}
import os
from dodopayments import DodoPayments
# Initialize the Dodo Payments client
client = DodoPayments(
bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
)
def create_dynamic_pricing_checkout(
product_id: str,
amount_in_cents: int,
return_url: str
):
"""
Create a checkout session with dynamic pricing.
Args:
product_id: The product ID with Pay What You Want enabled
amount_in_cents: The amount in cents (e.g., 2500 for $25.00)
return_url: URL to redirect after payment completion
Returns:
Session object with checkout_url and session_id
"""
try:
session = client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1,
# Dynamic amount in cents (e.g., 1500 = $15.00)
"amount": amount_in_cents
}
],
return_url=return_url,
# Optional: Pre-fill customer information
customer={
"email": "customer@example.com",
"name": "John Doe"
},
# Optional: Add metadata for tracking
metadata={
"order_id": "order_123",
"pricing_tier": "custom"
}
)
print(f"Checkout URL: {session.checkout_url}")
print(f"Session ID: {session.session_id}")
return session
except Exception as error:
print(f"Failed to create checkout session: {error}")
raise error
# Example: Create checkout with $25.00 (2500 cents)
session = create_dynamic_pricing_checkout(
"prod_123abc456def",
2500, # $25.00 in cents
"https://yoursite.com/checkout/success"
)
# Example: Create checkout with $10.00 (1000 cents)
session2 = create_dynamic_pricing_checkout(
"prod_123abc456def",
1000, # $10.00 in cents
"https://yoursite.com/checkout/success"
)
```
**Formato do valor**: O campo `amount` deve estar na menor denominação da moeda. Para USD, isso significa centavos (por exemplo, \$25,00 = `2500`). Para outras moedas, use a menor unidade (por exemplo, paise para INR).
## Passo 3: Deixar os Clientes Escolherem Seu Preço
Se quiser que os clientes escolham o próprio preço durante o checkout, basta omitir o campo `amount` do carrinho do produto. A página de checkout exibirá um campo de entrada onde os clientes poderão inserir qualquer valor dentro dos seus limites mínimo e máximo.
```typescript TypeScript theme={null}
async function createCustomerChoiceCheckout(
productId: string,
returnUrl: string
) {
try {
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1
// No amount field - customer will choose their price
}
],
return_url: returnUrl,
customer: {
email: 'customer@example.com',
name: 'John Doe'
}
});
return session;
} catch (error) {
console.error('Failed to create checkout session:', error);
throw error;
}
}
```
```python Python theme={null}
def create_customer_choice_checkout(
product_id: str,
return_url: str
):
"""
Create a checkout session where customers choose their own price.
"""
try:
session = client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1
# No amount field - customer will choose their price
}
],
return_url=return_url,
customer={
"email": "customer@example.com",
"name": "John Doe"
}
)
return session
except Exception as error:
print(f"Failed to create checkout session: {error}")
raise error
```
## Casos de Uso Comuns
### Caso de Uso 1: Preços em Camadas com Base no Tipo de Usuário
Ofereça preços diferentes para diferentes segmentos de clientes usando o mesmo produto:
```typescript theme={null}
// Student discount: $10.00
const studentSession = await createDynamicPricingCheckout(
'prod_123abc456def',
1000, // $10.00
'https://yoursite.com/success'
);
// Regular price: $25.00
const regularSession = await createDynamicPricingCheckout(
'prod_123abc456def',
2500, // $25.00
'https://yoursite.com/success'
);
// Premium price: $50.00
const premiumSession = await createDynamicPricingCheckout(
'prod_123abc456def',
5000, // $50.00
'https://yoursite.com/success'
);
```
### Caso de Uso 2: Preços Dinâmicos com Base na Quantidade
Ajuste o preço com base na quantidade comprada:
```typescript theme={null}
async function createQuantityBasedCheckout(
productId: string,
quantity: number
) {
// Base price: $20.00 per unit
// Discount: 10% for 2+ items, 20% for 5+ items
const basePrice = 2000; // $20.00 in cents
let discount = 0;
if (quantity >= 5) {
discount = 0.20; // 20% off
} else if (quantity >= 2) {
discount = 0.10; // 10% off
}
const totalAmount = Math.round(basePrice * quantity * (1 - discount));
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: quantity,
amount: totalAmount
}
],
return_url: 'https://yoursite.com/success'
});
return session;
}
```
### Caso de Uso 3: Preços Baseados em Tempo ou Promoções
Aplique preços promocionais durante períodos específicos:
```typescript theme={null}
async function createPromotionalCheckout(productId: string) {
const isPromoActive = checkIfPromotionActive(); // Your logic
const regularPrice = 3000; // $30.00
const promoPrice = 2000; // $20.00
const amount = isPromoActive ? promoPrice : regularPrice;
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
amount: amount
}
],
return_url: 'https://yoursite.com/success',
metadata: {
pricing_type: isPromoActive ? 'promotional' : 'regular'
}
});
return session;
}
```
## Melhores Práticas
Escolha um preço mínimo que cubra seus custos e ainda seja acessível. Use um preço sugerido para orientar as expectativas dos clientes.
Sempre valide se os valores dinâmicos estão dentro dos limites mínimo e máximo do seu produto antes de criar sessões de checkout.
Use metadata para rastrear por que valores específicos foram escolhidos (por exemplo, `pricing_tier`, `discount_code`, `user_segment`).
Certifique-se de que sua aplicação trate com elegância os casos em que os valores ultrapassam os limites máximos ou ficam abaixo dos mínimos.
## Validação e Tratamento de Erros
Sempre valide os valores em relação às configurações mínimas e máximas do seu produto:
```typescript TypeScript theme={null}
async function createValidatedCheckout(
productId: string,
amountInCents: number,
minAmount: number,
maxAmount: number | null
) {
// Validate minimum
if (amountInCents < minAmount) {
throw new Error(
`Amount ${amountInCents} is below minimum ${minAmount}`
);
}
// Validate maximum (if set)
if (maxAmount !== null && amountInCents > maxAmount) {
throw new Error(
`Amount ${amountInCents} exceeds maximum ${maxAmount}`
);
}
// Create checkout session
return await client.checkoutSessions.create({
product_cart: [
{
product_id: productId,
quantity: 1,
amount: amountInCents
}
],
return_url: 'https://yoursite.com/success'
});
}
```
```python Python theme={null}
def create_validated_checkout(
product_id: str,
amount_in_cents: int,
min_amount: int,
max_amount: int | None
):
"""
Create a checkout session with amount validation.
"""
# Validate minimum
if amount_in_cents < min_amount:
raise ValueError(
f"Amount {amount_in_cents} is below minimum {min_amount}"
)
# Validate maximum (if set)
if max_amount is not None and amount_in_cents > max_amount:
raise ValueError(
f"Amount {amount_in_cents} exceeds maximum {max_amount}"
)
# Create checkout session
return client.checkout_sessions.create(
product_cart=[
{
"product_id": product_id,
"quantity": 1,
"amount": amount_in_cents
}
],
return_url="https://yoursite.com/success"
)
```
## Referência da API
Saiba mais sobre o modelo de precificação Pay What You Want e seus recursos.
Explore recursos avançados de sessão de checkout e opções de personalização.
## Solução de Problemas
Se o seu campo `amount` estiver sendo ignorado, verifique se:
* O produto tem o **Pay What You Want** ativado no painel
* O produto é um **Single Payment** (pagamento único), não uma assinatura
* O valor está no formato correto (menor denominação da moeda, por exemplo, centavos para USD)
A API rejeitará sessões de checkout em que o valor viole os limites de preço do seu produto. Sempre valide os valores antes de criar sessões de checkout ou permita que os clientes escolham o próprio preço omitindo o campo `amount`.
Se os clientes não estiverem vendo o campo de entrada de preço, certifique-se de ter omitido o campo `amount` do carrinho do produto. Quando o `amount` é fornecido, o checkout usa esse valor exato.