> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zouti.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Objeto pedido

> Todos os campos do pedido e o significado de cada valor.

O pedido é o objeto que [Listar pedidos](/api-reference/orders/list) e
[Buscar pedido](/api-reference/orders/get) devolvem. A conta vê os pedidos em que é dona e os de
coprodução.

* **Formato fixo.** Todo campo abaixo vem sempre no JSON; campo sem valor vem `null`, nunca
  ausente. A exceção são as chaves dentro de `metadata`, que só aparecem quando existem no pedido.
* **Valores em centavos**, como inteiros: `27730` é R\$ 277,30.
* **Datas** em ISO 8601, UTC: `2026-10-14T13:05:22.418Z`.
* **Valores novos.** Listas de valores (como `status`) podem ganhar itens novos na `v1`. Trate um
  valor desconhecido sem falhar.

<Note>
  **Coprodução.** Com `role: COPRODUCER`, a conta vê os valores do pedido inteiro, não a parte
  dela na coprodução. Só `tracking` e `navigator` vêm `null` para o coprodutor.
</Note>

<ResponseExample>
  ```json Pedido próprio, cartão theme={null}
  {
    "object": "order",
    "id": "ord_8k2m4q6s1v3x5z7b9d0f2h",
    "role": "OWNER",
    "status": "PAID",
    "currency": "BRL",
    "amount_total": 27730,
    "amount_subtotal": 29700,
    "amount_in_brl": 27730,
    "created_at": "2026-10-14T13:05:22.418Z",
    "paid_at": "2026-10-14T13:05:24.902Z",
    "canceled_at": null,
    "updated_at": "2026-10-14T13:05:25.117Z",
    "customer": {
      "name": "Maria Oliveira",
      "email": "maria.oliveira@example.com",
      "phone": "+5511999998888",
      "document": "12345678909",
      "document_type": "CPF"
    },
    "shipping_address": {
      "line1": "Rua das Flores",
      "line2": "123",
      "line3": "Apto 45",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postal_code": "01001000",
      "full_name": "Maria Oliveira"
    },
    "payment": {
      "method": "CREDIT_CARD",
      "status": "PAID",
      "installments": 1,
      "amount": 27730,
      "interest_amount": 0,
      "discount_amount": 1970,
      "fee": 1386,
      "amount_refunded": 0,
      "refunded_at": null,
      "decline_code": null,
      "decline_message": null,
      "card": {
        "brand": "MASTERCARD",
        "last4": "4242"
      }
    },
    "items": [
      {
        "product_id": "prod_3n7p1r5t9w2y4a6c8e0g1j",
        "name": "Curso Completo de Fotografia",
        "quantity": 1,
        "unit_price": 19700,
        "sub_total": 19700,
        "currency": "BRL",
        "offer_id": "prod_offer_5d1f3h7k9m2p4r6t8v0x2z",
        "plan_id": null,
        "order_bump_id": null
      },
      {
        "product_id": "prod_6b8d0f2h4k6m8p0r2t4v6x",
        "name": "Pacote de Presets",
        "quantity": 1,
        "unit_price": 10000,
        "sub_total": 10000,
        "currency": "BRL",
        "offer_id": null,
        "plan_id": null,
        "order_bump_id": "ob_2c4e6g8j0l2n4q6s8u0w2y"
      }
    ],
    "offer": {
      "id": "prod_offer_5d1f3h7k9m2p4r6t8v0x2z",
      "name": "Oferta de lançamento"
    },
    "promocode": {
      "code": "BEMVINDO10",
      "description": "10% de desconto no curso",
      "amount": -1970
    },
    "utm": {
      "utm_source": "instagram",
      "utm_medium": "social",
      "utm_campaign": "lancamento-outubro",
      "utm_term": null,
      "utm_content": "stories"
    },
    "tracking": {
      "sck": "parceiro-123",
      "src": "bio"
    },
    "navigator": {
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Instagram 350.0.0",
      "referer": "https://www.instagram.com/",
      "device": "Mobile",
      "browser": "Instagram",
      "origin": "instagram.com"
    },
    "metadata": {}
  }
  ```

  ```json Coprodução, PIX theme={null}
  {
    "object": "order",
    "id": "ord_1q3s5u7w9y0a2c4e6g8i0k",
    "role": "COPRODUCER",
    "status": "PAID",
    "currency": "BRL",
    "amount_total": 9700,
    "amount_subtotal": 9700,
    "amount_in_brl": 9700,
    "created_at": "2026-10-13T18:42:10.036Z",
    "paid_at": "2026-10-13T18:43:51.274Z",
    "canceled_at": null,
    "updated_at": "2026-10-13T18:43:52.009Z",
    "customer": {
      "name": "Maria Oliveira",
      "email": "maria.oliveira@example.com",
      "phone": "+5511999998888",
      "document": "12345678909",
      "document_type": "CPF"
    },
    "shipping_address": null,
    "payment": {
      "method": "PIX",
      "status": "PAID",
      "installments": 1,
      "amount": 9700,
      "interest_amount": 0,
      "discount_amount": 0,
      "fee": 485,
      "amount_refunded": 0,
      "refunded_at": null,
      "decline_code": null,
      "decline_message": null,
      "card": null
    },
    "items": [
      {
        "product_id": "prod_9x1z3b5d7f9h1k3m5p7r9t",
        "name": "Mentoria em Grupo",
        "quantity": 1,
        "unit_price": 9700,
        "sub_total": 9700,
        "currency": "BRL",
        "offer_id": "prod_offer_4w6y8a0c2e4g6j8l0n2q4s",
        "plan_id": null,
        "order_bump_id": null
      }
    ],
    "offer": {
      "id": "prod_offer_4w6y8a0c2e4g6j8l0n2q4s",
      "name": "Mentoria em Grupo"
    },
    "promocode": null,
    "utm": null,
    "tracking": null,
    "navigator": null,
    "metadata": {
      "order_parent_id": "ord_7h9k1m3p5r7t9v1x3z5b7d"
    }
  }
  ```
