> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avanttifinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Assinatura

> Crie uma assinatura recorrente para um cliente

## Visão geral

Use este endpoint para criar uma assinatura recorrente vinculada a um cliente e a um produto. A Avantti Finance gerencia automaticamente a cobrança periódica, gerando transações a cada novo ciclo de cobrança.

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.avanttifinance.com/v1/subscriptions \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "customer_id": "cus_8f72a1b3c4d5",
      "product_id": "prod_8f72a1b3c4d5",
      "billing_interval": "monthly",
      "payment_method": "card"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.avanttifinance.com/v1/subscriptions", {
    method: "POST",
    headers: {
      "Authorization": \`Bearer \${accessToken}\`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      customer_id: "cus_8f72a1b3c4d5",
      product_id: "prod_8f72a1b3c4d5",
      billing_interval: "monthly",
      payment_method: "card"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.avanttifinance.com/v1/subscriptions"
  headers = {
      "Authorization": f"Bearer {access_token}",
      "Content-Type": "application/json"
  }
  payload = {
      "customer_id": "cus_8f72a1b3c4d5",
      "product_id": "prod_8f72a1b3c4d5",
      "billing_interval": "monthly",
      "payment_method": "card"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

## Parâmetros do corpo

<ParamField body="customer_id" type="string" required>
  Identificador do cliente que será cobrado pela assinatura.
</ParamField>

<ParamField body="product_id" type="string" required>
  Identificador do produto vinculado à assinatura, que define o valor cobrado a cada ciclo.
</ParamField>

<ParamField body="billing_interval" type="string" required>
  Intervalo de cobrança da assinatura. Valores aceitos: `weekly`, `monthly`, `quarterly`, `yearly`.
</ParamField>

<ParamField body="payment_method" type="string" required>
  Método de pagamento utilizado nas cobranças recorrentes. Valores aceitos: `card`, `pix`, `boleto`.
</ParamField>

<ParamField body="trial_days" type="integer">
  Número de dias de teste gratuito antes da primeira cobrança. Padrão: `0`.
</ParamField>

<ParamField body="metadata" type="object">
  Conjunto de pares chave-valor para armazenar informações adicionais sobre a assinatura.
</ParamField>

## Resposta

<ResponseField name="id" type="string">
  Identificador único da assinatura, no formato `sub_xxxxxxxxxxxx`.
</ResponseField>

<ResponseField name="customer_id" type="string">
  Identificador do cliente vinculado à assinatura.
</ResponseField>

<ResponseField name="product_id" type="string">
  Identificador do produto vinculado à assinatura.
</ResponseField>

<ResponseField name="status" type="string">
  Status atual da assinatura. Valores possíveis: `trialing`, `active`, `past_due`, `canceled`.
</ResponseField>

<ResponseField name="billing_interval" type="string">
  Intervalo de cobrança da assinatura.
</ResponseField>

<ResponseField name="current_period_end" type="string">
  Data e hora em que o ciclo de cobrança atual termina, no formato ISO 8601.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data e hora de criação da assinatura, no formato ISO 8601.
</ResponseField>

### Exemplo de resposta

```json theme={null}
{
  "id": "sub_8f72a1b3c4d5",
  "customer_id": "cus_8f72a1b3c4d5",
  "product_id": "prod_8f72a1b3c4d5",
  "status": "active",
  "billing_interval": "monthly",
  "current_period_end": "2025-02-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z"
}
```

<Tip>
  Configure um endpoint de webhook para o evento `subscription.charge_failed` para ser notificado quando uma cobrança recorrente falhar.
</Tip>

## Erros comuns

| Código HTTP | Significado                                                  |
| ----------- | ------------------------------------------------------------ |
| 400         | Dados inválidos ou campos obrigatórios ausentes              |
| 401         | Token de autenticação inválido ou ausente                    |
| 404         | Cliente ou produto não encontrado                            |
| 422         | Método de pagamento incompatível com o intervalo de cobrança |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Listar assinaturas" icon="list" href="/listar-filtrar-1">
    Consulte todas as assinaturas e seus status.
  </Card>

  <Card title="Cancelar assinatura" icon="ban" href="/cancelar">
    Cancele uma assinatura ativa.
  </Card>
</CardGroup>