POST /api/v1/subscriptions/:id/invoices - Chargefy

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

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`

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

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"
  }'

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

{
  "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"
}