</ResponseExample>

## Atributos

<ResponseField name="object" type="string">
  Tipo do objeto: sempre `order`.
</ResponseField>

<ResponseField name="id" type="string">
  Identificador do pedido, com prefixo `ord_`. Use-o como chave do pedido na sua base.
</ResponseField>

<ResponseField name="role" type="string">
  Papel da conta no pedido.

  * `OWNER`: a conta é dona do pedido.
  * `COPRODUCER`: a conta participa do pedido por coprodução. Vê os valores do pedido inteiro, não
    a parte dela; `tracking` e `navigator` vêm `null`.
</ResponseField>

<ResponseField name="status" type="string">
  Situação do pedido.

  * `AWAITING_PAYMENT`: PIX ou boleto emitido e ainda pagável. Também o pagamento dividido entre a
    primeira e a segunda parte, e o primeiro status do parcelado inteligente.
  * `UNPAID`: a cobrança foi tentada e não foi paga. Cartão recusado (inclusive pelo antifraude),
    PIX ou boleto expirado, período de teste de assinatura que terminou sem conversão, ou
    assinatura cancelada no prazo de inadimplência. Um cartão recusado no checkout aparece assim,
    com `payment.status` `DECLINED` e `payment.decline_code` preenchido.
  * `PAID`: todo pagamento cobrado está pago (no pagamento dividido, todas as partes). Um estorno
    parcial mantém `PAID`.
  * `CANCELED`: pagamento dividido não concluído em 20 minutos. As partes já pagas são estornadas.
  * `REFUNDED`: todo pagamento cobrado foi estornado por inteiro.
  * `DISPUTED`: chargeback em todo pagamento cobrado. Uma disputa ganha volta o pedido para `PAID`.
  * `TRIAL`: assinatura em período de teste, com o cartão guardado e sem cobrança. Os valores vêm
    `0`.
  * `SHIPPED`, `DELIVERED`: reservados. Não são usados hoje.

  A renovação de uma assinatura não muda o status do pedido: o pagamento novo entra no mesmo
  pedido e aparece em `payment`. Um pedido cuja cobrança falhou na infraestrutura da Zouti, sem
  chegar ao banco, não aparece nesta API.
