Cria uma assinatura
/v1/subscriptionsCria uma assinatura
Só pelo catálogo (Selectwin-strict): o modelo de preço/cobrança vem da variante do produto, nunca do pedido — a variante precisa ter pricingType=recurring (senão 422). Assinaturas medidas/por faixa usam o mesmo formato de pedido; o comportamento vem da variante. Uma assinatura com freeTrial nasce trialing e NÃO é cobrada até o fim do período de teste.
Autentique com o header SelectKey: a chave sk_test_ opera no sandbox, a sk_live_ em produção. Como autenticar.
Corpo da requisição
namestringNome da assinatura, para a sua referência.
itemsobject[]obrigatórioOs itens (1 a 20), cada um de uma variante recorrente.
+5 campos de
itemsmetadataobjectObjeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
quantityintegerQuantidade.
variantIdstringobrigatórioUma variante recorrente do seu catálogo — o preço e a periodicidade vêm dela.
descriptionstringA sua nota sobre o item (não muda o preço).
externalReferencestringO seu próprio identificador do item.
splitsobject[]Splits de cada cobrança de ciclo (até 20).
+3 campos de
splitstypestringobrigatóriopercentageouflat.Valores:percentageflatvaluenumberobrigatórioO percentual (0–100) ou o valor fixo, conforme
type.recipientstringobrigatórioA conta que recebe a fatia (
bus_…).
billingobjectPeriodicidade da cobrança e endereço do pagador. O valor recorrente nunca fica aqui: vem das variantes do catálogo.
+7 campos de
billingaddressobjectEndereço do pagador: um endereço salvo (
id) ou os campos inline (postcode,streetenumberpelo menos). Obrigatório no boleto; guardado como retrato nos outros meios.+9 campos de
addressidstringUm endereço salvo do comprador.
citystringCidade.
statestringEstado (sigla de duas letras, ex.:
SP).numberstringNúmero.
streetstringLogradouro.
countrystringCódigo do país (ISO 3166-1, ex.:
BR).districtstringBairro.
postcodestringCEP, 8 dígitos — o hífen é aceito.
complementstringComplemento (apartamento, sala, bloco…).
endDatestringQuando a assinatura termina (
YYYY-MM-DD); padrão nunca.exactDayintegerCobrar neste dia do mês.
freeTrialobjectPeríodo de teste: a assinatura nasce
trialinge nada é cobrado até o teste acabar.+2 campos de
freeTrialdaysintegerobrigatórioDuração do teste, em dias.
enabledbooleanobrigatórioSe há período de teste.
frequencystringUnidade do intervalo de cobrança.
Valores:dailyweeklymonthlyyearlystartDatestringQuando a assinatura começa (
YYYY-MM-DD); padrão hoje.frequencyCountintegerQuantas unidades por ciclo (ex.:
monthly× 3 = trimestral).
endDateanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).paymentobjectobrigatórioComo cada ciclo é cobrado. Regra: Com
method=credit,cardé obrigatório (card.idde um cartão salvo, ou cartão completo inline: holderName, expirationMonth, expirationYear, numbering, securityCode).+5 campos de
paymentpixobjectOpções do Pix.
+2 campos de
pixautomaticbooleanPix Automático: o pagador autoriza uma vez (um QR code) e cada ciclo é debitado — sem QR por ciclo. Só valor fixo.
expiresInMinutesintegerPor quanto tempo o QR code de cada ciclo fica pagável, em minutos.
cardobjectO cartão de uma cobrança no crédito: um cartão salvo (
id), um token emitido no navegador do comprador (token), ou o cartão completo inline. O cartão inline é tokenizado antes da cobrança e nunca guardado.+7 campos de
cardidstringUm cartão salvo do cliente.
tokenstringToken de cartão de uso único emitido no navegador do comprador por
POST /v1/tokenization/tokens(válido por uma hora).numberingstringNúmero do cartão (PAN), só dígitos — espaços e traços são removidos. Tokenizado ao chegar, nunca guardado.
holderNamestringNome impresso no cartão (só no cartão inline).
securityCodestringCódigo de segurança do cartão (CVV/CVC), 3 ou 4 dígitos.
expirationYearobjectAno de validade, 4 dígitos — 2 dígitos são aceitos (só no cartão inline).
expirationMonthintegerMês de validade, 1 a 12 (só no cartão inline).
billetobjectOpções do boleto.
+1 campo de
billetexpiresInDaysintegerDias até o vencimento do boleto de cada ciclo.
methodstringcreditcobra o cartão salvo a cada ciclo;pixebilletemitem um QR code / boleto novo a cada ciclo para o comprador pagar.Valores:creditpixbilletinstallmentsintegerParcelas de cada cobrança de ciclo (só cartão).
callbackobjectWebhook só desta assinatura.
+2 campos de
callbackactivebooleanSe o webhook próprio está ativo.
webhookUrlstring (uri)obrigatórioURL que recebe os webhooks desta assinatura.
customerobjectobrigatórioO comprador: um cliente salvo (
id), ou os dados inline (firstName,lastNameeemail), que é encontrado ou criado. Regra: Obrigatório informarid(cliente salvo) OU os dados inlinefirstName+lastName+email(a API faz find-or-create). Enviarcustomer: {}é rejeitado.+12 campos de
customeridstringUm cliente salvo. Sem ele, o comprador é encontrado ou criado pelos campos inline.
emailstring (email)Endereço de e-mail (obrigatório para criar o comprador inline).
genderstringGênero:
male,femaleouother.Valores:malefemaleotherdocumentobjectDocumento do comprador.
+2 campos de
documenttypestringobrigatórioTipo do documento:
cpf,cnpjoupassport.Valores:cpfcnpjpassportnumberstringobrigatórioNúmero do documento: dígitos do CPF ou CNPJ, ou o número do passaporte.
fullNamestringNome completo, como alternativa a nome + sobrenome.
lastNamestringSobrenome (obrigatório para criar o comprador inline).
metadataobjectObjeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
birthdatestringData de nascimento,
YYYY-MM-DD.firstNamestringNome (obrigatório para criar o comprador inline).
telephoneobjectTelefone do comprador, em partes;
lineé o número inteiro.+4 campos de
telephonelinestringO número inteiro com código do país e DDD (ex.:
5511987654321) — o único telefone que chega ao provedor de pagamento (boleto, 3DS).numberstringNúmero local, só dígitos.
areaCodestringDDD (ex.:
11).countryCodestringCódigo do país (ex.:
55).
additionalEmailsstring (email)[]Outros e-mails do comprador (até 20).
externalReferencestringO seu próprio identificador do comprador.
exactDayanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).metadataobjectObjeto JSON livre — no máximo 50 chaves, chaves de até 40 caracteres, cada valor com até 500 caracteres (o JSON dele, quando não é texto), o objeto inteiro com até 8192 bytes em JSON.
shippingobjectRetrato do frete (JSON livre), guardado e devolvido como veio.
autoRenewbooleanSe a assinatura se renova sozinha no fim de cada período (padrão
true).discountsobject[]Códigos de cupom (até 20): um cupom
recurringé reaplicado a cada ciclo; umfirstCharge, só no primeiro.+1 campo de
discountscodestringobrigatórioUm código de cupom do seu catálogo.
freeTrialanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).frequencyanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).sessionIdstringA sessão de checkout de que a assinatura veio, se houver.
startDateanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).onBehalfOfstringMarketplace: criar a assinatura NA sub-conta sua indicada — ela passa a ser a vendedora de registro e a sua taxa de plataforma é recolhida em cada ciclo.
descriptionstringDescrição.
geolocationobjectSinais de dispositivo e localização do comprador (JSON livre), para a análise de fraude.
integrationIdstringA integração de que a assinatura veio, se houver.
frequencyCountanyNão é mais aceito na raiz: mande dentro do bloco
billing(uma requisição com ele aqui é recusada).externalReferencestringO seu próprio identificador da assinatura, devolvido como veio.
Respostas
201Criado
idstringobrigató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á.
400Requisição inválida (validação)
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório
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
409Conflito (idempotência ou estado)
errorobjectobrigatório+8 campos de
errorcodestringobrigatórioparamsobject[]statusstringobrigatóriodetailsstringmessagestringobrigatóriocategorystringobrigatórioValores:validationauthenticationauthorizationpaymentclientserverrate_limitpendingresourcestringobrigatóriostatusCodeintegerobrigatório
422Regra de negócio impede o processamento
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