# Venda

URL: https://staging.pagpolar.com/docs/referencia/entidades/venda

> Uma cobrança: avulsa ou um ciclo de assinatura. Traz status, valores, itens e os dados para o cliente pagar.

Uma cobrança: avulsa ou um ciclo de assinatura. Traz status, valores, itens e os dados para o cliente pagar.

## Onde aparece

* [`GET /sales`](/docs/referencia/vendas/list-sales)
* [`GET /sales/{identifier}`](/docs/referencia/vendas/get-sale)
* [`GET /payments/{identifier}`](/docs/referencia/vendas/get-payment)

Os valores em dinheiro vêm em **reais**, como número.

## Campos

Campos anuláveis chegam com `null`. Campos com opções fixas listam todos os valores.

| Campo | Tipo | Obrigatório | Nulo | Descrição |
| --- | --- | --- | --- | --- |
| `id` | texto (uuid) | não | não | Id da venda. É o mesmo valor que volta em `transactions` na criação do pagamento e pode ser usado em `GET /sales/{identifier}`. Exemplo: `a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d`. |
| `identifier` | texto | não | não | Código da venda: prefixo `PPO` seguido de 10 dígitos. É o mesmo código do painel e do webhook. Exemplo: `PPO9876543210`. |
| `external_reference` | texto | não | sim | Referência do pedido enviada por você na criação do pagamento ou da assinatura. `null` quando não foi enviada. Exemplo: `PED-2026-0001`. |
| `status` | enum | não | não | Valores: `DRAFT`, `OPEN`, `PROCESSING`, `PAID`, `CANCELED`, `ASK_REFUND`, `REFUNDED`, `REFUNDING`, `ABANDONED`, `EXPIRED`, `FAILED`, `CHARGEBACK_REQUESTED`, `CHARGEBACK_APPROVED`. Exemplo: `PAID`. |
| `type` | enum | não | não | Valores: `BILLING`, `TRANSFER`, `FEE`. Exemplo: `BILLING`. |
| `payment_method` | enum | não | não | Valores: `CREDIT_CARD`, `PIX`, `BOLETO`, `APPLE_PAY`, `GOOGLE_PAY`. Exemplo: `PIX`. |
| `installments` | inteiro | não | não | Exemplo: `1`. |
| `total_amount` | número | não | não | Exemplo: `197`. |
| `cycle` | inteiro | não | não | Posição do ciclo de cobrança para vendas recorrentes (não é a periodicidade — para isso veja Offer.cycle). 1 para venda avulsa. Exemplo: `1`. |
| `paid_at` | texto (date-time) | não | sim | null enquanto a venda não é paga. Exemplo: `2026-01-20T14:32:10.000Z`. |
| `refund_at` | texto (date-time) | não | sim | Exemplo: `null`. |
| `created_at` | texto (date-time) | não | não | Exemplo: `2026-01-20T14:30:00.000Z`. |
| `customer` | [Cliente](/docs/referencia/entidades/cliente) | não | não | — |
| `items` | lista de objetos | não | não | — |
| `items[].quantity` | inteiro | não | não | Exemplo: `1`. |
| `items[].amount` | número | não | não | Exemplo: `197`. |
| `items[].original_amount` | número | não | não | Exemplo: `197`. |
| `items[].discount_value` | número | não | não | Exemplo: `0`. |
| `items[].offer` | objeto | não | sim | — |
| `items[].offer.id` | texto (uuid) | não | não | — |
| `items[].offer.identifier` | texto | não | não | Código da oferta: prefixo `PPP` seguido de 10 dígitos. Exemplo: `PPP1234567890`. |
| `items[].offer.title` | texto | não | não | Exemplo: `Plano Mensal`. |
| `items[].product` | objeto | não | sim | — |
| `items[].product.id` | texto (uuid) | não | não | — |
| `items[].product.name` | texto | não | não | Exemplo: `Curso de Marketing Digital`. |
| `items[].product.type` | texto | não | não | Exemplo: `DIGITAL`. |
| `shipping` | objeto | não | sim | Frete cobrado e endereço de entrega. `null` quando a venda não tem entrega. |
| `shipping.amount` | número | não | não | Valor do frete em reais, já somado ao total da venda. Exemplo: `32.9`. |
| `shipping.option_name` | texto | não | sim | Nome da opção de frete escolhida na cobrança. Exemplo: `SEDEX`. |
| `shipping.address` | objeto | não | sim | — |
| `shipping.address.street` | texto | não | não | Exemplo: `Rua das Flores`. |
| `shipping.address.number` | texto | não | não | Exemplo: `123`. |
| `shipping.address.complement` | texto | não | sim | Exemplo: `Apto 4B`. |
| `shipping.address.neighborhood` | texto | não | não | Exemplo: `Centro`. |
| `shipping.address.city` | texto | não | não | Exemplo: `São Paulo`. |
| `shipping.address.state` | texto | não | não | Exemplo: `SP`. |
| `shipping.address.postal_code` | texto | não | não | Exemplo: `01311000`. |
| `payment_details` | objeto | não | sim | null antes da venda ser processada (ex.: aguardando confirmação do gateway). |
| `payment_details.qr_code` | texto | não | sim | Exemplo: `00020126...`. |
| `payment_details.qr_code_expires_at` | texto (date-time) | não | sim | — |
| `payment_details.billet_barcode` | texto | não | sim | Exemplo: `34191.79001 01043.510047 91020.150008 1 96610000015000`. |
| `payment_details.billet_link` | texto | não | sim | Exemplo: `https://boletos.pagpolar.com/a1b2c3d4.pdf`. |
| `payment_details.last_credit_card_digits` | texto | não | sim | Exemplo: `4242`. |