Consulta um cliente
/v1/customers/{customerId}Autentique com o header SelectKey: a chave sk_test_ opera no sandbox, a sk_live_ em produção. Como autenticar.
Parâmetros do caminho
customerIdstringobrigatórioIdentificador público (cus_…)
Respostas
200Sucesso
idstringobrigatórioIdentificador público (cus_…)
cardsobject[]Os cartões salvos do cliente (só na leitura individual).
+16 campos de
cardsidstringobrigatórioIdentificador público (card_…)
brandstringobrigatórioBandeira do cartão (ex.:
visa,mastercard).validbooleanobrigatórioSe o cartão passou na validação.
_linksobjectLinks para operações relacionadas, por ação (
self,create,update,delete,list…).activebooleanobrigatórioSe o cartão pode ser cobrado.
primarybooleanobrigatórioSe é o cartão principal do cliente.
merchantobjectA conta dona do recurso (o vendedor de registro).
+3 campos de
merchantnamestringobrigatóriopode ser nuloNome fantasia da conta dona do recurso.
merchantIdstringobrigatóriopode ser nuloId público da conta dona do recurso (
bus_…).isSubAccountbooleanobrigatóriotruequando o recurso pertence a uma sub-conta operada por uma plataforma de marketplace.
verifiedbooleanobrigatórioSe o cartão foi verificado com o emissor.
createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
associatedbooleanobrigatóriopode ser nuloSe o cartão está vinculado ao cliente para cobrança.
null= pendente: o cartão entrou por uma tela do comprador e ainda não tem cobrança aprovada.holderNamestringobrigatóriopode ser nuloNome impresso no cartão.
lastDigitsstringobrigatórioQuatro últimos dígitos do cartão.
firstDigitsstringobrigatórioSeis primeiros dígitos do cartão (BIN).
expirationYearstringobrigatórioAno de validade (
YYYY).expirationMonthstringobrigatórioMês de validade (
MM).
emailstringobrigatóriopode ser nuloEndereço de e-mail;
nullquando não há._linksobjectLinks para operações relacionadas, por ação (
self,create,update,delete,list…).genderstringobrigatóriopode ser nuloGênero (
male,female,other);nullquando desconhecido.documentobjectobrigatóriopode ser nuloDocumento do comprador;
nullquando não há.+2 campos de
documenttypestringobrigatóriopode ser nuloTipo do documento;
nullquando não há.Valores:cpfcnpjpassportnumberstringobrigatóriopode ser nuloNúmero do documento (dígitos em CPF/CNPJ);
nullquando não há.
lastNamestringobrigatórioSobrenome.
merchantobjectA conta dona do recurso (o vendedor de registro).
+3 campos de
merchantnamestringobrigatóriopode ser nuloNome fantasia da conta dona do recurso.
merchantIdstringobrigatóriopode ser nuloId público da conta dona do recurso (
bus_…).isSubAccountbooleanobrigatóriotruequando o recurso pertence a uma sub-conta operada por uma plataforma de marketplace.
metadataobjectobrigatóriopode ser nuloOs seus metadados chave-valor;
nullquando não há.addressesobject[]Os endereços do cliente (só na leitura individual).
+23 campos de
addressesidstringobrigatórioIdentificador público (addr_/cad_/cadm_/add_…)
citystringobrigatóriopode ser nuloCidade.
linestringobrigatóriopode ser nuloO endereço inteiro numa linha.
line1stringobrigatóriopode ser nuloPrimeira linha: logradouro e número.
line2stringobrigatóriopode ser nuloSegunda linha: bairro.
line3stringobrigatóriopode ser nuloTerceira linha: cidade, estado e CEP.
statestringobrigatóriopode ser nuloEstado (sigla de duas letras).
_linksobjectLinks para operações relacionadas, por ação (
self,create,update,delete,list…).numberstringobrigatóriopode ser nuloNúmero.
streetstringobrigatóriopode ser nuloLogradouro.
countrystringobrigatóriopode ser nuloCódigo do país (ISO 3166-1).
ownerIdstringobrigatórioId público do dono.
primarybooleanobrigatórioSe é o endereço principal do dono.
districtstringobrigatóriopode ser nuloBairro.
latitudestringobrigatóriopode ser nuloLatitude, em graus decimais como texto;
nullquando desconhecida.merchantobjectA conta dona do recurso (o vendedor de registro).
+3 campos de
merchantnamestringobrigatóriopode ser nuloNome fantasia da conta dona do recurso.
merchantIdstringobrigatóriopode ser nuloId público da conta dona do recurso (
bus_…).isSubAccountbooleanobrigatóriotruequando o recurso pertence a uma sub-conta operada por uma plataforma de marketplace.
metadataobjectobrigatóriopode ser nuloOs seus metadados chave-valor;
nullquando não há.postcodestringobrigatórioCEP, só dígitos.
createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
longitudestringobrigatóriopode ser nuloLongitude, em graus decimais como texto;
nullquando desconhecida.ownerTypestringobrigatórioQuem é dono do endereço: um
customer, a própriacompany, umuserou umvendor.Valores:vendorcustomercompanyuserupdatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
complementstringobrigatóriopode ser nuloComplemento (apartamento, sala, bloco…).
availablebooleanobrigatórioSe o cliente está ativo e pode ser cobrado.
birthdatestringobrigatóriopode ser nuloData de nascimento (
YYYY-MM-DD);nullquando desconhecida.createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
firstNamestringobrigatórioNome.
telephoneobjectobrigatóriopode ser nuloTelefone do comprador, em partes;
nullquando não há.+4 campos de
telephonelinestringobrigatóriopode ser nuloO número inteiro com código do país e DDD.
numberstringobrigatóriopode ser nuloNúmero local.
areaCodestringobrigatóriopode ser nuloDDD.
countryCodestringobrigatóriopode ser nuloCódigo do país.
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
delinquentbooleanobrigatórioSe o cliente tem pagamentos em atraso.
transactionsobject[]As cobranças mais recentes do cliente (só na leitura individual).
+14 campos de
transactionsidstringobrigatórioIdentificador público (tra_/trx_…)
feesintegerobrigatórioTotal de taxas, em centavos.
amountstringobrigatórioValor cobrado, em centavos (como texto).
imagesstring[]obrigatórioURLs das imagens dos itens.
methodstringobrigatórioMeio de pagamento.
statusstringobrigatórioStatus da cobrança.
currencystringobrigatórioMoeda (ISO 4217).
customIdstringobrigatóriopode ser nuloO seu id personalizado da cobrança;
nullem cobranças antigas.cardBrandstringobrigatóriopode ser nuloBandeira do cartão;
nullnos outros meios.createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
approvedAtstringobrigatóriopode ser nuloQuando a cobrança foi aprovada;
nullnos demais casos.customerIdstringobrigatóriopode ser nuloO comprador.
originalAmountstringobrigatórioValor antes dos descontos, em centavos (como texto).
subscriptionsobject[]As assinaturas mais recentes do cliente (só na leitura individual).
+27 campos de
subscriptionsidstringobrigatórioIdentificador público (subs_/sub_…)
typestringobrigatóriopode ser nuloTipo da assinatura (
recurring).itemsobject[]obrigatórioOs itens.
+13 campos de
itemsidstringobrigatórioIdentificador público (sit_/item_…)
namestringobrigatórioNome do item, vindo da variante.
imagesum de[]obrigatóriopode ser nuloImagens da variante;
nullquando não há.enabledbooleanobrigatórioSe o item é cobrado nos próximos ciclos.
currencystringobrigatórioMoeda (ISO 4217).
metadataobjectobrigatóriopode ser nuloOs seus metadados chave-valor do item;
nullquando não há.quantityintegerobrigatórioQuantidade.
createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
unitPriceintegerobrigatórioPreço unitário congelado da variante, em centavos.
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
descriptionstringobrigatóriopode ser nuloA sua nota sobre o item.
pricingSchemastringobrigatórioEsquema de preço da variante:
unit,tieredoupackage.externalReferencestringobrigatóriopode ser nuloO seu próprio identificador do item;
nullquando não há.
_linksobjectLinks para operações relacionadas, por ação (
self,create,update,delete,list…).methodstringobrigatóriopode ser nuloComo os ciclos são cobrados:
credit,pixoubillet.splitsobject[]obrigatóriopode ser nuloSplits de cada cobrança de ciclo;
nullquando não há.+8 campos de
splitsidstringobrigatórioIdentificador público (ssp_/split_…)
typestringobrigatóriopercentageouflat.valuenumberobrigatórioO percentual (0–100) ou o valor fixo, conforme
type.liablebooleanobrigatórioSe o recebedor arca com os chargebacks da fatia.
createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
recipientstringobrigatóriopode ser nuloA conta que recebe a fatia.
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
chargeProcessingFeebooleanobrigatórioSe o recebedor paga a taxa de processamento da fatia.
statusstringobrigatórioStatus:
active,trialing,pending,paused,pastdue,unpaidoucanceled.Valores:activetrialingpendingpausedpastdueunpaidcanceledbillingobjectobrigatórioPeriodicidade da cobrança e endereço do pagador.
+7 campos de
billingaddressobjectobrigatórioO endereço do pagador (usado no boleto de cada ciclo). Todos os campos
nullquando não há.+13 campos de
addresscitystringobrigatóriopode ser nuloCidade.
linestringobrigatóriopode ser nuloO endereço inteiro numa linha.
line1stringobrigatóriopode ser nuloPrimeira linha: logradouro e número.
line2stringobrigatóriopode ser nuloSegunda linha: bairro.
line3stringobrigatóriopode ser nuloTerceira linha: cidade, estado e CEP.
statestringobrigatóriopode ser nuloEstado (sigla de duas letras).
numberstringobrigatóriopode ser nuloNúmero.
streetstringobrigatóriopode ser nuloLogradouro.
countrystringobrigatóriopode ser nuloCódigo do país (ISO 3166-1).
districtstringobrigatóriopode ser nuloBairro.
postcodestringobrigatóriopode ser nuloCEP, só dígitos.
complementstringobrigatóriopode ser nuloComplemento (apartamento, sala, bloco…).
fingerprintstringobrigatóriopode ser nuloImpressão digital do endereço (deduplicação).
endDatestringobrigatóriopode ser nuloQuando a assinatura termina;
null= nunca.exactDayintegerobrigatóriopode ser nuloDia do mês em que é cobrada;
nullquando não é fixo.autoRenewbooleanobrigatórioSe a assinatura se renova sozinha no fim de cada período (
falsedepois de um cancelamento no fim do período).frequencystringobrigatóriopode ser nuloUnidade do intervalo de cobrança:
daily,weekly,monthlyouyearly.freeTrialDaysintegerobrigatóriopode ser nuloDuração do período de teste, em dias;
nullquando não há.frequencyCountintegerobrigatóriopode ser nuloQuantas unidades por ciclo.
callbackobjectobrigatóriopode ser nuloWebhook próprio;
nullquando não há.+2 campos de
callbackactivebooleanobrigatórioSe o webhook próprio está ativo.
webhookUrlstringobrigatórioURL que recebe os webhooks desta assinatura.
currencystringobrigatóriopode ser nuloMoeda (ISO 4217).
customerobjectobrigatórioO comprador.
+15 campos de
customeridstringobrigatóriopode ser nuloId do cliente (
cus_…).emailstringobrigatóriopode ser nuloEndereço de e-mail.
genderstringobrigatóriopode ser nuloGênero;
nullquando desconhecido.documentobjectobrigatóriopode ser nuloDocumento do comprador;
nullquando não há.+2 campos de
documenttypestringobrigatóriopode ser nuloTipo do documento.
numberstringobrigatóriopode ser nuloNúmero do documento.
lastNamestringobrigatóriopode ser nuloSobrenome.
metadataobjectobrigatóriopode ser nuloOs seus metadados chave-valor;
nullquando não há.availablebooleanobrigatóriopode ser nuloSe o cliente está ativo e pode ser cobrado.
birthdatestringobrigatóriopode ser nuloData de nascimento (
YYYY-MM-DD);nullquando desconhecida.createdAtstringobrigatóriopode ser nuloQuando o recurso foi criado (ISO 8601, UTC).
firstNamestringobrigatóriopode ser nuloNome.
telephoneobjectobrigatóriopode ser nuloTelefone do comprador, em partes;
nullquando não há.+4 campos de
telephonelinestringobrigatóriopode ser nuloO número inteiro com código do país e DDD.
numberstringobrigatóriopode ser nuloNúmero local.
areaCodestringobrigatóriopode ser nuloDDD.
countryCodestringobrigatóriopode ser nuloCódigo do país.
updatedAtstringobrigatóriopode ser nuloQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
delinquentbooleanobrigatóriopode ser nuloSe o cliente tem pagamentos em atraso.
additionalEmailsstring[]obrigatóriopode ser nuloOutros e-mails;
nullquando não há.externalReferencestringobrigatóriopode ser nuloO seu próprio identificador do cliente.
discountobjectobrigatóriopode ser nuloDesconto aplicado;
nullquando não há.+3 campos de
discounttypestringobrigatórioflatoupercentage.valuenumberobrigatórioO desconto.
percentageOfAmountnumberobrigatóriopode ser nuloO desconto como percentual do valor.
merchantobjectA conta dona do recurso (o vendedor de registro).
+3 campos de
merchantnamestringobrigatóriopode ser nuloNome fantasia da conta dona do recurso.
merchantIdstringobrigatóriopode ser nuloId público da conta dona do recurso (
bus_…).isSubAccountbooleanobrigatóriotruequando o recurso pertence a uma sub-conta operada por uma plataforma de marketplace.
metadataobjectobrigatóriopode ser nuloOs seus metadados chave-valor;
nullquando não há.shippingobjectobrigatóriopode ser nuloRetrato do frete, como enviado;
nullquando não há.spplitedbooleanobrigatórioSe as cobranças dos ciclos são divididas com outras contas (ver
splits). O nome mantém a grafia histórica.createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
discountsany[]obrigatóriopode ser nuloOs cupons aplicados;
nullquando não há.shippablebooleanobrigatórioSe a assinatura tem itens físicos para enviar.
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
canceledAtstringobrigatóriopode ser nuloQuando a assinatura foi encerrada;
nullenquanto está viva.geolocationobjectobrigatóriopode ser nuloSinais de dispositivo e localização do comprador, como enviados;
nullquando não há.cancellationobjectobrigatóriopode ser nuloPor que foi cancelada;
nullenquanto ninguém pediu o cancelamento.+3 campos de
cancellationreasonstringobrigatóriopode ser nuloO texto livre escrito por quem cancelou.
canceledBystringobrigatóriopode ser nuloseller(API ou painel),customer(portal) ouplatform(régua de cobrança, chargeback, estorno).Valores:sellercustomerplatformreasonCodestringobrigatóriopode ser nuloO motivo da lista;
nullnos cancelamentos antigos e nos da própria plataforma.Valores:pricenot_usingtechnical_issueswitched_providerother
currentCycleobjectobrigatóriopode ser nuloO ciclo de cobrança atual;
nullquando não há.+9 campos de
currentCycleidstringobrigatórioIdentificador público (scy_/cycle_…)
cycleintegerobrigatórioNúmero do ciclo (1 = o primeiro).
statusstringobrigatórioStatus do ciclo:
scheduled,processing,paid,failedoucanceled.dueDatestringobrigatórioQuando o ciclo é cobrado (ou vence).
endDatestringobrigatóriopode ser nuloQuando o ciclo termina;
nullenquanto aberto.billedAtstringobrigatóriopode ser nuloQuando o ciclo foi cobrado;
nullaté lá.createdAtstringobrigatórioQuando o recurso foi criado (ISO 8601, UTC).
startDatestringobrigatórioQuando o ciclo começa.
updatedAtstringobrigatórioQuando o recurso foi atualizado pela última vez (ISO 8601, UTC).
pixAutomaticobjectpode ser nuloSó na leitura individual;
nullquando a assinatura não é paga por Pix Automático.+8 campos de
pixAutomaticstatusstringobrigatóriopending(sendo criado) ·awaitingAuthorization(QR code exibido) ·active(debitado a cada ciclo) ·rejected(o pagador recusou ou revogou) ·ended. Depois derejected/endedos ciclos são cobrados por um QR code cada.Valores:pendingawaitingAuthorizationactiverejectedendedjourneystringobrigatóriopaymentOnApproval: o primeiro ciclo é pago junto com a autorização;onlyRecurrency: só a recorrência é autorizada.Valores:paymentOnApprovalonlyRecurrencyendReasonstringobrigatóriopode ser nuloPor que terminou;
nullenquanto ativo.qrCodeEmvstringobrigatóriopode ser nuloO QR code de autorização (copia e cola) — só enquanto
awaitingAuthorization.qrCodeUrlstringobrigatóriopode ser nuloURL da imagem do QR code de autorização — só enquanto
awaitingAuthorization.approvedAtstringobrigatóriopode ser nuloQuando o pagador autorizou;
nullaté lá.valueCentsintegerobrigatórioO valor fixo debitado a cada ciclo, em centavos.
firstChargeDatestringobrigatórioData do primeiro débito.
renewalTermsobjectobrigatóriopode ser nuloO que cada renovação cobra além dos itens, congelado na criação;
null= nada congelado (as renovações cobram itens menos cupons).+5 campos de
renewalTermsshippingbooleanobrigatórioSe o frete é cobrado em cada renovação.
discountMethodstringobrigatóriopode ser nuloO meio que concedeu o desconto no checkout;
nullquando nenhum.Valores:creditpixbilletmethodDiscountbooleanobrigatórioSe o desconto do meio de pagamento vale nas renovações cobradas por
discountMethod.shippingAmountintegerobrigatórioO frete cotado no checkout, em centavos (0 = sem frete).
discountPercentagenumberobrigatórioO desconto desse meio, como percentual (ex.: 5 = 5%).
externalReferencestringobrigatóriopode ser nuloO seu próprio identificador da assinatura;
nullquando não há.
additionalEmailsstring[]obrigatóriopode ser nuloOutros e-mails do comprador;
nullquando não há.externalReferencestringobrigatóriopode ser nuloO seu próprio identificador deste cliente;
nullquando não há.
401Não autenticado (credencial ausente ou inválida)
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório
403Sem permissão
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório
404Não encontrado
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório
500Erro interno do servidor
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório