Referência

Crie checkouts de assinatura e gerencie as existentes.

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: MONTHLY, YEARLY, WEEKLY.

Status

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

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