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

# Listar Reembolsos

> Reembolsos dos seus produtos: os pedidos pelo comprador e os já devolvidos.

#### Escopo

```bash theme={null}
    read orders
```

## Como funciona o reembolso pedido pelo comprador

Quando o comprador pede reembolso, a venda vira `refund_requested`, o valor fica retido no seu
saldo e abre-se uma janela que termina em `autoApproveAt`:

* **o comprador pode desistir** até lá, e a venda volta a `paid`;
* **você pode aprovar antes**, com [Aprovar Reembolso](/api-reference/refunds/approve.md);
* **se ninguém agir**, o reembolso é efetivado automaticamente em `autoApproveAt`.

A devolução **não depende da sua aprovação**. A janela existe para você falar com o comprador, e
o contato dele vem em `customer`.

> [!TIP]
>
> Para saber na hora que um reembolso foi pedido, sem consultar esta lista de tempos em tempos,
> assine o evento de webhook `refund_requested`. Ver [Guia de Webhooks](/conceitos/webhooks.md#bloco-do-pedido-de-reembolso).

## Estados

| `status` | O que significa |
| - | - |
| `refund_requested` | pedido pelo comprador, janela aberta até `autoApproveAt` |
| `in_settlement` | aprovado, por você ou pelo prazo. O estorno foi enviado e a adquirente ainda não confirmou a devolução |
| `acquirer_error` | a adquirente recusou o estorno. Não se resolve pela API: fale com o suporte informando o `id` |
| `refunded` | devolvido ao comprador. `refundedAt` traz quando |

O `id` de cada reembolso é o **id do pedido**. Reembolso feito direto pelo painel, sem pedido do
comprador, também aparece aqui, com `requestedAt` nulo.

> [!NOTE]
>
> **O estorno é da cobrança inteira.** Numa compra com order bump, os pedidos da mesma cobrança
> são reembolsados juntos, e cada um aparece nesta lista com o seu `id`. `parentOrderId` liga o
> order bump ao pedido principal.

## Filtros

| Parâmetro | |
| - | - |
| `status` | `refund_requested`, `in_settlement`, `acquirer_error` ou `refunded` |
| `requestedAt__gte` / `requestedAt__lte` | janela pela data do **pedido de reembolso** (`YYYY-MM-DD`), inclusive nos dois lados |
| `product` | id do produto |
| `page` / `limit` | paginação, como em toda listagem do contrato. Default `10` por página, máximo `500` |

A resposta vem no [envelope de paginação](/conceitos/paginacao.md) do contrato: `count`, `next`,
`previous` e `results`, do pedido de reembolso mais recente para o mais antigo.

> [!NOTE]
>
> A listagem traz só pedidos de produto **da conta dona do token**, que é quem pode aprovar.

***

## Exemplo

```python Python theme={null}
import requests

resposta = requests.get(
    "https://api.cakto.com.br/public_api/refunds/",
    params={"status": "refund_requested", "limit": 50},
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."},
    timeout=30,
)
resposta.raise_for_status()

for reembolso in resposta.json()["results"]:
    cliente = reembolso["customer"]
    print(reembolso["autoApproveAt"], cliente["name"], cliente["phone"])
```

```javascript Node.js theme={null}
const params = new URLSearchParams({ status: "refund_requested", limit: "50" });

const resposta = await fetch(`https://api.cakto.com.br/public_api/refunds/?${params}`, {
  headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." },
});

if (!resposta.ok) throw new Error(`Cakto API error ${resposta.status}`);

