Panoramica dei programmi fedeltà

Mostra i vantaggi del tuo negozio su Google utilizzando i programmi fedeltà. Puoi specificare una serie di vantaggi, come la spedizione gratuita, i punti riscattabili e i prezzi esclusivi per i membri. I vantaggi del tuo programma fedeltà possono essere visualizzati nelle schede senza costi, negli annunci Shopping e negli annunci di inventario locale sulle piattaforme Google, tra cui la Ricerca Google, la scheda Shopping e Google Wallet.

Con l'API Merchant, i commercianti e i fornitori di programmi fedeltà di terze parti che agiscono per loro conto possono configurare e gestire i programmi fedeltà in modo programmatico utilizzando LoyaltyProgramService. Questo servizio ti consente di creare, recuperare, elencare, aggiornare ed eliminare i programmi fedeltà.

Per saperne di più sui requisiti aziendali e sulle linee guida sulle norme, consulta Informazioni sul programma fedeltà del commerciante nel Centro assistenza Merchant Center.

Concetti fondamentali

Tieni presente i seguenti concetti e limitazioni quando utilizzi i programmi fedeltà:

  • Identificatore a livello di account: l'API Merchant identifica i programmi fedeltà in base all'ID account Merchant Center proprietario.

  • Limite di un singolo programma: l'API Merchant supporta un solo programma fedeltà per account commerciante.

  • Proprietà diretta dell'account: i programmi fedeltà devono essere configurati direttamente nell'account commerciante di destinazione (accounts/{ACCOUNT_ID}). Il servizio non supporta la gestione dei programmi fedeltà a livello di account avanzato per i subaccount. I fornitori di programmi fedeltà di terze parti con accesso autorizzato all'account di un commerciante possono gestire il programma per conto del commerciante.

  • Revisione redazionale: dopo aver creato o aggiornato un programma fedeltà, il programma viene sottoposto a revisione. Il campo review_result.review_status indica se il programma è UNDER_REVIEW, APPROVED o REJECTED. Ogni aggiornamento riuscito rimanda il programma alla coda di revisione, anche se l'aggiornamento non apporta modifiche significative. Google nasconde il programma agli acquirenti durante la procedura di revisione. La revisione può richiedere fino a 48 ore.

  • Regioni supportate: i programmi fedeltà dei commercianti sono disponibili nei paesi supportati, tra cui Australia, Brasile, Canada, Corea del Sud, Francia, Germania, Giappone, India, Italia, Messico, Paesi Bassi, Regno Unito, Spagna e Stati Uniti.

  • Regioni attive: l'attributo regionCodes di un programma fedeltà deve essere un sottoinsieme dell'attributo activeRegionCodes di accounts/{ACCOUNT_ID}/programs/loyalty. In caso contrario, le richieste di creazione, aggiornamento ed eliminazione non vanno a buon fine e viene visualizzato un errore LOYALTY_PROGRAM_DISABLED. Google attiva un paese supportato quando il componente aggiuntivo Programma fedeltà è attivato e l'account soddisfa i requisiti di idoneità in quel paese. Ad esempio, l'account è idoneo se il programma Schede senza costi è attivato e un'origine dei dati di prodotto principale ha come target il paese per la destinazione FREE_LISTINGS. Per scoprire perché un paese non è attivo, consulta Controlla le regioni attive.

  • Requisiti dei livelli: i livelli possono essere senza costi, richiedere una quota di iscrizione, una soglia di spesa o una carta di credito con il brand del commerciante. I livelli basati sull'occupazione (ad esempio i livelli per studenti o militari) non sono supportati.

  • Vantaggi e benefit: i programmi supportano la spedizione gratuita, i punti utilizzabili e i prezzi per i membri. Negli annunci, il prezzo per i membri richiede uno sconto di almeno il 5% o di 5 unità di valuta rispetto al prezzo normale o scontato.

Prerequisiti

