Skip to main content
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âmetroObrigatórioDescrição
itemsSimLista com exatamente um item (id e quantity); o produto deve ter sido criado com ciclo de assinatura
customerIdNãoID do cliente já cadastrado
externalIdNãoID da assinatura no seu sistema
returnUrlNãoURL de retorno ao clicar em “Voltar”
completionUrlNãoURL após pagamento concluído
metadataNãoMetadados livres
couponsNãoLista de cupons
methodsNãoLista 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
}
CampoTipoDescrição
trialDaysinteger | nullDuração do período de teste em dias; null se não houver trial
trialEndsAtstring | nullData/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:
EndpointDescrição
CancelarCancela a assinatura imediatamente e interrompe cobranças futuras
Alterar planoTroca o produto principal; novo valor começa no próximo ciclo
Registrar usoAdiciona 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