const pagina = await resposta.json();
for (const reembolso of pagina.results) {
  console.log(reembolso.autoApproveAt, reembolso.customer.name, reembolso.customer.phone);
}
```


## OpenAPI

````yaml GET /public_api/refunds/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/refunds/:
    get:
      tags:
        - refunds
      description: >-
        Reembolsos dos seus produtos, do pedido de reembolso mais recente para o
        mais antigo: os abertos pelo comprador e os já devolvidos. O `id` de
        cada um é o id do pedido.
      operationId: refunds_list
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
          description: Itens por página. Default `10`, máximo `500`.
        - in: query
          name: page
          schema:
            type: integer
          description: Página a retornar. Default `1`.
        - in: query
          name: product
          schema:
            type: string
          description: Id do produto.
        - in: query
          name: requestedAt__gte
          schema:
            type: string
            format: date
          description: Pedidos de reembolso a partir desta data (`YYYY-MM-DD`), inclusive.
        - in: query
          name: requestedAt__lte
          schema:
            type: string
            format: date
          description: Pedidos de reembolso até esta data (`YYYY-MM-DD`), inclusive.
        - in: query
          name: status
          schema:
            type: string
            enum:
              - acquirer_error
              - in_settlement
              - refund_requested
              - refunded
          description: >-
            Filtra por estado. `refund_requested` é a fila do que ainda pode ser
            aprovado.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRefundList'
              examples:
                Sucesso:
                  value:
                    count: 123
                    next: http://api.example.org/accounts/?page=4
                    previous: http://api.example.org/accounts/?page=2
                    results:
                      - id: 5f2a1c3e-8b7d-4e21-9f10-3c6d7a2b9e41
                        refId: Q7W2k9P
                        status: refund_requested
                        amount: '197.00'
                        currency: BRL
                        paymentMethod: pix
                        offerType: main
                        parentOrderId: null
                        reason: Comprei por engano
                        refundedBy: customer
                        paidAt: '2026-09-26T10:14:03.201544-03:00'
                        requestedAt: '2026-09-28T09:41:22.873610-03:00'
                        autoApproveAt: '2026-09-29T09:41:22.873610-03:00'
                        settlementStartedAt: null
                        refundedAt: null
                        customer:
                          id: 183921
                          name: Maria Souza
                          email: maria.souza@example.com
                          birthDate: null
                          phone: '11999999999'
                          docType: cpf
                          docNumber: '12345678909'
                        product:
                          id: ff3fdf61-e88f-43b5-982a-32d50f112414
                          short_id: AckhQ75
                          name: Curso de Exemplo
                        offer:
                          id: B8BcHrY
                          name: Oferta principal
          description: >-
            Reembolsos dos seus produtos, do pedido de reembolso mais recente
            para o mais antigo.
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
              examples:
                StatusInvalido:
                  value:
                    status:
                      - >-
                        Faça uma escolha válida. paid não é uma das escolhas
                        disponíveis.
          description: 'Filtro inválido: o corpo diz qual parâmetro e por quê.'
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
      security:
        - OAuth Token: []
components:
  schemas:
    PaginatedRefundList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    Refund:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Id do pedido. É também o id do reembolso: é por ele que se consulta
            e aprova.
        refId:
          type: string
          readOnly: true
          description: Id curto do pedido, o mesmo que aparece no painel.
        status:
          allOf:
            - $ref: '#/components/schemas/RefundStatusEnum'
          readOnly: true
          description: >-
            `refund_requested`: o comprador pediu e a janela está aberta; se
            ninguém agir, o reembolso é efetivado em `autoApproveAt`.
            `in_settlement`: aprovado, aguardando a adquirente confirmar a
            devolução. `acquirer_error`: a adquirente recusou o estorno.
            `refunded`: devolvido.


            * `refund_requested` - refund_requested

            * `in_settlement` - in_settlement

            * `acquirer_error` - acquirer_error

            * `refunded` - refunded
        amount:
          type: string
          format: decimal
          example: '2.49'
          readOnly: true
          description: Valor deste pedido, como string decimal.
        currency:
          type: string
          readOnly: true
          description: Moeda do pedido.
        paymentMethod:
          type: string
          readOnly: true
          description: Método de pagamento do pedido.
        offerType:
          type: string
          readOnly: true
          description: '`main`, `orderbump`, `upsell` ou `downsell`.'
        parentOrderId:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Id do pedido principal da mesma compra, quando este é order bump ou
            upsell.
        reason:
          type: string
          readOnly: true
          nullable: true
          description: Motivo informado pelo comprador ao pedir o reembolso.
        refundedBy:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Quem acionou o reembolso: `customer` (pedido pelo comprador),
            `producer` (aprovado ou feito pelo produtor) ou `admin` (suporte da
            Cakto).
        paidAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Quando o pedido foi pago.
        requestedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Quando o comprador pediu o reembolso. `null` em reembolso feito sem
            solicitação.
        autoApproveAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Fim da janela da solicitação: se o comprador não cancelar e ninguém
            aprovar antes, o reembolso é efetivado automaticamente neste
            instante. `null` fora da janela.
        settlementStartedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Quando o estorno foi enviado à adquirente.
        refundedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Quando a adquirente confirmou a devolução. `null` enquanto não
            confirmou.
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerOrder'
          readOnly: true
          description: 'Comprador: nome e contato para falar com ele dentro da janela.'
        product:
          allOf:
            - $ref: '#/components/schemas/RefundProduct'
          readOnly: true
        offer:
          allOf:
            - $ref: '#/components/schemas/RefundOffer'
          readOnly: true
          nullable: true
      required:
        - amount
        - autoApproveAt
        - currency
        - customer
        - id
        - offer
        - offerType
        - paidAt
        - parentOrderId
        - paymentMethod
        - product
        - reason
        - refId
        - refundedAt
        - refundedBy
        - requestedAt
        - settlementStartedAt
        - status
    RefundStatusEnum:
      enum:
        - refund_requested
        - in_settlement
        - acquirer_error
        - refunded
      type: string
      description: |-
        * `refund_requested` - refund_requested
        * `in_settlement` - in_settlement
        * `acquirer_error` - acquirer_error
        * `refunded` - refunded
    CustomerOrder:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          title: Nome
          description: Nome completo do cliente
          maxLength: 255
        email:
          type: string
          format: email
          description: Endereço de email do cliente
          maxLength: 254
        birthDate:
          type: string
          format: date
          nullable: true
          title: Nascimento
          description: Data de nascimento do cliente
        phone:
          type: string
          title: Telefone
          description: Número de telefone do cliente
          maxLength: 255
        docType:
          nullable: true
          title: Tipo de Documento
          description: |-
            Tipo do documento (ex: cpf, cnpj)

            * `cpf` - CPF
            * `cnpj` - CNPJ
            * `dni` - DNI
            * `cuit` - CUIT
          oneOf:
            - $ref: '#/components/schemas/DocTypeEnum'
            - $ref: '#/components/schemas/BlankEnum'
            - $ref: '#/components/schemas/NullEnum'
        docNumber:
          type: string
          nullable: true
          title: Documento
          description: Número do documento do cliente
          maxLength: 255
      required:
        - email
        - id
        - name
        - phone
    RefundProduct:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do produto
          maxLength: 255
        short_id:
          type: string
          title: ID Curto
          description: Identificador curto do produto
          maxLength: 40
        name:
          type: string
          title: Nome
          description: Nome do produto
          maxLength: 255
      required:
        - name
    RefundOffer:
      type: object
      properties:
        id:
          type: string
          title: Identificador
          description: Identificador único da oferta
          maxLength: 40
        name:
          type: string
          title: Nome
          description: Nome da oferta, exibido no checkout e em outros locais
          maxLength: 255
      required:
        - name
    DocTypeEnum:
      enum:
        - cpf
        - cnpj
        - dni
        - cuit
      type: string
      description: |-
        * `cpf` - CPF
        * `cnpj` - CNPJ
        * `dni` - DNI
        * `cuit` - CUIT
    BlankEnum:
      enum:
        - ''
    NullEnum:
      enum:
        - null
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````

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