RecorrênciaRequer liberação

Assinaturas

A assinatura liga um cliente a um plano. Por padrão a 1ª cobrança (vencimento em start_date) sai na hora; as seguintes, no vencimento de cada ciclo.

POST/recurring/subscriptions

Assina um cliente num plano.

Corpo da requisição

Campo	Tipo	Descrição
`plan_id`obrigatório	string	uuid de um plano ativo da sua conta.
`customer`obrigatório	object	Quem paga as cobranças.
`customer.name`obrigatório	string	Nome do cliente, até 255 caracteres.
`customer.email`obrigatório	string	E-mail que recebe as cobranças.
`customer.tax_id`obrigatório	string	CPF ou CNPJ válido, com ou sem máscara.
`amount`opcional	number	Valor próprio desta assinatura (mínimo 1.00). Sem ele: o valor do plano.
`message`opcional	string	Mensagem das cobranças, até 255 caracteres.
`start_date`opcional	string	Data do 1º vencimento (`YYYY-MM-DD`), de hoje até 1 ano à frente. Padrão: hoje.
`max_cycles`opcional	integer	Quantidade de cobranças (1 a 600). Padrão: `default_max_cycles` do plano.
`end_date`opcional	string	Data de término (`YYYY-MM-DD`), igual ou depois de `start_date`.
`notify_customer`opcional	boolean	Padrão `true`. Com `false`, a plataforma não envia e-mails ao cliente.
`issue_first_charge`opcional	boolean	Padrão `true`: gera a 1ª cobrança agora (Pix + e-mail) e a devolve em `first_charge`. Com `false`, ela sai no vencimento, a partir das 8h.
`reference`opcional	string	Identificador do seu sistema (até 100); garante a idempotência.

Requisição

1curl -X POST "https://api.sancopay.com/api/v1/recurring/subscriptions" \2  -H "Authorization: Bearer <TOKEN>" \3  -H "Content-Type: application/json" \4  -d '{5    "plan_id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",6    "customer": {7      "name": "Maria Souza",8      "email": "[email protected]",9      "tax_id": "123.456.789-09"10    },11    "start_date": "2026-10-01",12    "issue_first_charge": true,13    "reference": "ASS-1001"14  }'

Resposta

A assinatura, com a 1ª cobrança em first_charge.

1{2  "id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",3  "reference": "ASS-1001",4  "status": "active",5  "status_label": "Ativa",6  "plan": {7    "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",8    "name": "Plano Mensal",9    "periodicity": "monthly",10    "periodicity_label": "Mensal",11    "amount": 99.912  },13  "customer": {14    "name": "Maria Souza",15    "email": "[email protected]",16    "tax_id": "12345678909"17  },18  "amount": 99.9,19  "amount_override": null,20  "message": null,21  "start_date": "2026-10-01",22  "next_due_date": "2026-11-01",23  "upcoming_due_dates": [24    "2026-11-01",25    "2026-12-01",26    "2027-01-01"27  ],28  "cycles_issued": 1,29  "max_cycles": 12,30  "end_date": null,31  "notify_customer": true,32  "paused_at": null,33  "cancelled_at": null,34  "completed_at": null,35  "cancel_reason": null,36  "created_at": "2026-09-18T13:15:03.000000Z",37  "updated_at": "2026-09-18T13:15:03.000000Z",38  "first_charge": {39    "id": "c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96",40    "subscription_id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",41    "subscription_reference": "ASS-1001",42    "plan": {43      "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",44      "name": "Plano Mensal"45    },46    "customer": {47      "name": "Maria Souza",48      "email": "[email protected]"49    },50    "cycle_number": 1,51    "due_date": "2026-10-01",52    "amount": 99.9,53    "message": "Plano Mensal",54    "status": "pending",55    "status_label": "Em aberto",56    "pay_url": "https://app.sancopay.com/cobranca/k3Jd9xQ2mZ7pL4vR8tW1nB6cY0aF5sH2eU9gT4oM",57    "pix": {58      "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",59      "transaction_id": 4821,60      "generated_at": "2026-09-18T13:15:04.000000Z"61    },62    "last_pix_error": null,63    "issued_at": "2026-09-18T13:15:04.000000Z",64    "overdue_at": null,65    "paid_at": null,66    "paid_transaction_id": null,67    "cancelled_at": null,68    "duplicate_payment": false,69    "duplicate_payment_at": null,70    "created_at": "2026-09-18T13:15:04.000000Z",71    "transactions": [72      {73        "id": 4821,74        "status": "pending",75        "origin": "issue",76        "created_at": "2026-09-18T13:15:04.000000Z"77      }78    ],79    "emails": [80      {81        "kind": "due",82        "kind_label": "Vencimento",83        "status": "sent",84        "to_email": "[email protected]",85        "skip_reason": null,86        "failure_reason": null,87        "sent_at": "2026-09-18T13:15:06.000000Z",88        "created_at": "2026-09-18T13:15:04.000000Z"89      }90    ]91  }92}

Campos da assinatura

