> ## Documentation Index > Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt > Use this file to discover all available pages before exploring further. # Referência > Crie checkouts de assinatura e gerencie as existentes. Toda assinatura antes de ser iniciada, o seu cliente deve passar pelo [Checkout](/pages/payment/reference). 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): ```json theme={null} { "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:** ```json theme={null} { "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](/pages/products/create). Durante o trial, o cliente não é cobrado — a primeira cobrança ocorre somente ao final do período. ### Como funciona 1. **Criação do produto**: defina `trialDays` (inteiro de 1 a 90) junto com `cycle`. 2. **Checkout**: o cliente insere o cartão normalmente, mas o valor cobrado é **R\$ 0,00**. O cartão é apenas tokenizado para uso futuro. 3. **Assinatura ativa imediatamente**: a assinatura é criada com `status: ACTIVE` e os campos `trialDays` e `trialEndsAt` preenchidos. 4. **Fim do trial**: na data `trialEndsAt`, a primeira cobrança pelo valor integral é processada automaticamente. 5. **Renovações**: seguem o ciclo normal do produto a partir do fim do trial. ### Exemplo de produto com trial ```json theme={null} 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`: ```json theme={null} { "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: ```json theme={null} { "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](/pages/subscriptions/cancel). ## Gerenciando assinaturas ativas Após uma assinatura ser criada e ativada, você pode gerenciá-la com os seguintes endpoints: | Endpoint | Descrição | | -------------------------------------------------- | ------------------------------------------------------------------------------------ | | [Cancelar](/pages/subscriptions/cancel) | Cancela a assinatura imediatamente e interrompe cobranças futuras | | [Alterar plano](/pages/subscriptions/change-plan) | Troca o produto principal; novo valor começa no próximo ciclo | | [Registrar uso](/pages/subscriptions/record-usage) | 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](/pages/subscriptions/record-usage). 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](https://abacatepay.com/termos)