Referência

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

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

Modelo mental

Criar checkout

Cancelar

Alterar plano

Parâmetros

Resposta

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

​Modelo mental

Criar checkout

Cancelar

Alterar plano

​Parâmetros

​Resposta

​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

Modelo mental

Parâmetros

Resposta

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