Collezioni di Prodotti

Le Product Collections raggruppano prodotti correlati (ad es. piani Starter, Pro, Enterprise) sotto un unico insieme. Mostra tutte le opzioni in un singolo checkout, definisci i percorsi di upgrade/downgrade e consenti ai clienti di cambiare piano direttamente dal Customer Portal.

Schermata della pagina di checkout della Collezione di Prodotti che mostra più prodotti visualizzati

Punti Salienti

Le Product Collections consentono di:

Raggruppare prodotti correlati (piani, livelli, opzioni di prezzo) per una gestione organizzata.
Includere più prodotti, come Starter, Pro e Lifetime, ciascuno con il proprio modello di prezzo.
Mostrare tutti i prodotti in un’unica vista di checkout, così che i clienti possano confrontare e scegliere il piano preferito.
Consentire ai clienti di effettuare l’upgrade o il downgrade tra prodotti della stessa raccolta tramite il Customer Portal.
Controllare quali prodotti sono visibili, in quale ordine e quale viene preselezionato al checkout.

Creazione di una Product Collection

Crea e gestisci le raccolte dalla dashboard o tramite API.

Create the collection

Definisci la raccolta con un nome e una descrizione opzionale. Carica un’immagine per rappresentarla nel checkout.

Screenshot del modulo per la creazione di una Product Collection nella dashboard, con campi per nome, descrizione e caricamento dell'immagine

Campi della raccolta:

Nome (obbligatorio): nome visualizzato (ad es. “Piani SaaS”, “Livelli di licenza”).
Descrizione (opzionale): breve spiegazione mostrata nel checkout.
Immagine (opzionale): elemento visivo per il branding della raccolta.

Add products to the collection

Aggiungi prodotti esistenti alla raccolta. Organizzali in gruppi per una struttura migliore.

Screenshot della pagina dei prodotti di una Product Collection, con un elenco di prodotti e la possibilità di aggiungerli alla raccolta

Organizzazione dei prodotti:

Gruppi: organizza facoltativamente i prodotti in gruppi con nome (ad es. “Piani mensili”, “Piani annuali”).
Prodotti non raggruppati: i prodotti senza gruppo vengono visualizzati a livello della raccolta.
Ordinamento: trascina e rilascia per impostare l’ordine di visualizzazione.

Ogni prodotto può appartenere a una sola raccolta. Se un prodotto si trova già in un’altra raccolta, rimuovilo prima.

Configure ordering and visibility

Controlla l’ordine di visualizzazione e la visibilità dei prodotti all’interno della raccolta.Opzioni di configurazione:

Stato del prodotto: abilita o disabilita singoli prodotti all’interno della raccolta.
Ordine di visualizzazione: trascina e rilascia per impostare la sequenza in cui i prodotti vengono mostrati nel checkout.

Il primo prodotto nella raccolta viene preselezionato automaticamente al checkout. Riordina i prodotti per modificare quello selezionato per impostazione predefinita.

Checkout della raccolta

Le raccolte consentono un’esperienza di checkout unificata, in cui i clienti visualizzano e selezionano tutti i prodotti disponibili in un unico luogo.

Tipi di checkout

Tipo	Descrizione	Caso d’uso
Checkout della raccolta	Mostra tutti i prodotti attivi all’interno di una raccolta	Selezione di piani in abbonamento, prezzi a livelli
Checkout di un singolo prodotto	Mostra un solo prodotto specifico	Acquisto diretto, link promozionali

Esperienza di checkout della raccolta

Quando utilizzi il checkout di una raccolta:

Vengono mostrati tutti i prodotti attivi nella raccolta.
Il primo prodotto nell’ordine della raccolta viene preselezionato automaticamente.
Ogni prodotto mostra nome, descrizione e prezzo.
Il cliente seleziona un prodotto da acquistare.
Il checkout prosegue con i prezzi e le impostazioni di fatturazione del prodotto scelto.

Screenshot della pagina di checkout di una Product Collection, con più prodotti visualizzati

Il checkout della raccolta è ideale per le attività in abbonamento, in cui i clienti confrontano i piani affiancati prima dell’acquisto.

Integrazione API

Crea una sessione di checkout per una raccolta:

const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

window.location.href = session.checkout_url;

Quando utilizzi product_collection_id, i codici sconto non possono essere applicati in anticipo durante la creazione della sessione. I clienti possono comunque inserire i codici durante il checkout, se abilitati.

Integrazione con il Customer Portal

I clienti possono effettuare l’upgrade o il downgrade tra prodotti della stessa raccolta direttamente dal Customer Portal.

Hai già prodotti in abbonamento? Aggiungili a una Product Collection per abilitare i flussi di upgrade/downgrade nel Customer Portal. Non è necessario ricreare i prodotti.

Azioni di gestione del piano

Azione	Descrizione	Controllo del merchant
Visualizza piano attuale	Mostra il nome, il prezzo e la data di rinnovo del prodotto attuale.	Sempre disponibile.
Upgrade del piano	Passa a un prodotto di livello superiore nella stessa raccolta.	Configurabile (predefinito: disabilitato).
Downgrade del piano	Passa a un prodotto di livello inferiore nella stessa raccolta.	Configurabile (predefinito: disabilitato).
Annulla	Annulla completamente l’abbonamento.	Sempre disponibile.

Regole per upgrade e downgrade

Gli upgrade e i downgrade sono disponibili solo tra prodotti all’interno della stessa raccolta.
La proroga per le modifiche del piano nel Customer Portal segue il comportamento predefinito di upgrade e downgrade in Settings → Subscriptions, e ogni raccolta può sostituire queste impostazioni predefinite. Le modifiche del piano effettuate tramite la Change Plan API utilizzano proration_billing_mode inviato con la richiesta.
A ogni upgrade, downgrade o annullamento vengono inviate notifiche email all’attività.

I clienti non possono passare a prodotti esterni alla raccolta attuale. Crea raccolte separate per linee di prodotto distinte.

Impostazioni degli abbonamenti

Configura il funzionamento degli abbonamenti e delle modifiche dei piani per la tua attività da Settings → Subscriptions nella dashboard.

Impostazioni disponibili

Impostazione	Descrizione	Predefinito
Allow Multiple Subscriptions	I clienti possono avere più di un abbonamento attivo contemporaneamente.	Abilitato
Allow Subscription Updates	I clienti possono effettuare in qualsiasi momento l’upgrade o il downgrade degli abbonamenti esistenti tramite Customer Portal.	Disabilitato
Allow Immediate Cancellation	I clienti possono terminare il proprio abbonamento e perdere immediatamente l’accesso.	Abilitato
Allow Cancellation at Next Billing Date	I clienti possono annullare l’abbonamento alla fine del periodo già pagato.	Abilitato
Allow Subscription Pause	I clienti possono mettere in pausa e riprendere autonomamente i propri abbonamenti dal Customer Portal.	Disabilitato
Bill Usage at Pause	Un abbonamento basato sull’utilizzo messo in pausa viene fatturato per l’utilizzo dovuto nel momento della pausa, invece di trasferire l’utilizzo alla fattura successiva.	Abilitato
Prevent Trial Misuse	I clienti che hanno già riscattato una prova vengono convertiti in un acquisto a pagamento senza prova, invece di ricevere una nuova prova.	Disabilitato
Payment Method Reminder	Giorni prima dell’inizio della fatturazione in cui al cliente di un abbonamento Card-Optional at Zero Price viene inviata un’email per aggiungere un metodo di pagamento (da 1 a 30 giorni).	3 giorni

Le modifiche del piano tramite Customer Portal sono disabilitate per impostazione predefinita. Abilita “Allow Subscription Updates” in Settings → Subscriptions per consentire ai clienti di effettuare l’upgrade o il downgrade tra prodotti della stessa raccolta.

Le due impostazioni di annullamento sono indipendenti: puoi consentire ai clienti di usufruire del periodo già pagato mantenendo per te l’annullamento immediato, oppure il contrario. Disabilitando una delle due opzioni, questa viene nascosta nel Customer Portal e le richieste corrispondenti tramite Customer Portal API vengono rifiutate. Gli annullamenti effettuati dal merchant non sono interessati. Consulta Cancelling a Subscription.

“Allow Subscription Pause” riguarda solo il Customer Portal: puoi mettere in pausa e riprendere gli abbonamenti dalla dashboard o tramite API, indipendentemente dall’impostazione. “Bill Usage at Pause” si applica solo agli abbonamenti basati sull’utilizzo e viene registrato per ciclo di fatturazione; modificarlo durante il ciclo non cambia il modo in cui viene regolato il ciclo in corso. Consulta Pausing and Resuming Subscriptions.

Per informazioni dettagliate sulla corrispondenza e la registrazione dei riscatti delle prove, consulta Preventing Trial Misuse.

“Payment Method Reminder” è rilevante solo per gli abbonamenti con Card-Optional at Zero Price abilitato; non ha effetto sugli abbonamenti che richiedono già una carta. Consulta What Happens Without a Card per la sequenza completa, incluso ciò che accade se il promemoria viene ignorato.

Subscription Plan Changes

Scopri di più sulle modalità di proroga e sul comportamento delle modifiche dei piani.

Gestione delle raccolte

Gestisci le raccolte tramite dashboard o programmaticamente tramite API.

Operazioni dalla dashboard

Crea: configura nuove raccolte con prodotti e gruppi.
Aggiorna: modifica nome, descrizione, immagine e organizzazione dei prodotti.
Riordina: trascina e rilascia per modificare l’ordine di visualizzazione dei prodotti.
Abilita/Disabilita prodotti: controlla quali prodotti vengono mostrati nel checkout.
Archivia: nascondi una raccolta senza eliminarla definitivamente (può essere ripristinata in seguito).

