Referência

Crie checkouts de assinatura e gerencie as existentes.

Modelo mental

Uma assinatura na AbacatePay tem três fases distintas:

Checkout (cliente paga) → Assinatura ACTIVE → Cobranças automáticas a cada ciclo

O POST /subscriptions/create não cria uma assinatura diretamente — ele cria um checkout de assinatura. A assinatura em si (com id: subs_...) só existe após o cliente concluir o pagamento. Esse detalhe muda como você lida com os webhooks: ouça subscription.completed para confirmar que a assinatura está ativa, não apenas que o checkout foi criado.

Criar checkout

Inicia o fluxo de assinatura.

Cancelar

Cancela imediatamente, sem cobranças futuras.

Alterar plano

Muda o produto; novo valor no próximo ciclo.

---

Toda assinatura antes de ser iniciada, o seu cliente deve passar pelo Checkout.

A diferença é que um checkout de assinatura aceita só um produto, e esse produto precisa ter ciclo (frequency) definido na loja.

Quando o pagamento é realizado, a assinatura se torna ativa.

Parâmetros

O POST /subscriptions/create usa os mesmos parâmetros do Checkout:

Parâmetro	Obrigatório	Descrição
items	Sim	Lista com exatamente um item (id e quantity); o produto deve ter sido criado com ciclo de assinatura
customerId	Não	ID do cliente já cadastrado
externalId	Não	ID da assinatura no seu sistema
returnUrl	Não	URL de retorno ao clicar em “Voltar”
completionUrl	Não	URL após pagamento concluído
metadata	Não	Metadados livres
coupons	Não	Lista de cupons
methods	Não	Lista de métodos (PIX, CARD). Padrão: ["CARD"] para assinaturas

Exemplo (cada item só precisa de id e quantity; o ciclo vem do produto):

{
  "items": [
    {
      "id": "prod-1234",
      "quantity": 1
    }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "subs-123",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["CARD"]
}

Resposta

Create e list retornam o mesmo formato do Checkout (id, url, amount, items, status, etc.).

Resposta:

{
  "data": {
    "id": "bill_abc123xyz",
    "externalId": "subs-123",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "paidAmount": null,
    "items": [
      {
        "id": "prod_456",
        "quantity": 1
      }
    ],
    "status": "PENDING",
    "coupons": [],
    "devMode": false,
    "customerId": "cust_abc123xyz",
    "returnUrl": "https://seusite.com/voltar",
    "completionUrl": "https://seusite.com/sucesso",
    "receiptUrl": null,
    "metadata": {},
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}

Use a url retornada para levar o cliente ao checkout e concluir o pagamento.

Ciclo de cobrança

Definido no produto ao criar na loja. Valores: WEEKLY, MONTHLY, SEMIANNUALLY, ANNUALLY.

Status

Mesmos do Checkout: PENDING, EXPIRED, CANCELLED, PAID, REFUNDED.

Período de teste gratuito (Free Trial)

Configure um período de teste no produto com o campo trialDays ao criar o produto. Durante o trial, o cliente não é cobrado — a primeira cobrança ocorre somente ao final do período.

Como funciona

1. Criação do produto: defina trialDays (inteiro de 1 a 90) junto com cycle.
2. Checkout: o cliente insere o cartão normalmente, mas o valor cobrado é R$ 0,00. O cartão é apenas tokenizado para uso futuro.
3. Assinatura ativa imediatamente: a assinatura é criada com status: ACTIVE e os campos trialDays e trialEndsAt preenchidos.
4. Fim do trial: na data trialEndsAt, a primeira cobrança pelo valor integral é processada automaticamente.
5. Renovações: seguem o ciclo normal do produto a partir do fim do trial.

Exemplo de produto com trial

POST /products/create
{
  "externalId": "plano-pro-trial",
  "name": "Plano Pro — 7 dias grátis",
  "price": 4990,
  "currency": "BRL",
  "cycle": "MONTHLY",
  "trialDays": 7
}

Objeto da assinatura com trial

Após a ativação, a assinatura expõe trialDays e trialEndsAt:

{
  "data": {
    "id": "subs_abc123xyz",
    "customerId": "cust_abc123xyz",
    "amount": 4990,
    "status": "ACTIVE",
    "method": "CARD",
    "coupons": [],
    "devMode": false,
    "trialDays": 7,
    "trialEndsAt": "2024-11-11T23:59:59.999Z",
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}

Campo	Tipo	Descrição
trialDays	integer | null	Duração do período de teste em dias; null se não houver trial
trialEndsAt	string | null	Data/hora (ISO 8601) em que o trial termina; null se não houver trial

Webhook de início de trial

Quando uma assinatura com trial é criada, o evento subscription.trial_started é disparado:

{
  "event": "subscription.trial_started",
  "apiVersion": 2,
  "data": {
    "subscription": {
      "id": "subs_abc123xyz",
      "amount": 4990,
      "status": "ACTIVE",
      "method": "CARD",
      "trialDays": 7,
      "trialEndsAt": "2024-11-11T23:59:59.999Z",
      "createdAt": "2024-11-04T18:38:28.573Z"
    }
  }
}

Cancelamento durante o trial

Cancelar uma assinatura em período de trial tem o mesmo comportamento que cancelar uma assinatura normal: o cancelamento é imediato e nenhuma cobrança futura é processada. Veja Cancelar assinatura.

Gerenciando assinaturas ativas

Após uma assinatura ser criada e ativada, você pode gerenciá-la com os seguintes endpoints:

Endpoint	Descrição
Cancelar	Cancela a assinatura imediatamente e interrompe cobranças futuras
Alterar plano	Troca o produto principal; novo valor começa no próximo ciclo
Registrar uso	Adiciona ou remove unidades de produtos pay-as-you-go para cobrança no próximo ciclo

Produtos de uso (pay-as-you-go)

Além do produto principal (com ciclo), uma assinatura pode acumular cobranças variáveis via Registrar uso. O produto referenciado precisa ser um produto sem ciclo — ele representa um item cobrado por unidade consumida (ex: chamadas de API, SMS, créditos).

Segurança

• Requisições autenticadas via Bearer Token
• Abusos podem levar à suspensão da conta conforme os termos de uso