Crie uma assinatura

Crie uma assinatura para que o Asaas gere cobranças recorrentes conforme a periodicidade configurada.

Cada cobrança gerada possui seu próprio ID, status e ciclo financeiro.

Antes de começar

Antes de criar a assinatura:

• cadastre o cliente e armazene seu ID;
• defina a forma de pagamento;
• defina o valor e a periodicidade;
• escolha a data do primeiro vencimento.

Caso utilize cartão de crédito, consulte Criando assinatura com cartão de crédito.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Cadastrar ou localizar o cliente"] --> B["Definir a recorrência"]
    B --> C["Criar a assinatura"]
    C --> D["Armazenar o ID"]
    D --> E["Asaas gera as cobranças"]
    E --> F["Receber os Webhooks"]
    F --> G["Atualizar a aplicação"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Crie a assinatura

Envie uma requisição para:

POST /v3/subscriptions

Exemplo:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "BOLETO",
  "nextDueDate": "2027-01-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "description": "Assinatura Plano Pró"
}

Nesse exemplo:

• customer identifica o cliente;
• billingType define a forma de pagamento;
• nextDueDate define o primeiro vencimento;
• value define o valor da recorrência;
• cycle define a periodicidade.

As próximas cobranças serão geradas automaticamente conforme cycle.

Consulte o endpoint Criar nova assinatura.

2. Armazene o ID da assinatura

Após a criação, a API retorna o identificador da assinatura.

Exemplo:

sub_VXJBYgP2u0eO

Armazene esse ID. Ele será utilizado para consultar, atualizar ou remover a assinatura e recuperar suas cobranças.

Resultado esperado

A assinatura estará criada e pronta para gerar cobranças conforme a recorrência configurada.

A criação da assinatura não confirma nenhum pagamento.

3. Acompanhe a assinatura e as cobranças por Webhook

Prefira Webhooks para manter sua aplicação sincronizada com o Asaas.

Utilize os eventos de assinaturas para acompanhar alterações no ciclo de vida da assinatura, como criação, atualização, inativação e remoção.

Consulte os Eventos para assinaturas.

Utilize os eventos de cobranças para acompanhar as cobranças geradas pela recorrência e seus respectivos pagamentos.

Quando uma nova cobrança for criada, sua aplicação poderá receber:

PAYMENT_CREATED

O objeto da cobrança possui o campo subscription, que identifica a assinatura de origem.

Consulte os Eventos para cobranças.

4. Consulte as cobranças quando necessário

Para recuperar as cobranças já geradas pela assinatura, utilize:

GET /v3/subscriptions/{id}/payments

Consulte o endpoint Listar cobranças de uma assinatura.

A listagem retorna apenas cobranças que já foram geradas. Cobranças futuras ainda não criadas não aparecem no resultado.

Ao atualizar uma assinatura

As alterações realizadas na assinatura afetam as próximas cobranças por padrão.

Para alterar uma assinatura, utilize:

PUT /v3/subscriptions/{id}

Quando precisar aplicar alterações suportadas também às cobranças pendentes já geradas, envie:

{
  "updatePendingPayments": true
}

Cobranças já criadas não são alteradas por padrão.

Consulte o endpoint Atualizar assinatura existente.

Próximos passos

• Acompanhe os eventos de assinaturas
• Acompanhe os eventos de cobranças
• Liste as cobranças de uma assinatura
• Atualize uma assinatura
• Consulte os Limites da API
• Consulte o FAQ de Assinaturas