Screenshot della dashboard delle Product Collections, con le operazioni di gestione delle raccolte

Gestione tramite API

Utilizza i seguenti endpoint per creare, aggiornare, recuperare, archiviare e organizzare programmaticamente le Product Collections, inclusa la gestione di gruppi e prodotti nidificati.

Listing Product Collections

Recupera tutte le Product Collections associate al tuo account utilizzando una richiesta GET all’endpoint /product-collections. Supporta la paginazione, il filtraggio per brand e l’inclusione delle raccolte archiviate.

List Product Collections API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API List Product Collections.

Creating a Product Collection

Crea una nuova Product Collection inviando una richiesta POST all’endpoint /product-collections con dettagli quali nome, descrizione e brand.

Create Product Collection API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Create Product Collection.

Retrieving a Product Collection

Ottieni informazioni dettagliate su una Product Collection specifica, inclusi gruppi ed elementi prodotto, utilizzando una richiesta GET all’endpoint /product-collections/{id}.

Get Product Collection API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Get Product Collection.

Updating a Product Collection

Modifica i dettagli di una Product Collection (nome, descrizione, brand e così via) inviando una richiesta PATCH all’endpoint /product-collections/{id}.

Update Product Collection API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Update Product Collection.

Uploading Collection Images

Associa un’immagine a una raccolta caricandola tramite un URL pre-firmato. Richiedi un URL di caricamento dall’endpoint /product-collections/{id}/images, quindi esegui PUT dell’immagine all’URL restituito entro 60 secondi.

L’URL pre-firmato scade dopo 60 secondi, quindi l’immagine deve essere caricata entro tale intervallo.

Update Collection Images API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Update Collection Images.

Archiving a Product Collection

Archivia una raccolta inviando una richiesta DELETE all’endpoint /product-collections/{id}. In questo modo la raccolta non sarà disponibile per i nuovi utilizzi, ma non verrà rimossa definitivamente.

Archive Product Collection API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Archive Product Collection.

Unarchiving a Product Collection

Ripristina una raccolta archiviata inviando una richiesta POST all’endpoint /product-collections/{id}/unarchive.

Unarchive Product Collection API

Visualizza la struttura dettagliata della richiesta e della risposta nella documentazione dell’API Unarchive Product Collection.

Managing Groups within a Collection

I gruppi consentono di organizzare i prodotti all’interno di una raccolta (ad esempio, “Piani mensili” e “Piani annuali”). Utilizza gli endpoint dei gruppi per aggiungere, aggiornare o rimuovere gruppi all’interno di una raccolta.

Crea un gruppo: POST /product-collections/{id}/groups
Aggiorna un gruppo: PATCH /product-collections/{id}/groups/{group_id}
Elimina un gruppo: DELETE /product-collections/{id}/groups/{group_id}

Create Group

Aggiungi un nuovo gruppo a una Product Collection.

Update Group

Modifica il nome o gli attributi di un gruppo.

Delete Group

Rimuovi un gruppo da una raccolta.

Managing Products within a Group

Gestisci i singoli elementi prodotto all’interno di un gruppo: aggiungi nuovi prodotti, aggiorna gli elementi esistenti (ad esempio l’ordine di visualizzazione) o rimuovili completamente.

Aggiungi prodotti a un gruppo: POST /product-collections/{id}/groups/{group_id}/items
Aggiorna un elemento del gruppo: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
Elimina un elemento del gruppo: DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

Aggiungi uno o più prodotti a un gruppo all’interno di una raccolta.

Update Group Item

Aggiorna un elemento prodotto all’interno di un gruppo.

Delete Group Item

Rimuovi un elemento prodotto da un gruppo.

Buone pratiche

Raggruppa logicamente: organizza i prodotti per intervallo di fatturazione (mensile/annuale) o livello di funzionalità (starter/pro/enterprise).
Ordina strategicamente: posiziona per primo il piano più popolare o consigliato, poiché verrà preselezionato al checkout.
Utilizza nomi chiari: i nomi dei prodotti devono comunicare chiaramente le differenze di valore.
Abilita entrambe le direzioni: consenti sia gli upgrade sia i downgrade per offrire flessibilità ai clienti.
Considera la proroga: scegli una modalità di proroga in linea con il tuo modello di business.
Esegui test approfonditi: verifica i flussi di checkout e di modifica del piano in modalità di test prima della messa in produzione.

Products

Crea prodotti una tantum, in abbonamento o basati sull’utilizzo da aggiungere alle raccolte.

Checkout

Visualizza i prodotti della raccolta in un’esperienza di checkout unificata.

Customer Portal

Consenti ai clienti di effettuare l’upgrade o il downgrade all’interno della stessa raccolta.

Subscriptions

Gestisci i piani ricorrenti con proration e modifiche del piano.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Punti Salienti

Creazione di una Product Collection