Introduzione

Questa sezione definisce gli schemi completi per gli eventi relativi alle Subscription (Abbonamenti) su Webround Commerce. La gestione degli abbonamenti permette di automatizzare le vendite ricorrenti, monitorando in tempo reale lo stato dei pagamenti, i periodi di prova e i cicli di fatturazione sincronizzati con Stripe.

Perché ascoltare gli eventi sugli abbonamenti

L'integrazione degli eventi subscription è fondamentale per:

• Gestione Accessi: Attivare o revocare permessi e servizi in base allo stato status dell'abbonamento (es. active, past_due, canceled).
• Sincronizzazione Billing: Monitorare le date di fine periodo (currentPeriodEnd) e gestire i rinnovi o le cancellazioni programmate.
• Customer Care: Fornire assistenza immediata in caso di fatture fallite tramite il monitoraggio del latestInvoiceId.
• Analisi Trial: Tracciare l'inizio e la fine dei periodi di prova per strategie di conversione marketing.

Tabella Completa Eventi e Payload

Evento	Payload Schema	Esempio JSON
subscription.created	Subscription Schema	Link
subscription.updated	Subscription Schema	Link
subscription.canceled	Subscription Schema	Link
subscription.deleted	Subscription Deleted Schema	Link

---

Schema Abbonamento (subscriptionDataSchema)

Campo	Tipo	Note
id	uuid	Obbligatorio. ID univoco su Webround
stripeId	string	Obbligatorio. ID dell'abbonamento su Stripe
storeCustomerId	uuid	Obbligatorio. ID cliente interno
stripeCustomerId	string	Obbligatorio. ID cliente su Stripe
status	string	Stato (es. trialing, active, past_due, canceled)
activeSince	isoDate	Data di inizio attivazione
currentPeriodEnd	isoDate	Data fine del ciclo di fatturazione corrente
cancelAtPeriodEnd	boolean	Se true, l'abbonamento scadrà alla fine del periodo
latestInvoiceId	string	ID dell'ultima fattura generata
trialStart/End	isoDate	Date relative al periodo di prova

Esempio Abbonamento

{
    "envelopeId": "e1f2g3h4-i5j6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "subscription.updated",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:45:00.000Z",
    "data": {
        "id": "s1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
        "stripeId": "sub_1QRsT2U3V4W5X6",
        "storeCustomerId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "stripeCustomerId": "cus_R987654321",
        "stripeAccountId": "acct_123456789",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
        "status": "active",
        "activeSince": "2026-01-22T10:00:00.000Z",
        "currentPeriodEnd": "2026-03-22T10:00:00.000Z",
        "cancelAtPeriodEnd": false,
        "latestInvoiceId": "in_1QSx...",
        "latestInvoiceUrl": "https://invoice.stripe.com/...",
        "trialStart": null,
        "trialEnd": null,
        "createdAt": "2026-01-22T10:00:00.000Z",
        "updatedAt": "2026-02-22T23:45:00.000Z"
    },
    "eventId": "k1l2m3n4-o5p6-4a5b-b6c7-d8e9f0a1b2c3"
}

---

Schema Abbonamento Eliminato (subscriptionDeletedSchema)

Campo	Tipo	Note
subscriptionId	uuid	Obbligatorio. ID dell'abbonamento rimosso

Esempio Abbonamento Eliminato

{
    "envelopeId": "f2g3h4i5-j6k7-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "subscription.deleted",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:50:00.000Z",
    "data": {
        "subscriptionId": "s1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "l2m3n4o5-p6q7-4a5b-b6c7-d8e9f0a1b2c3"
}