customer é o cadastro de um cliente na conta: contato, identificação, preferências de email e indicadores de receita. O vínculo com pedidos usa o ID do cliente. Criar um cliente não cria um pedido nem concede acesso a conteúdo.
Objeto completo
Formato retornado pelas consultas e pelos itens das listagens. Os campos de retorno não são todos editáveis; confira as regras de escrita abaixo.Campos do objeto
string
Identificador público estável. Use o valor retornado pela API nas consultas e relacionamentos; não derive IDs de nomes.
string | null
Cidade do cliente; null quando ausente.
string | null
País informado no cadastro; null quando ausente.
string
Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.
string | null
Moeda dos indicadores do cliente. Pode ser null. Somente leitura.
string | null
Documento do cliente como string, preservando zeros à esquerda; null quando ausente.
string | null
Tipo do documento informado, como cpf ou cnpj; null quando ausente.
string | null
Email do cliente. Obrigatório e não vazio na criação; convertido para minúsculas ao criar.
string | null
Situação de email marketing: subscribed, unsubscribed, archived, requires_verification, invalid_email ou bounced.
string | null
Identificador do cliente no seu sistema. Pode ser null. Não substitui o id da Hubfy.
string | null
Primeiro nome; null quando ausente.
string | null
Sobrenome; null quando ausente.
object
Objeto JSON livre para referências da integração, limitado a 16 KB. Ao enviar, substitui todo o metadata anterior; use
{} para limpar. Não aceita null.integer
Receita recorrente mensal registrada para o cliente, em centavos. Somente leitura.
string | null
Nome do cliente. Obrigatório e não vazio na criação.
string
Tipo do objeto retornado. O valor é fixo para este recurso.Sempre
customer.string | null
Telefone do cliente como string; null quando ausente.
string | null
Estado ou região do cliente; null quando ausente.
integer
Receita acumulada registrada para o cliente, em centavos. Não deve ser enviada em criação ou atualização.
string
Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.
Criação e alterações
Na criação, envieemail e name, ambos não vazios. O email é convertido para minúsculas. Se já existir um cliente com esse email na conta, a criação retorna esse cadastro e preenche somente valores ausentes; não sobrescreve os dados existentes. Para alterar valores preenchidos, use a atualização.
A atualização aceita os dados de contato, identificação, preferências, external_id e metadata. Os indicadores financeiros e currency são somente leitura. Excluir um cliente não é uma operação de estorno ou cancelamento; vínculos que impeçam a remoção retornam erro.
Campos omitidos em uma atualização são preservados. metadata substitui o objeto inteiro quando enviado. Campos desconhecidos são rejeitados.
Relacionamentos
Pedidos apontam para este cadastro pelo campocustomer. Use GET /v1/orders?customer=cus_1234567890abcdef para listar os pedidos associados.
Eventos
Clientes não possuem eventos públicos próprios. Para mudanças nos pedidos do cliente, recebaorder.updated e confira o campo customer do pedido.
Eventos descrevem mudanças efetivas no objeto público. Repetir uma operação sem alterar o objeto não garante um evento. Confira entrega e assinatura.