Skip to main content

​
Visão geral

Use este endpoint para criar uma assinatura recorrente vinculada a um cliente e a um produto. A Avantti Finance gerencia automaticamente a cobrança periódica, gerando transações a cada novo ciclo de cobrança.

​
Endpoint

curl -X POST https://api.avanttifinance.com/v1/subscriptions \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_8f72a1b3c4d5",
    "product_id": "prod_8f72a1b3c4d5",
    "billing_interval": "monthly",
    "payment_method": "card"
  }'

​
Parâmetros do corpo

​
customer_id
string
required
Identificador do cliente que será cobrado pela assinatura.
​
product_id
string
required
Identificador do produto vinculado à assinatura, que define o valor cobrado a cada ciclo.
​
billing_interval
string
required
Intervalo de cobrança da assinatura. Valores aceitos: weekly, monthly, quarterly, yearly.
​
payment_method
string
required
Método de pagamento utilizado nas cobranças recorrentes. Valores aceitos: card, pix, boleto.
​
trial_days
integer
Número de dias de teste gratuito antes da primeira cobrança. Padrão: 0.
​
metadata
object
Conjunto de pares chave-valor para armazenar informações adicionais sobre a assinatura.

​
Resposta

​
id
string
Identificador único da assinatura, no formato sub_xxxxxxxxxxxx.
​
customer_id
string
Identificador do cliente vinculado à assinatura.
​
product_id
string
Identificador do produto vinculado à assinatura.
​
status
string
Status atual da assinatura. Valores possíveis: trialing, active, past_due, canceled.
​
billing_interval
string
Intervalo de cobrança da assinatura.
​
current_period_end
string
Data e hora em que o ciclo de cobrança atual termina, no formato ISO 8601.
​
created_at
string
Data e hora de criação da assinatura, no formato ISO 8601.

​
Exemplo de resposta

{
  "id": "sub_8f72a1b3c4d5",
  "customer_id": "cus_8f72a1b3c4d5",
  "product_id": "prod_8f72a1b3c4d5",
  "status": "active",
  "billing_interval": "monthly",
  "current_period_end": "2025-02-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z"
}
Configure um endpoint de webhook para o evento subscription.charge_failed para ser notificado quando uma cobrança recorrente falhar.

​
Erros comuns

Código HTTPSignificado
400Dados inválidos ou campos obrigatórios ausentes
401Token de autenticação inválido ou ausente
404Cliente ou produto não encontrado
422Método de pagamento incompatível com o intervalo de cobrança

​
Próximos passos

Listar assinaturas

Consulte todas as assinaturas e seus status.

Cancelar assinatura

Cancele uma assinatura ativa.