Trocar plano da assinatura

PATCH

/api/partner/v1/subscriptions/{token}/change-plan

Troca o plano de uma assinatura ativa. Regras:

Só permite entre planos do mesmo produto e mesmo billing_method.

V1: apenas billing_method: qr_code. Pix Automático será suportado em v2.

Upgrade (novo plano com amount maior): aplica imediatamente. Cria
cobrança PIX de pró-rata (diferença proporcional ao restante do ciclo).
Se cliente não pagar a pró-rata dentro do prazo do QR, a assinatura
permanece no plano novo — a pró-rata simplesmente expira e dispara
cobranca_falhou.

Downgrade (novo plano com amount menor): não cria cobrança agora.
Agenda a troca para next_charge_at da assinatura. Cliente continua
usando o plano atual até o fim do ciclo pago. Zero devolução.

Same value: aplica imediatamente sem cobrança.

Requisição

Authorization

Bearer Token

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

Parâmetros de Caminho

Parâmetros Bodyapplication/jsonObrigatório

Examples

Respostas

🟢200

application/json

Bodyapplication/json

🟠404

🟠422

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PATCH '/api/partner/v1/subscriptions//change-plan' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "new_plan_token": "ce228ae1-1050-42c4-9d0c-8ecbd4012c97",
    "reason": "string"
}'

Response Example

200 - Exemplo 1

{
    "data": {
        "token": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "status": "pending_first_payment",
        "subscriber_name": "João Silva",
        "subscriber_email": "joao@email.com",
        "subscriber_document": "123.456.789-00",
        "subscriber_phone": "+5511999999999",
        "started_at": "2025-06-01T10:00:00.000000Z",
        "next_charge_at": "2025-07-01T10:00:00.000000Z",
        "overdue_since": null,
        "suspended_at": null,
        "cancelled_at": null,
        "retry_count": 0,
        "plan": {
            "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Plano Mensal",
            "description": "Acesso completo à plataforma por 30 dias",
            "amount": "50.00",
            "periodicity_days": 30,
            "billing_advance_days": 3,
            "grace_period_days": 5,
            "max_retry_attempts": 3,
            "billing_method": "qr_code",
            "status": "active",
            "checkout_url": "https://app.syncpayments.com.br/subscription/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "splits": [
                {
                    "email": "parceiro@empresa.com",
                    "name": "Parceiro Silva",
                    "percentage": 20,
                    "status": "pending",
                    "invited_at": "2026-07-14T18:30:00+00:00",
                    "accepted_at": "2026-07-14T18:45:12+00:00"
                }
            ],
            "is_default": false,
            "display_order": 0,
            "active_subscriptions_count": 12,
            "product": {
                "reference_id": "a245c59c-e269-42ff-b36d-b0a0059768d3",
                "name": "Curso Premium",
                "image_url": "https://cdn.syncpayments.com.br/products/abc.png"
            }
        },
        "charges": [
            {
                "cycle_number": 2,
                "amount": "50.00",
                "status": "pending",
                "due_date": "2025-07-01",
                "expires_at": "2025-07-02T00:00:00.000000Z",
                "paid_at": null,
                "payment": {
                    "pix_code": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
                    "qr_code": null
                }
            }
        ]
    },
    "plan_change": {
        "type": "upgrade",
        "from_plan_token": "63c9472b-efc6-492d-ab5c-897d70e2b949",
        "from_plan_name": "string",
        "to_plan_token": "a5372bee-ed89-4e36-b6fa-6337f44fb0a2",
        "to_plan_name": "string",
        "applied_at": "2019-08-24T14:15:22.123Z",
        "scheduled_for": "2019-08-24T14:15:22.123Z",
        "proration_amount": "string",
        "proration_charge": {
            "cycle_number": 2,
            "amount": "50.00",
            "status": "pending",
            "due_date": "2025-07-01",
            "expires_at": "2025-07-02T00:00:00.000000Z",
            "paid_at": null,
            "payment": {
                "pix_code": "00020126360014BR.GOV.BCB.PIX0114+5511999999999...",
                "qr_code": null
            }
        }
    }
}

Modificado em 2026-08-11 04:52:18

Página anterior

Reenviar cobrança

Próxima página

Listar entregas de um webhook