</ResponseField>

<ResponseField name="currency" type="string | null">
  Moeda do pedido, em ISO 4217 (ex. `BRL`).
</ResponseField>

<ResponseField name="amount_total" type="integer">
  Valor cobrado no checkout, em centavos. No parcelado inteligente, o valor total do contrato.
</ResponseField>

<ResponseField name="amount_subtotal" type="integer | null">
  Soma de preço × quantidade dos produtos, em centavos.
</ResponseField>

<ResponseField name="amount_in_brl" type="integer | null">
  Valor total em BRL, em centavos. Hoje é igual a `amount_total` nos pedidos de infoproduto.
</ResponseField>

<ResponseField name="created_at" type="string">
  Instante de criação do pedido.
</ResponseField>

<ResponseField name="paid_at" type="string | null">
  Instante em que o pedido foi pago. `null` quando não foi.
</ResponseField>

<ResponseField name="canceled_at" type="string | null">
  Instante do cancelamento. `null` quando não houve.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Instante (UTC, com milissegundos) da última mudança em algum campo deste objeto: status,
  valores, pagamento, estorno, cliente, endereço, itens, oferta, cupom, UTM ou metadados. Um
  reprocessamento interno que não muda nada do que a API devolve não avança este campo. `null` em
  pedido que ainda não passou pelo preenchimento inicial.

  É o campo da [sincronização de pedidos](/concepts/sync), com `sort=updated_at_asc` e
  `updated_gte`.
</ResponseField>

