Shopify

Sync Data

Scopri come sincronizzare e personalizzare i dati dal tuo negozio Shopify

Sincronizza i prodotti, i meta-field e gli iscritti di Shopify con Clerk. Questa guida copre la creazione di un’app nel Developer Dashboard di Shopify, la personalizzazione dei dati prodotto e la sincronizzazione delle informazioni degli iscritti.

Configurare la sincronizzazione #

Per sincronizzare i dati del negozio Shopify con Clerk, devi creare un’app nel Developer Dashboard di Shopify e configurarla in Clerk. L’utente che configura la sincronizzazione deve avere accesso al Developer Dashboard e i permessi per sviluppare app sul negozio Shopify.

Requisiti di accesso: Solo i proprietari del negozio o lo staff con permessi da Amministratore possono creare l’app (non tramite accesso collaborativo). Lo stesso utente Shopify deve creare e installare l’app.

Crea l’app #

  1. In Shopify, vai a Settings > Apps > Develop Apps.

  2. Clicca su Build apps in Dev Dashboard.

    • Se non vedi questa opzione, clicca invece su Learn more.
    • Nella nuova finestra che si apre, clicca su Go to Dev Dashboard.
    • In alternativa, puoi aprire direttamente il Dev Dashboard dopo aver effettuato l’accesso.

  3. Nel Developer Dashboard, clicca su Create App.

  4. Inserisci Clerk.io come nome dell’app.

  5. In App URL, aggiungi il placeholder standard di Shopify per le app: https://shopify.dev/docs/apps/default-app-home

  6. Sotto Embed App in Shopify Admin, rimuovi il segno di spunta. L’app deve essere installata solo una volta e non deve comparire nel menu laterale di Shopify.

  7. In Webhooks API Version, seleziona l’ultima versione disponibile (almeno 2025-07).

Configura le autorizzazioni #

  1. Sotto Access scopes, concedi accesso alle autorizzazioni elencate qui sotto. Puoi incollare direttamente questa stringa nel campo di input per aggiungere tutte le autorizzazioni contemporaneamente:

    read_all_orders,read_customers,write_customers,read_inventory,read_locales,read_locations,read_markets,read_markets_home,read_metaobjects,read_online_store_pages,read_orders,read_products,read_publications,read_content,read_translations
    Perché serve l’accesso in scrittura? Clerk legge solo i dati, ma Shopify richiede l’autorizzazione write_customers per accedere ai campi URL di marketing dei clienti (ad esempio per sincronizzare customer.unsub_url).

    Oppure puoi selezionarle singolarmente:

    • Customers (read_ e write_)
    • Inventory (read_)
    • Locales (read_)
    • Locations (read_)
    • Markets (read_)
    • Markets Home (read_)
    • Metaobjects (read_)
    • Online Store Pages (read_)
    • Orders (read_)
    • All Orders (read_)
    • Products (read_)
    • Publications (read_)
    • Store Content (read_)
    • Translations (read_)

  2. In basso alla schermata, clicca su Release.

Installa l’app #

Importante: L’utente Shopify che crea l’app deve anche installarla. Se un altro utente tenta l’installazione, Shopify non la consentirà.

  1. Clicca su Home, poi clicca su Install app in alto a destra.

  2. Shopify ti reindirizza a una pagina dove selezionare lo store Shopify su cui installare l’app. Scegli il tuo store dalla lista.

  3. Nella pagina successiva, rivedi il riepilogo dei dettagli dell’app e clicca su Install in basso a destra.

Collega a Clerk #

  1. Torna al Developer Dashboard e clicca su Settings all’interno dell’app Clerk.io. Qui troverai Client ID e Client Secret.

  2. Vai su my.clerk.io > Data > Configuration. Sotto Sync Method, seleziona Shopify.

  3. Incolla Client ID e Client Secret nel form. Poi clicca su Start Sync.

Problema noto: Shopify potrebbe non generare il token alla prima sincronizzazione, causando un errore di autenticazione. Si tratta di un problema intermittente noto in Shopify. Attendi semplicemente 1-2 minuti e poi riprova la sincronizzazione.

Mercati e inventario #

Se gestisci diversi mercati, località o posizioni di inventario su Shopify, conferma questi campi prima della sincronizzazione:

  • Shopify Market
  • Shopify Locale
  • Prefix URLs with Locale
  • Force Relative URLs
  • Posizioni di inventario

Questi valori devono corrispondere all’impostazione di mercato/dominio del tuo Shopify. Per una mappatura completa campo per campo, vedi Shopify integration settings.

Dati delle varianti #

I dati delle varianti di Shopify possono comportarsi in modo diverso a seconda dell’impostazione Import only stock variant data.

Gli attributi tipici delle varianti Shopify in Clerk.io includono:

  • variant_inventory_policy (elenco stringhe)
  • variant_inventory_tracking (elenco booleano)
  • variant_list_prices (elenco numerico)
  • variant_names (elenco stringhe)
  • variant_option_size (elenco stringhe)
  • variant_prices (elenco numerico)
  • variant_stocks (elenco numerico)
  • variant_weight (elenco numerico)
  • variant_weight_unit (elenco stringhe)
  • variants (elenco stringhe, ID varianti)

Esempio:

{
  "variant_inventory_policy": ["deny", "deny"],
  "variant_inventory_tracking": [true, true],
  "variant_list_prices": [240, 240],
  "variant_names": ["Xs", "M"],
  "variant_option_size": ["Xs", "M"],
  "variant_prices": [120, 120],
  "variant_stocks": [1, 7],
  "variant_weight": [0.4, 0.4],
  "variant_weight_unit": ["KILOGRAMS", "KILOGRAMS"],
  "variants": ["55970989179259", "55970989244795"]
}

Quando Import only stock variant data è attivo, queste liste includono solo le varianti in stock.

Personalizzazione dei dati prodotto #

In Shopify, i meta-field e gli altri attributi creati possono essere sincronizzati tramite my.clerk.io > System status > Data sync.

Vai semplicemente sul campo di input chiamato Custom Attributes e digita gli attributi prodotto da includere.

Per aggiungere più attributi, separali con virgole.

Add attributes

Gli attributi devono sempre essere scritti usando il loro key.

Di solito sono tutti in minuscolo. Ad esempio, l’attributo “Sizes” deve essere “sizes”.

Non serve includere il namespace - Clerk lo riconoscerà automaticamente in base al key.

In Shopify, spesso puoi trovare queste chiavi trovando il tuo attributo in Settings > Custom data > Products/Variants:

Custom data

Sincronizzare gli iscritti #

Shopify consente di gestire gli iscritti direttamente nella piattaforma.

Questi possono essere facilmente sincronizzati con Clerk.

Quando è attivo, importeremo quell’attributo “subscribed: true” per ogni indirizzo email iscritto in Shopify.

Questo può poi essere utilizzato per Auto-Email.

Vai semplicemente al tuo store my.clerk.io, quindi Data -> Configuration e imposta Include Subscriber State su Yes. Poi clicca su Save e avvia una nuova sincronizzazione.

Subscriber state configuration

Se vuoi offrire un link di disiscrizione ai clienti, ogni cliente importato da un backend Shopify ha un attributo unsub_url che può essere utilizzato nei design di auto email come campo di disiscrizione: {{customer.unsub_url}}

La versione delle Webhooks API deve essere impostata almeno alla 2022-04, dove è stato aggiunto questo supporto. Puoi verificarlo nell’app che hai creato per Clerk nel Developer Dashboard sotto Settings.

Legacy Custom App #

Da gennaio 2026, Shopify non consente più la creazione di app personalizzate direttamente dall’amministrazione dello store. Le app personalizzate esistenti continueranno a funzionare, ma questo metodo dovrebbe essere utilizzato solo se hai già un’app personalizzata configurata. Per tutte le altre configurazioni, utilizza il Developer Dashboard method sopra.

Se hai già un’app personalizzata esistente e hai bisogno di utilizzarla o modificarla, seleziona Shopify (Legacy Custom App) come Sync Method in my.clerk.io > Data > Configuration.

Questi passaggi si applicano solo se il tuo negozio Shopify consente ancora la creazione di app personalizzate dall’amministrazione.

  1. In Shopify, vai a Settings > Apps > Develop Apps.
Develop apps page

  1. Clicca su Create app, assegnale il nome “Clerk.io”, scegli lo sviluppatore dell’app, poi clicca ancora su Create app.

  2. Clicca su Configuration → Admin API integration → Configure.

Permissions configuration

  1. Sotto Admin API access scopes, concedi accesso in sola lettura (autorizzazioni che iniziano con read_) ai seguenti permessi. Per Customers, impostalo su Lettura e scrittura (include write_customers).

    Perché serve l’accesso in scrittura? Clerk legge solo i dati, ma Shopify richiede l’autorizzazione write_customers per accedere ai campi URL di marketing dei clienti (ad esempio per sincronizzare customer.unsub_url).

    Puoi incollare direttamente questa stringa nel campo di input per aggiungere tutte le autorizzazioni contemporaneamente:

    read_all_orders,read_customers,write_customers,read_inventory,read_locales,read_locations,read_markets,read_markets_home,read_metaobjects,read_online_store_pages,read_orders,read_products,read_publications,read_content,read_translations

    Oppure puoi selezionarle singolarmente:

    • Customers (read_ e write_)
    • Inventory (read_)
    • Locales (read_)
    • Locations (read_)
    • Markets (read_)
    • Markets Home (read_)
    • Metaobjects (read_)
    • Online Store Pages (read_)
    • Orders (read_)
    • All Orders (read_)
    • Products (read_)
    • Publications (read_)
    • Store Content (read_)
    • Translations (read_)
API access scopes

  1. Clicca su Save, poi Install App → Install.

  2. Apri API Credentials e copia il tuo dominio Shopify e l’API Key, Access Token e Secret Key dell’app.

API credentials

  1. Vai a my.clerk.io > Data > Configuration. Sotto Sync Method, seleziona Shopify (Legacy Custom App).

  2. Incolla questi valori nel form. Scegli una dimensione immagine predefinita se richiesto, poi clicca su Start Sync.

Questa pagina è stata tradotta da un'utile intelligenza artificiale, quindi potrebbero esserci errori linguistici. Grazie per la comprensione.