amount: Valor efetivo da próxima cobrança. amount_override é o valor próprio da assinatura (null = segue o plano).
upcoming_due_dates: Até 3 próximos vencimentos já calculados.
customer.tax_id: Volta só com dígitos.
max_cycles / end_date: Sem os dois, a assinatura segue até ser cancelada. Ao atingir um deles, passa para completed.

Consultar, listar e alterar

GET/recurring/subscriptionsFiltros: status (active, paused, cancelled, completed), plan_id, reference, q (nome, e-mail ou documento do cliente), page, per_page.
GET/recurring/subscriptions/{id}Consulta uma assinatura (mesmo formato da criação, sem first_charge).
PATCH/recurring/subscriptions/{id}Alteração parcial: customer.name, customer.email, customer.tax_id, amount (null volta a seguir o plano), message, max_cycles, end_date, notify_customer.

Buscar pela reference

1curl -X GET "https://api.sancopay.com/api/v1/recurring/subscriptions?reference=ASS-1001" \2  -H "Authorization: Bearer <TOKEN>"

Resposta200 OK

1{2  "data": [3    {4      "id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",5      "reference": "ASS-1001",6      "status": "active",7      "status_label": "Ativa",8      "plan": {9        "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",10        "name": "Plano Mensal",11        "periodicity": "monthly",12        "periodicity_label": "Mensal",13        "amount": 99.914      },15      "customer": {16        "name": "Maria Souza",17        "email": "[email protected]",18        "tax_id": "12345678909"19      },20      "amount": 99.9,21      "amount_override": null,22      "message": null,23      "start_date": "2026-10-01",24      "next_due_date": "2026-11-01",25      "upcoming_due_dates": [26        "2026-11-01",27        "2026-12-01",28        "2027-01-01"29      ],30      "cycles_issued": 1,31      "max_cycles": 12,32      "end_date": null,33      "notify_customer": true,34      "paused_at": null,35      "cancelled_at": null,36      "completed_at": null,37      "cancel_reason": null,38      "created_at": "2026-09-18T13:15:03.000000Z",39      "updated_at": "2026-09-18T13:15:03.000000Z"40    }41  ],42  "meta": {43    "page": 1,44    "per_page": 20,45    "total": 1,46    "last_page": 147  }48}

Alterar valor e e-mail

1curl -X PATCH "https://api.sancopay.com/api/v1/recurring/subscriptions/3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47" \2  -H "Authorization: Bearer <TOKEN>" \3  -H "Content-Type: application/json" \4  -d '{5    "amount": 79.9,6    "customer": {7      "email": "[email protected]"8    }9  }'

plan_id, start_date, periodicity e reference não podem ser alterados (422). Para trocar de plano, cancele e crie outra assinatura.
Assinatura cancelada ou concluída não pode ser alterada (409).
O novo amount vale a partir da próxima cobrança emitida; as já emitidas mantêm o valor.

Pausar, retomar e cancelar

POST/recurring/subscriptions/{id}/pausePausa uma assinatura active; deixa de gerar cobranças. Outro status: 409.
POST/recurring/subscriptions/{id}/resumeRetoma uma paused (outro status: 409). Sem cobrança retroativa: o próximo vencimento é o primeiro a partir de hoje.
POST/recurring/subscriptions/{id}/cancelEncerra a assinatura. Já cancelada ou concluída: 409.

Corpo do cancel

Campo	Tipo	Descrição
`cancel_open_charges`opcional	boolean	Padrão `true`: cancela também as cobranças em aberto e vencidas.
`reason`opcional	string	Motivo do cancelamento, até 255 caracteres.

Cancelar

1curl -X POST "https://api.sancopay.com/api/v1/recurring/subscriptions/3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47/cancel" \2  -H "Authorization: Bearer <TOKEN>" \3  -H "Content-Type: application/json" \4  -d '{5    "cancel_open_charges": true,6    "reason": "Pedido do cliente"7  }'

Resposta200 OK

1{2  "id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",3  "reference": "ASS-1001",4  "status": "cancelled",5  "status_label": "Cancelada",6  "plan": {7    "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",8    "name": "Plano Mensal",9    "periodicity": "monthly",10    "periodicity_label": "Mensal",11    "amount": 99.912  },13  "customer": {14    "name": "Maria Souza",15    "email": "[email protected]",16    "tax_id": "12345678909"17  },18  "amount": 99.9,19  "amount_override": null,20  "message": null,21  "start_date": "2026-10-01",22  "next_due_date": "2026-11-01",23  "upcoming_due_dates": [24    "2026-11-01",25    "2026-12-01",26    "2027-01-01"27  ],28  "cycles_issued": 1,29  "max_cycles": 12,30  "end_date": null,31  "notify_customer": true,32  "paused_at": null,33  "cancelled_at": "2026-11-09T15:04:05.000000Z",34  "completed_at": null,35  "cancel_reason": "Pedido do cliente",36  "created_at": "2026-09-18T13:15:03.000000Z",37  "updated_at": "2026-09-18T13:15:03.000000Z"38}

pause e resume não têm corpo. As três respondem 200 com a assinatura atualizada.