<ResponseField name="customer" type="object">
  Comprador.

  <Expandable title="propriedades">
    <ResponseField name="name" type="string">
      Nome do comprador.
    </ResponseField>

    <ResponseField name="email" type="string">
      E-mail do comprador.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      Telefone do comprador (ex. `+5511999998888`).
    </ResponseField>

    <ResponseField name="document" type="string | null">
      CPF (11 dígitos) ou CNPJ (14 dígitos) do comprador, só dígitos.
    </ResponseField>

    <ResponseField name="document_type" type="string | null">
      Tipo de `document`, pelo número de dígitos.

      * `CPF`: 11 dígitos.
      * `CNPJ`: 14 dígitos.

      `null` quando não há documento.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping_address" type="object | null">
  Endereço de entrega informado no checkout. `null` quando o pedido não tem endereço.

  <Expandable title="propriedades">
    <ResponseField name="line1" type="string">
      Logradouro.
    </ResponseField>

    <ResponseField name="line2" type="string">
      Número.
    </ResponseField>

    <ResponseField name="line3" type="string | null">
      Complemento.
    </ResponseField>

    <ResponseField name="neighborhood" type="string">
      Bairro.
    </ResponseField>

    <ResponseField name="city" type="string">
      Cidade.
    </ResponseField>

    <ResponseField name="state" type="string">
      Estado (ex. `SP`).
    </ResponseField>

    <ResponseField name="country" type="string">
      País (ex. `BR`).
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      CEP (ex. `01001000`).
    </ResponseField>

    <ResponseField name="full_name" type="string | null">
      Nome do destinatário.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment" type="object">
  Último pagamento do pedido: o mais recente pela data de criação. Na renovação de assinatura, no
  parcelado inteligente e numa nova tentativa, os valores são os desse último pagamento. Só no
  pagamento dividido (`method` `MULTIPLE`) os valores somam as partes pagas.

  <Expandable title="propriedades">
    <ResponseField name="method" type="string">
      Forma de pagamento.

      * `CREDIT_CARD`: cartão de crédito.
      * `BOLETO`: boleto bancário.
      * `PIX`: PIX.
      * `MULTIPLE`: pagamento dividido em 2 ou mais pagamentos, com cartão e/ou PIX, com mínimo de
        R\$ 5 por parte. Nenhum pagamento individual tem esse método.
    </ResponseField>

    <ResponseField name="status" type="string">
      Situação do último pagamento.

      * `PENDING`: em andamento.
      * `FAILED`: não chegou ao banco, por falha de comunicação da Zouti. Pode aparecer num pedido
        visível, como uma renovação que falhou.
      * `DECLINED`: recusado pelo banco, pelo adquirente ou pelo antifraude. O motivo vem em
        `decline_code` e `decline_message`.
      * `PAID`: pago.
      * `UNPAID`: PIX ou boleto expirado.
      * `PARTIALLY_REFUNDED`: estornado em parte.
      * `REFUNDED`: estornado por inteiro.
      * `DISPUTED`: chargeback.
      * `TRIAL`: período de teste de assinatura, sem cobrança.
    </ResponseField>

    <ResponseField name="installments" type="integer | null">
      Número de parcelas, a partir de `1`. PIX e boleto: `1`. `null` só em registro antigo.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Valor cobrado no último pagamento, em centavos. No pagamento dividido, a soma das partes
      pagas. `0` em `TRIAL`.
    </ResponseField>

    <ResponseField name="interest_amount" type="integer">
      Juros de parcelamento do pagamento, em centavos.
    </ResponseField>

    <ResponseField name="discount_amount" type="integer">
      Desconto do pagamento, em centavos, como valor **positivo**: soma do cupom, do desconto por
      forma de pagamento e do desconto por quantidade.
    </ResponseField>

    <ResponseField name="fee" type="integer">
      Taxa da Zouti pelo plano da conta, em centavos. Não inclui a taxa do adquirente nem a
      comissão de afiliado.
    </ResponseField>

    <ResponseField name="amount_refunded" type="integer | null">
      Total estornado, em centavos: acumulado e bruto.
    </ResponseField>

    <ResponseField name="refunded_at" type="string | null">
      Instante do estorno do último pagamento. `null` quando não houve.
    </ResponseField>

    <ResponseField name="decline_code" type="string | null">
      Motivo da recusa no código padronizado da Zouti: `ZT-` seguido de 4 dígitos (ex. `ZT-1000`).
      `null` quando o último pagamento não foi recusado.

      Um cartão recusado no checkout, inclusive pelo antifraude, deixa o pedido `UNPAID` com
      `payment.status` `DECLINED` e este campo preenchido. O mesmo vale para uma renovação de
      assinatura recusada, que não muda o status do pedido.
    </ResponseField>

    <ResponseField name="decline_message" type="string | null">
      Texto do motivo da recusa, para mostrar ao comprador. `null` quando não houve recusa.
    </ResponseField>

    <ResponseField name="card" type="object | null">
      Cartão do pagamento: só a bandeira e os últimos 4 dígitos. `null` quando o pagamento não foi
      com cartão.

      <Expandable title="propriedades">
        <ResponseField name="brand" type="string | null">
          Bandeira do cartão: `AMERICAN_EXPRESS`, `DINERS_CLUB_INTERNATIONAL`, `DISCOVER`, `ELO`,
          `ELO_DISCOVER`, `HIPERCARD`, `JCB`, `MAESTRO`, `MASTERCARD`, `OUROCARD`, `SODEXO`,
          `UNIONPAY` ou `VISA`. `null` quando a bandeira não é reconhecida. A lista pode crescer.
        </ResponseField>

        <ResponseField name="last4" type="string">
          Últimos 4 dígitos do cartão.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="items" type="object[]">
  Produtos do pedido.

  <Expandable title="propriedades">
    <ResponseField name="product_id" type="string">
      Identificador do produto, com prefixo `prod_`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome do produto.
    </ResponseField>

    <ResponseField name="quantity" type="integer">
      Quantidade.
    </ResponseField>

    <ResponseField name="unit_price" type="integer">
      Preço unitário, em centavos.
    </ResponseField>

    <ResponseField name="sub_total" type="integer">
      `unit_price` × `quantity`, em centavos.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Moeda do item. Hoje sempre `BRL`.
    </ResponseField>

    <ResponseField name="offer_id" type="string | null">
      Oferta do produto pela qual o item foi vendido, com prefixo `prod_offer_`. `null` quando não
      há.
    </ResponseField>

    <ResponseField name="plan_id" type="string | null">
      Plano da oferta do item, com prefixo `prod_offer_plan_`. `null` quando não há.
    </ResponseField>

    <ResponseField name="order_bump_id" type="string | null">
      Order bump que acrescentou o item, com prefixo `ob_`. `null` quando o item não veio de order
      bump.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="offer" type="object | null">
  Oferta do checkout em que o pedido foi feito. `null` quando não há.

  <Expandable title="propriedades">
    <ResponseField name="id" type="string">
      Identificador da oferta, com prefixo `prod_offer_`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome da oferta.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promocode" type="object | null">
  Cupom aplicado no pedido. `null` sem cupom.

  <Expandable title="propriedades">
    <ResponseField name="code" type="string">
      Código do cupom.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Descrição do cupom.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Desconto do cupom em centavos, como valor **negativo** (ex. `-1970`). O mesmo desconto entra
      em `payment.discount_amount` como valor positivo.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="utm" type="object | null">
  Parâmetros UTM do checkout. `null` quando o pedido não tem UTM.

  <Expandable title="propriedades">
    <ResponseField name="utm_source" type="string | null">
      Valor de `utm_source`.
    </ResponseField>

    <ResponseField name="utm_medium" type="string | null">
      Valor de `utm_medium`.
    </ResponseField>

    <ResponseField name="utm_campaign" type="string | null">
      Valor de `utm_campaign`.
    </ResponseField>

    <ResponseField name="utm_term" type="string | null">
      Valor de `utm_term`.
    </ResponseField>

    <ResponseField name="utm_content" type="string | null">
      Valor de `utm_content`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tracking" type="object | null">
  Parâmetros de rastreamento que vieram na URL do checkout (ex. `sck`, `src`, `xcod`), como chave →
  valor, com valores em texto. `null` quando o pedido não tem rastreamento ou quando a conta é
  coprodutora (`role` `COPRODUCER`).
