Referência

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
`retryPolicy`	Não	Política de retentativa em caso de falha de cobrança (veja abaixo)

retryPolicy

Controla o comportamento automático de retentativas quando uma cobrança do ciclo falha (ex.: cartão sem saldo). Se não informado, os padrões são aplicados.

Campo	Tipo	Padrão	Min	Max	Descrição
`maxRetry`	integer	`3`	`1`	`10`	Número máximo de tentativas de cobrança antes do cancelamento automático da assinatura
`retryEvery`	integer	`1`	`1`	`30`	Dias entre cada tentativa

Após esgotar todas as tentativas sem sucesso, a assinatura é automaticamente cancelada com cancelledDueTo: "max_payment_retries_exceeded" e o evento subscription.cancelled é disparado. 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"],
  "retryPolicy": {
    "maxRetry": 5,
    "retryEvery": 3
  }
}

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.

Objeto de assinatura ativa

Após ativação, os endpoints de assinatura (GET /subscriptions/get, GET /subscriptions/list) retornam o objeto completo incluindo retryPolicy:

{
  "data": {
    "id": "subs_abc123xyz",
    "customerId": "cust_abc123xyz",
    "amount": 10000,
    "status": "ACTIVE",
    "method": "CARD",
    "coupons": [],
    "devMode": false,
    "trialDays": null,
    "trialEndsAt": null,
    "retryPolicy": {
      "maxRetry": 5,
      "retryEvery": 3
    },
    "createdAt": "2024-11-04T18:38:28.573Z",
    "updatedAt": "2024-11-04T18:38:28.573Z"
  },
  "success": true,
  "error": null
}

Campo	Tipo	Descrição
`retryPolicy.maxRetry`	integer	Tentativas máximas antes do cancelamento automático
`retryPolicy.retryEvery`	integer	Dias entre cada tentativa

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

Criação do produto: defina trialDays (inteiro de 1 a 90) junto com cycle.
Checkout: o cliente insere o cartão normalmente, mas o valor cobrado é R$ 0,00. O cartão é apenas tokenizado para uso futuro.
Assinatura ativa imediatamente: a assinatura é criada com status: ACTIVE e os campos trialDays e trialEndsAt preenchidos.
Fim do trial: na data trialEndsAt, a primeira cobrança pelo valor integral é processada automaticamente.
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

Introdução

Cobrar com Checkout

Links de pagamento

Clientes

Checkout Transparente

Cupons

Produtos

Webhooks

Assinaturas

Saques

PIX

Loja

Public MRR

Parâmetros

retryPolicy

Resposta

Objeto de assinatura ativa

Ciclo de cobrança

Status

Período de teste gratuito (Free Trial)

Como funciona

Exemplo de produto com trial

Objeto da assinatura com trial

Webhook de início de trial

Cancelamento durante o trial

Gerenciando assinaturas ativas

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

Segurança

​Parâmetros

​retryPolicy

​Resposta

​Objeto de assinatura ativa

​Ciclo de cobrança

​Status

​Período de teste gratuito (Free Trial)

​Como funciona

​Exemplo de produto com trial

​Objeto da assinatura com trial

​Webhook de início de trial

​Cancelamento durante o trial

​Gerenciando assinaturas ativas

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

​Segurança

Parâmetros

retryPolicy

Resposta

Objeto de assinatura ativa

Ciclo de cobrança

Status

Período de teste gratuito (Free Trial)

Como funciona

Exemplo de produto com trial

Objeto da assinatura com trial

Webhook de início de trial

Cancelamento durante o trial

Gerenciando assinaturas ativas

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

Segurança