Prima di gestire i programmi fedeltà con l'API Merchant, assicurati di soddisfare i seguenti requisiti:

  • Devi disporre di un account Merchant Center attivo (o di un accesso autorizzato all'account del commerciante se sei un fornitore di programmi fedeltà di terze parti).

  • Attiva il componente aggiuntivo del programma fedeltà per il tuo account. Puoi attivare il componente aggiuntivo utilizzando una delle seguenti opzioni:

  • I paesi in cui vuoi offrire il tuo programma fedeltà devono essere attivi per il tuo account. Per scoprire quali paesi sono attivi, consulta Controlla le regioni attive.

Ecco una richiesta di esempio per attivare il componente aggiuntivo del programma fedeltà utilizzando la sub-API Programs:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Controlla le regioni attive

Dopo aver attivato il componente aggiuntivo del programma fedeltà, chiama il metodo accounts.programs.get per accounts/{ACCOUNT_ID}/programs/loyalty. La risposta mostra dove puoi utilizzare i programmi fedeltà e perché gli altri paesi supportati non sono attivi.

Ecco una richiesta di esempio:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

Sostituisci {ACCOUNT_ID} con l'identificatore univoco del tuo account Merchant Center.

Ecco un esempio di risposta per un account che ha attivato il componente aggiuntivo ed è idoneo solo negli Stati Uniti:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

In questa risposta, osserva i seguenti campi:

  • activeRegionCodes: i paesi che puoi utilizzare nel regionCodes del tuo programma fedeltà. Nell'esempio precedente, è attivo solo US.
  • unmetRequirements: il motivo per cui gli altri paesi supportati non sono attivi. Per i programmi fedeltà, questo è il requisito IS_ELIGIBLE_FOR_LOYALTY.
    • affectedRegionCodes: i paesi supportati in cui l'account non è idoneo.
    • documentationUri: un link ai requisiti di idoneità.

Nell'esempio precedente, non puoi ancora utilizzare i paesi in affectedRegionCodes. Se il regionCodes del tuo programma fedeltà include uno di questi, le richieste di creazione, aggiornamento ed eliminazione non vanno a buon fine e viene restituito un errore LOYALTY_PROGRAM_DISABLED. Per attivare un paese, segui questi passaggi:

  1. Rendere l'account idoneo in quel paese. Ad esempio, attiva il programma Schede senza costi e imposta un'origine dei dati di prodotto principale per scegliere come target il paese per la destinazione FREE_LISTINGS. Per scoprire tutti i modi per diventare idoneo, consulta i requisiti di idoneità.
  2. Chiama di nuovo accounts.programs.get e verifica che il paese sia activeRegionCodes.

affectedRegionCodes può includere paesi in cui non vendi. Non devi intraprendere alcuna azione per questi paesi. Non influiscono sui paesi in activeRegionCodes.

Metodi

Gestisci i programmi fedeltà utilizzando i seguenti metodi:

Crea un programma fedeltà

Per creare un nuovo programma fedeltà per un account, utilizza il metodo loyaltyPrograms.create. Specifica dettagli come le descrizioni del programma, l'URL di registrazione e i livelli del programma con i relativi vantaggi e requisiti unici.

L'attributo obbligatorio program_label imposta l'identificatore univoco del programma fedeltà. Ad esempio, se fornisci l'etichetta my-rewards, viene generata una risorsa name di accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Ecco una richiesta di esempio:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Sostituisci {ACCOUNT_ID} con l'identificatore univoco del tuo account Merchant Center.

Ecco un esempio di risposta di una richiesta riuscita:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Recupera un programma fedeltà

Per recuperare i dettagli di un programma fedeltà di proprietà specifico, utilizza il metodo loyaltyPrograms.get.

Ecco una richiesta di esempio:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Sostituisci {ACCOUNT_ID} con il tuo ID account e {PROGRAM_LABEL} con l'etichetta univoca del programma fedeltà (ad esempio, my-rewards).

Ecco un esempio di risposta di una richiesta riuscita:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Elenca i programmi fedeltà

Per elencare tutti i programmi fedeltà di tua proprietà associati al tuo account, utilizza il metodo loyaltyPrograms.list.

Ecco una richiesta di esempio:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Ecco un esempio di risposta di una richiesta riuscita:

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Aggiorna un programma fedeltà

Per aggiornare un programma fedeltà esistente, utilizza il metodo loyaltyPrograms.update. Esegui un aggiornamento parziale utilizzando un update_mask o esegui una sostituzione completa omettendo la maschera. Ogni aggiornamento riuscito attiva una nuova revisione editoriale, quindi invia un aggiornamento solo quando un valore cambia.

Aggiornamento parziale con maschera di aggiornamento

Un update_mask consente di specificare i campi esatti da aggiornare. Vengono modificati solo i campi elencati nella maschera, mentre i campi non elencati rimangono invariati. Qualsiasi campo omesso dalla maschera di aggiornamento viene ignorato, anche se fornito nel corpo della richiesta.

La seguente richiesta di esempio aggiorna solo programDescriptions e advancedSettings:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

In questo esempio, il servizio ignora signupUrl perché non è incluso in update_mask. Il campo programDescriptions sostituisce completamente qualsiasi descrizione configurata in precedenza.

Ecco un esempio di risposta di una richiesta andata a buon fine:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Sostituzione completa senza maschera di aggiornamento

Se ometti il parametro update_mask, la richiesta esegue una sostituzione completa della configurazione del programma fedeltà.

Ecco una richiesta di esempio:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Ecco un esempio di risposta di una richiesta andata a buon fine:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Elimina un programma fedeltà

Per eliminare un programma fedeltà dal tuo account, utilizza il metodo loyaltyPrograms.delete.

Ecco una richiesta di esempio:

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

In caso di esito positivo, il corpo della risposta è vuoto.

Passaggi successivi

Indietro
Overview
Avanti
Manage customer loyalty data