</ResponseField>

<ResponseField name="navigator" type="object | null">
  Navegador do comprador no checkout. Nunca traz o IP. `null` quando o pedido não registrou
  navegador nem página de origem, ou quando a conta é coprodutora (`role` `COPRODUCER`).

  <Expandable title="propriedades">
    <ResponseField name="user_agent" type="string | null">
      User-Agent do navegador do comprador.
    </ResponseField>

    <ResponseField name="referer" type="string | null">
      Página de onde o comprador chegou ao checkout.
    </ResponseField>

    <ResponseField name="device" type="string | null">
      Tipo de dispositivo, derivado do `user_agent`. Hoje `Mobile`, `Tablet` ou `Desktop`.
    </ResponseField>

    <ResponseField name="browser" type="string | null">
      Navegador, derivado do `user_agent` (ex. `Chrome`, `Safari`, `Instagram`). `null` quando não
      é reconhecido.
    </ResponseField>

    <ResponseField name="origin" type="string | null">
      Domínio do `referer`, sem `www.` (ex. `instagram.com`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Metadados comerciais do pedido. Cada chave só aparece quando existe no pedido.

  <Expandable title="propriedades">
    <ResponseField name="order_parent_id" type="string">
      Pedido de origem de um upsell.
    </ResponseField>

    <ResponseField name="origin" type="string">
      Origem do checkout.
    </ResponseField>

    <ResponseField name="currency_rate" type="number">
      Câmbio usado para converter o pedido em outra moeda para BRL.
    </ResponseField>
  </Expandable>
</ResponseField>

## Situações comuns

Como `status` e `payment.status` aparecem juntos nos casos mais frequentes:

| Situação | `status` | `payment.status` |
| - | - | - |
| Cartão aprovado | `PAID` | `PAID` |
| Cartão recusado no checkout, inclusive pelo antifraude | `UNPAID` | `DECLINED`, com `decline_code` |
| PIX ou boleto expirado sem pagamento | `UNPAID` | `UNPAID` |
| Estorno parcial | `PAID` | `PARTIALLY_REFUNDED` |
| Estorno total | `REFUNDED` | `REFUNDED` |
| Chargeback | `DISPUTED` | `DISPUTED` |
| Assinatura em período de teste | `TRIAL` | `TRIAL` |
| Renovação de assinatura recusada | não muda | `DECLINED`, com `decline_code` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.