Skip to main content
Este guia mostra, passo a passo, como importar assinaturas que já estão rodando em outro sistema de cobrança. A ideia central: a assinatura entra já ativa, com o período real preservado, sem cobrar o período atual (que já foi pago na origem). A Chargefy assume a cobrança a partir do próximo ciclo. 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 (cobrável) e a assinatura continua ativa. O cartão pode ser coletado depois.
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 origemCampo que você enviaComo ela nasce na Chargefy
Ativabilling_cycle_anchor (próxima cobrança)active
Em período de testetrial_end (fim do trial)trialing
Já cancelada (histórico)canceled_at (data do cancelamento)canceled (registro inerte)

​
Passo a passo

1

Crie os customers

Cada assinatura precisa de um customer. Se você ainda não trouxe seus clientes, crie-os primeiro. Guarde o id do seu sistema em metadata para correlacionar depois.
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": { "external_id": "cliente_legado_42" }
  }'
2

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_123",
    "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.
3

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ê rodar a migração de novo, 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_123",
    "items": [{ "price": "price_123" }],
    "backdate_start_date": "2026-06-16T18:00:00Z",
    "billing_cycle_anchor": "2026-07-16T18:00:00Z",
    "proration_behavior": "none",
    "metadata": { "external_id": "assinatura_legada_987" }
  }'
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_123",
    "items": [{ "price": "price_123" }],
    "backdate_start_date": "2026-06-26T18:00:00Z",
    "trial_end": "2026-07-10T18:00:00Z",
    "proration_behavior": "none"
  }'
4

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 atualCampo no importVira na Chargefy
Início do período atual (já pago)backdate_start_datecurrent_period_start, start_date
Próxima cobrançabilling_cycle_anchorcurrent_period_end, next_billing_at
Fim do trial (se em trial)trial_endcurrent_period_end
Data do cancelamento (se cancelada)canceled_atcanceled_at, ended_at
Id da assinatura na origemIdempotency-Key + metadata.external_ididempotência + correlação

​
Regras de validação

O import recusa datas incoerentes com um erro 400 claro, sem criar nada:
RegraMotivo
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 futuroO trial ainda está rodando.
canceled_at deve estar no passadoA assinatura já foi cancelada.
proration_behavior deve ser noneConfirma que o período atual não é cobrado de novo.

​
Boas práticas

  • Use o id da assinatura na origem como Idempotency-Key. Migração em lote pode ser repetida sem medo de duplicar. Veja requisições idempotentes.
  • Guarde o id de origem também em metadata.external_id para correlacionar seus registros depois da migração.
  • Migre com folga: evite importar muito perto da data 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 import.

Requisições idempotentes

Como o header Idempotency-Key torna a migraçã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.