Vai al contenuto

Gestione degli upgrade e downgrade dell'abbonamento con calcolo proporzionale in 4Geeks Payments

🤖 Spiega con l'intelligenza artificiale

La gestione dei cicli di vita degli abbonamenti è una parte fondamentale della gestione di un’attività SaaS o di membership. Quando un cliente esegue l’upgrade o il downgrade del proprio piano nel bel mezzo di un ciclo di fatturazione, 4Geeks Payments gestisce automaticamente i calcoli proporzionali (proration). Ciò garantisce che ai tuoi clienti venga addebitato un importo equo (pagando solo per il tempo in cui hanno utilizzato ciascun piano) senza che tu debba eseguire calcoli manuali o emettere rimborsi separati.

Questa guida spiega come eseguire l’upgrade o il downgrade di un abbonamento in modo programmatico utilizzando l’API 4Geeks Payments e come il sistema calcola gli addebiti o i crediti proporzionali risultanti.

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

  • Un account 4Geeks Payments: Devi disporre di un account commerciante attivo.
  • Chiavi API: Le tue chiavi sk_test_ (per sandbox) o sk_live_ (per produzione).
  • ID abbonamento: L’identificatore univoco (UUID) dell’abbonamento che desideri modificare.
  • ID piano: L’identificatore univoco del nuovo piano a cui il cliente si sta trasferendo.
  • Accesso a 4Geeks Console: Accedi per gestire e verificare le modifiche.

Come aggiornare un abbonamento

4Geeks Payments semplifica le modifiche trattando gli upgrade e i downgrade come un aggiornamento dell’oggetto abbonamento esistente. Il sistema rileva automaticamente la differenza di prezzo e applica il calcolo proporzionale necessario.

Passaggio 1: Recupera l’abbonamento corrente

  1. Accedi alla 4Geeks Console.
  2. Vai al modulo Payments.
  3. Seleziona Subscriptions dalla barra laterale.
  4. Cerca il cliente tramite email o ID per elencare i suoi abbonamenti attivi.
  5. Annota il subscription_id per quello che desideri aggiornare.

In alternativa, utilizza l’API per recuperare gli abbonamenti in modo programmatico:

  • Endpoint: GET https://api.4geeks.io/v1/subscriptions/?customer={customer_id}

Passaggio 2: Aggiorna il piano di abbonamento

Invia una richiesta PUT all’endpoint dell’abbonamento con il nuovo plan_id. Ciò attiva la logica di calcolo proporzionale.

  1. Prepara la tua richiesta API con la chiave appropriata.
  2. Includi i dettagli del nuovo piano nel corpo della richiesta.

Esempio di richiesta (utilizzando cURL):

curl -X PUT "https://api.4geeks.io/v1/subscriptions/sub_123456789" \
  -u "sk_test_YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_new_tier_id"
  }'
  1. Invia la richiesta. Il sistema calcola immediatamente il calcolo proporzionale per il ciclo di fatturazione corrente.

Suggerimento: Per gli upgrade, aspettati una fattura immediata. Per i downgrade, un credito si applica alle fatture future. Evita di mescolare ID in modalità test e live per prevenire errori.

Passaggio 3: Verifica la fattura proporzionale

  1. Controlla la risposta API per i dettagli dell’abbonamento aggiornati, incluso latest_invoice.
  2. Nella 4Geeks Console, vai a Invoices per visualizzare la nuova fattura proporzionale.
  3. Conferma lo stato (ad es. “paid” o “open”) e l’importo dovuto.

Esempio di risposta (JSON semplificato):

{
  "id": "sub_123456789",
  "status": "active",
  "plan": {
    "id": "plan_new_tier_id",
    "name": "Pro Plan",
    "amount": 50.00
  },
  "current_period_end": "2023-12-01T00:00:00Z",
  "latest_invoice": {
    "id": "inv_987654321",
    "amount_due": 15.50,
    "status": "paid"
  }
}

Best Practice: Monitora i webhook per eventi come invoice.created o invoice.payment_succeeded per automatizzare le notifiche o gli aggiornamenti nel tuo sistema.

Casi d’uso comuni

Scenario 1: Upgrade a metà ciclo (Addebito immediato)

Un cliente su un piano Base da $10/mese passa al piano Pro da $30/mese a metà mese.

  • Il sistema accredita ~\(5 per il tempo Base non utilizzato e addebita ~\)15 per il tempo Pro rimanente.
  • Risultato: Fattura immediata da $10. Nessuna interruzione del servizio e il ciclo di fatturazione rimane lo stesso.

Ciò mantiene i clienti soddisfatti fornendo accesso immediato alle nuove funzionalità garantendo al contempo una fatturazione equa.

Scenario 2: Downgrade a metà ciclo (Credito applicato)

Un cliente passa da Pro da $30/mese a Base da $10/mese a metà strada.

  • Accredita ~\(15 per il tempo Pro non utilizzato e addebita ~\)5 per il tempo Base rimanente.
  • Risultato: Credito di $10 memorizzato nel saldo del cliente, applicato alla fattura successiva.

Ideale per fidelizzare i clienti che necessitano di flessibilità senza pagare troppo.

Risoluzione dei problemi

Problema 1: L’API restituisce 404 Not Found

  • Causa: subscription_id o plan_id errato.
  • Soluzione: Controlla due volte gli ID nella 4Geeks Console. Assicurati della coerenza della modalità test/live.

Problema 2: La fattura di upgrade fallisce (402 Payment Required)

  • Causa: La carta del cliente rifiuta l’addebito proporzionale.
  • Soluzione: Controlla lo stato di latest_invoice. Chiedi al cliente di aggiornare il metodo di pagamento tramite il link del portale clienti.

Problema 3: Nessun addebito visibile per il downgrade

  • Causa: I downgrade creano crediti, non rimborsi immediati.
  • Soluzione: Verifica il saldo del cliente nell’API o nella 4Geeks Console. I crediti si applicano automaticamente alle fatture future.

Conclusione

Con 4Geeks Payments, la gestione delle modifiche all’abbonamento è fluida e automatizzata, riducendo il carico amministrativo e migliorando la soddisfazione del cliente. Implementa questi passaggi per gestire upgrade e downgrade in modo efficiente. Per un’automazione più avanzata, esplora l’integrazione con 4Geeks AI Agents.

Risorse aggiuntive