Importar assinaturas

Este guia mostra como importar assinaturas que já existem em outro sistema de cobrança — ativas, em período de teste ou canceladas. Assinaturas ativas entram com o período real preservado, sem cobrar novamente o período atual. A Chargefy assume a cobrança a partir do próximo ciclo. Para assinaturas ativas ou em período de teste, você não precisa do cartão do cliente para importar. Sem cartão, a assinatura fica em send_invoice: no próximo ciclo a Chargefy gera uma fatura em aberto, e o cartão pode ser coletado depois. Assinaturas canceladas entram apenas como histórico e não geram cobrança.

A importação é acionada quando você envia backdate_start_date no POST /v1/subscriptions, sempre com proration_behavior: "none". Isso é o que diz à Chargefy: “não cobre o período atual, só assuma daqui pra frente”.

As três formas de importar

O estado da assinatura na origem	Campo que você envia	Como ela nasce na Chargefy
Ativa	`billing_cycle_anchor` (próxima cobrança)	`active`
Em período de teste	`trial_end` (fim do trial)	`trialing`
Já cancelada (histórico)	`canceled_at` (data do cancelamento)	`canceled` (registro inerte)

Passo a passo

Crie os customers

Cada assinatura precisa de um customer. Se você ainda não trouxe seus clientes, crie-os primeiro e guarde no seu banco a relação entre o ID da origem e o cus_* retornado.

curl -X POST "https://api.chargefy.io/v1/customers" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: cliente_legado_42" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@exemplo.com",
    "name": "Ana Souza",
    "metadata": {}
  }'

Crie os produtos e preços

A assinatura aponta para um price recorrente. Cadastre seus preços uma vez (ou envie price_data inline no item, se preferir não manter um catálogo).

curl -X POST "https://api.chargefy.io/v1/prices" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "prod_MR4Wsq1PN633CAEv",
    "currency": "brl",
    "unit_amount": 9900,
    "recurring": { "interval": "month" }
  }'

O preço precisa ter a mesma moeda e o mesmo ciclo da assinatura que você vai importar. Uma assinatura mensal em BRL só aceita um preço mensal em BRL.

Importe cada assinatura

Envie a assinatura com as datas reais do seu sistema. Use o id da assinatura na origem como Idempotency-Key: assim, se você repetir a importação, a mesma assinatura nunca é duplicada.

curl -X POST "https://api.chargefy.io/v1/subscriptions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: assinatura_legada_987" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_GHvNJie3UpSB8a68",
    "items": [{ "price": "price_rb78CHEQPo13Gahd" }],
    "backdate_start_date": "2026-06-16T18:00:00Z",
    "billing_cycle_anchor": "2026-07-16T18:00:00Z",
    "proration_behavior": "none",
    "metadata": {}
  }'

A resposta volta com a assinatura já active, latest_invoice em null (nenhuma cobrança foi feita) e o período preservado.Para os outros estados, troque billing_cycle_anchor pelo campo correspondente:

curl -X POST "https://api.chargefy.io/v1/subscriptions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: assinatura_legada_988" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_GHvNJie3UpSB8a68",
    "items": [{ "price": "price_rb78CHEQPo13Gahd" }],
    "backdate_start_date": "2026-06-26T18:00:00Z",
    "trial_end": "2026-07-10T18:00:00Z",
    "proration_behavior": "none"
  }'

curl -X POST "https://api.chargefy.io/v1/subscriptions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Idempotency-Key: assinatura_legada_989" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_GHvNJie3UpSB8a68",
    "items": [{ "price": "price_rb78CHEQPo13Gahd" }],
    "backdate_start_date": "2026-05-02T18:00:00Z",
    "canceled_at": "2026-06-21T18:00:00Z",
    "proration_behavior": "none"
  }'

Deixe a Chargefy assumir no próximo ciclo

Nada é cobrado no momento da importação. Na data que você informou como âncora (billing_cycle_anchor, ou o fim do trial), a Chargefy gera a primeira fatura do novo ciclo automaticamente:

Sem cartão (send_invoice): a fatura nasce em aberto e cobrável. A assinatura continua active. Envie o link de pagamento ao cliente ou colete um cartão antes da próxima cobrança.
Com cartão (charge_automatically): a Chargefy cobra automaticamente.

Assinaturas importadas como canceled são apenas histórico: não geram cobrança, job nem webhook.

De-para das datas

No seu sistema atual	Campo na importação	Vira na Chargefy
Início do período atual (já pago)	`backdate_start_date`	`current_period_start`, `start_date`
Próxima cobrança	`billing_cycle_anchor`	`current_period_end`, `next_billing_at`
Fim do trial (se em trial)	`trial_end`	`current_period_end`
Data do cancelamento (se cancelada)	`canceled_at`	`canceled_at`, `ended_at`
ID da assinatura na origem	`Idempotency-Key` + relação salva no seu banco	idempotência + correlação

Regras de validação

A importação recusa datas incoerentes com um erro 400 claro, sem criar nada:

Regra	Motivo
`backdate_start_date` deve estar no passado	É quando o período atual começou.
`billing_cycle_anchor` deve estar no futuro	É a próxima cobrança.
`trial_end` deve estar no futuro	O trial ainda está rodando.
`canceled_at` deve estar no passado	A assinatura já foi cancelada.
`proration_behavior` deve ser `none`	Confirma que o período atual não é cobrado de novo.

Boas práticas

Use o id da assinatura na origem como Idempotency-Key. A importação em lote pode ser repetida sem criar duplicatas. Veja requisições idempotentes.
Ao receber a resposta, guarde no seu banco a relação entre o ID da origem e o sub_* retornado pela Chargefy.
Importe com antecedência: evite importar muito perto da próxima cobrança, para ter tempo de coletar o cartão antes do primeiro ciclo na Chargefy.

Próximos passos

Criar assinatura

Contrato completo do POST /v1/subscriptions, incluindo os campos de importação.

Requisições idempotentes

Como o header Idempotency-Key torna a importação em lote segura.

Criar customer

Traga seus clientes antes de importar as assinaturas.

Criar preço

Cadastre os preços recorrentes que as assinaturas vão usar.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Importar assinaturas

As três formas de importar

Passo a passo

De-para das datas

Regras de validação

Boas práticas

Próximos passos

Criar assinatura

Requisições idempotentes

Criar customer

Criar preço

​As três formas de importar

​Passo a passo

​De-para das datas

​Regras de validação

​Boas práticas

​Próximos passos

Criar assinatura

Requisições idempotentes

Criar customer

Criar preço

As três formas de importar

Passo a passo

De-para das datas

Regras de validação

Boas práticas

Próximos passos