API Admin › Recursos

Clientes

As contas que os compradores abriram na área do cliente da loja, com os endereços salvos: a lista para o CRM ou o ERP sincronizar.

Escopo	O que abre
`read_customers`	ler as contas dos clientes, com o e-mail, o telefone, o CPF e os endereços

Só leitura: a conta é do comprador, que muda os dados, o e-mail e os endereços na própria área do cliente (a "Minha conta" da loja). A API não cria nem altera conta.

Quem é cliente aqui: quem entrou na área do cliente com o código mandado ao e-mail, na loja que ligou a área (Configurações › Conta do cliente). A compra continua sem cadastro: quem só comprou, sem entrar, não tem conta, e os dados dele estão nos pedidos (read_orders, ver Pedidos). A conta é da loja: o mesmo comprador em duas lojas tem duas contas, sem ligação entre elas.

Dados pessoais: cada conta traz o nome, o e-mail, o telefone, o CPF e os endereços salvos. Com read_customers, a integração passa a responder por esses dados na LGPD. Quando o comprador exclui a conta (ou a loja atende o pedido de exclusão em Privacidade), a conta some da API e o webhook customer.deleted avisa: apague os dados dela também na sua cópia.

O objeto cliente

{
  "id": "3f6b2c1e-...",
  "email": "helena@exemplo.com",
  "name": "Helena Souza",
  "phone": "41999990000",
  "cpf": "52998224725",
  "accepts_marketing": true,
  "accepts_marketing_at": "2026-10-03T18:05:00.000Z",
  "addresses": [
    {
      "id": "8a21...",
      "name": "Helena Souza",
      "zip": "80000000",
      "street": "Rua XV de Novembro",
      "number": "100",
      "complement": "Sala 2",
      "neighborhood": "Centro",
      "city": "Curitiba",
      "state": "PR",
      "default": true
    }
  ],
  "created_at": "2026-10-03T18:04:00.000Z",
  "updated_at": "2026-10-05T12:30:00.000Z"
}

email: o e-mail verificado pelo código, em minúsculas: o comprador provou que é dele. Um e-mail tem no máximo uma conta na loja. A troca de e-mail na área do cliente também passa por um código mandado ao e-mail novo.
name, phone e cpf: quando a conta nasce, vêm do pedido mais recente do e-mail; depois, o comprador muda na área do cliente, e o checkout com a conta completa o telefone e o CPF que faltavam. Telefone e CPF só com os números; null quando o comprador nunca informou. O CPF foi digitado pelo comprador e não foi conferido: não serve para provar quem é a pessoa.
accepts_marketing: o comprador marcou "Quero receber novidades" na área do cliente; accepts_marketing_at diz quando. Comprar não é aceitar propaganda: só mande campanhas a quem aceitou.
addresses: até 10, o padrão primeiro (default), depois os mais recentes. name é quem recebe a entrega no endereço. O endereço do pedido mais recente vira o primeiro quando a conta nasce.
updated_at: a última mudança do que este objeto mostra (os dados, o e-mail, as novidades ou os endereços). Entrar na conta não conta como mudança.

Os pedidos do cliente

O pedido traz a conta em customer.id (ver Pedidos): o pedido feito com a conta aberta no checkout e os pedidos antigos do mesmo e-mail, que passam a ser da conta quando o comprador entra pela primeira vez. A ligação é sempre pelo e-mail verificado, nunca pelo CPF. customer.id é null no pedido sem conta, no anonimizado e depois que a conta é excluída.

Quando o pedido entra numa conta, ou sai dela com a exclusão da conta, o updated_at do pedido muda e sai o webhook order.updated.

A lista

`GET /customers`

As contas, na ordem da última mudança, da mais antiga à mais nova (o id desempata). Para sincronizar, guarde o updated_at da última conta que leu e, na próxima vez, peça updated_at_min com ele (a data entra na lista: a última lida vem de novo). As contas excluídas não aparecem: para saber delas, use o webhook customer.deleted ou os eventos (ver Eventos).

Parâmetro	O que faz
`limit`	de 1 a 100 (50 sem ele)
`cursor`	o `next_cursor` da página anterior, como veio
`ids`	só estes ids, separados por vírgula (até 100)
`email`	só a conta deste e-mail (exato, sem diferença de maiúsculas)
`updated_at_min`	só o que mudou a partir desta data
`created_at_min`	só o criado a partir desta data
`created_at_max`	só o criado até esta data

A resposta é { "data": [cliente...], "next_cursor": "..." }; com mais páginas, o cabeçalho Link leva à próxima (rel="next"). Ver Listas.

`GET /customers/{id}`

Uma conta. A excluída dá 404.

Os webhooks

Evento	Quando	`data`
`customer.created`	o comprador entrou pela primeira vez (a conta nasceu)	o cliente
`customer.updated`	os dados, o e-mail, as novidades ou os endereços mudaram (na área do cliente ou no checkout)	o cliente
`customer.deleted`	a conta foi excluída pelo comprador ou em Privacidade	só `{ "id": "..." }`

Assinar os três pede read_customers. O cliente vai montado na hora do envio, como na API: o reenvio traz a conta como está agora, e a conta excluída depois do evento sai só com o id. Ver Webhooks.