> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrar assinaturas de outro sistema
> Traga suas assinaturas ativas de outro sistema de cobrança para a Chargefy — preservando as datas reais, sem cobrar de novo o período atual e sem precisar do cartão agora.
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 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
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.
```bash theme={}
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" }
}'
```
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).
```bash theme={}
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.
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.
```bash theme={}
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:
```bash Em trial theme={}
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"
}'
```
```bash Já cancelada (histórico) theme={}
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_123",
"items": [{ "price": "price_123" }],
"backdate_start_date": "2026-05-02T18:00:00Z",
"canceled_at": "2026-06-21T18:00:00Z",
"proration_behavior": "none"
}'
```
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 no import | 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` + `metadata.external_id` | idempotência + correlação |
## Regras de validação
O import 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`. Migração em lote
pode ser repetida sem medo de duplicar. Veja
[requisições idempotentes](/api-reference/idempotency).
* 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
Contrato completo do `POST /v1/subscriptions`, incluindo os campos de import.
Como o header `Idempotency-Key` torna a migração em lote segura.
Traga seus clientes antes de importar as assinaturas.
Cadastre os preços recorrentes que as assinaturas vão usar.