> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/subscriptions/:id/invoices

> Cria uma cobrança avulsa (invoice) para uma assinatura ativa

Gera uma cobrança extra para uma assinatura ativa, fora do ciclo de recorrência padrão. A cobrança é criada no gateway de pagamentos e registrada na base de dados.

## Autenticação

> [!NOTE]
>
> Requer um token de acesso válido (`CHARGEFY_ACCESS_TOKEN`) no header `Authorization`. Escopos necessários: `web:write` ou `subscriptions:write`.

## Parâmetros de Path

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `id` | `string` | Sim | ID da assinatura |

## Parâmetros do Body

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `amount` | `number` | Sim | Valor em centavos (ex: `9900` para R\$ 99,00). Deve ser positivo |
| `due_date` | `string` | Sim | Data de vencimento no formato ISO (`YYYY-MM-DD`) |
| `description` | `string` | Não | Descrição da cobrança |
| `expiration_date` | `string` | Não | Data de expiração da cobrança no formato ISO (`YYYY-MM-DD`) |
| `no_fees_installments` | `boolean` | Não | Se `true`, parcelas sem juros. Padrão: `false` |

> [!WARNING]
>
> Somente assinaturas com `status: active`, `trialing`, `unpaid` ou `past_due` e com identificador de recorrência no gateway (`zoop_subscription_id`) configurado podem receber cobranças avulsas.

## Campos da Resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `string` | ID da invoice criada |
| `zoop_invoice_id` | `string` | ID da invoice no gateway (campo da API) |
| `subscription_id` | `string` | ID da assinatura |
| `organization_id` | `string` | ID da organização |
| `amount` | `number` | Valor em centavos |
| `currency` | `string` | Moeda (`BRL`) |
| `description` | `string \| null` | Descrição da cobrança |
| `due_date` | `string` | Data de vencimento |
| `expiration_date` | `string \| null` | Data de expiração |
| `payment_method` | `string` | Método de pagamento (`credit`) |
| `status` | `string` | Status da invoice: `pending`, `paid`, `voided`, `failed` |
| `no_fees_installments` | `boolean` | Parcelas sem juros |
| `paid_at` | `datetime \| null` | Data em que a invoice foi paga |
| `created_at` | `datetime` | Data de criação |
| `modified_at` | `datetime` | Data da última modificação |

## Exemplo de Requisição

```bash cURL theme={null}
curl -X POST "https://api.chargefy.io/api/v1/subscriptions/sub_1a2b3c4d/invoices" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "due_date": "2026-04-10",
    "description": "Taxa de setup"
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const invoice = await chargefy.subscriptions.createInvoice('sub_1a2b3c4d', {
  amount: 9900,
  due_date: '2026-04-10',
  description: 'Taxa de setup',
});
```

## Exemplo de Resposta

```json theme={null}
{
  "id": "inv_abc123",
  "zoop_invoice_id": "gw_inv_xyz789",
  "subscription_id": "sub_1a2b3c4d",
  "organization_id": "org_def456",
  "amount": 9900,
  "currency": "BRL",
  "description": "Taxa de setup",
  "due_date": "2026-04-10",
  "expiration_date": null,
  "payment_method": "credit",
  "status": "pending",
  "no_fees_installments": false,
  "created_at": "2026-03-20T10:00:00Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.