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 previsti dal tuo programma fedeltà possono essere visualizzati nelle schede senza costi, negli annunci Shopping e negli annunci di inventario locale sulle varie 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 conto dei commercianti possono configurare e gestire i programmi fedeltà in modo programmatico utilizzando LoyaltyProgramService. Questo servizio consente di creare, recuperare, elencare, aggiornare ed eliminare i programmi fedeltà.

Importante: il servizio è disponibile solo per commercianti selezionati. Contatta il team di assistenza per esprimere il tuo interesse a partecipare inviando una richiesta di lista consentita nel modulo di assistenza dell'API Shopping in Qual è il problema/la domanda? > Richiesta di inclusione nella lista consentita > Altro.

Per ulteriori informazioni sui requisiti aziendali e sulle linee guida delle norme, consulta Informazioni sul programma fedeltà del commerciante nel Centro assistenza Merchant Center.

Concetti fondamentali

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

• Identificatore a livello di account:l'API Merchant identifica i programmi fedeltà in base all'ID account Merchant Center proprietario.
• Limite per programma singolo: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 editoriale: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.
• 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.
• Requisiti dei livelli:l'adesione ai livelli può essere senza costi, richiedere una quota di abbonamento, una soglia di spesa o una carta di credito con il brand del commerciante. I livelli basati sull'occupazione (ad esempio studente o militare) non sono supportati.
• Vantaggi e benefici: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 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:
  • Interfaccia utente di Merchant Center:segui le istruzioni riportate in Configurare un programma fedeltà nel Centro assistenza Merchant Center.
  • API secondaria Programs:abilita il programma in modo programmatico come descritto in Abilitare i programmi nell'API secondaria Programs.

Di seguito è riportata una richiesta di esempio per abilitare il componente aggiuntivo del programma fedeltà utilizzando l'API secondaria 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

Metodi

Gestisci i programmi fedeltà utilizzando i seguenti metodi:

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

Creare un programma fedeltà

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

L'program_label obbligatorio imposta l'identificatore univoco del programma fedeltà. Ad esempio, se fornisci l'etichetta my-rewards, ottieni 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.

Di seguito è riportato un esempio di risposta a 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"
  ]
}

Recuperare un programma fedeltà

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

Nota: anche se il componente aggiuntivo Programma fedeltà non è stato attivato, questo endpoint risponde comunque con un programma fedeltà corrispondente senza restituire un errore.

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 l'ID account e {PROGRAM_LABEL} con l'etichetta univoca del programma fedeltà (ad esempio, my-rewards).

Di seguito è riportato un esempio di risposta a 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 programmi fedeltà

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

Nota: questo metodo elenca solo i programmi fedeltà di proprietà diretta dell'account specificato, non i programmi associati ai subaccount. Anche se il componente aggiuntivo del programma fedeltà è disattivato, questo endpoint risponde con i programmi esistenti senza restituire un errore.

Ecco una richiesta di esempio:

HTTP

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

Di seguito è riportato un esempio di risposta a 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"
      ]
    }
  ]
}

Aggiornare 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.

Importante: quando aggiorni un programma fedeltà, i campi ripetuti (ad esempio programDescriptions e tiers) non possono essere aggiornati sul posto. Qualsiasi campo ripetuto incluso in un aggiornamento sostituisce l'intero elenco esistente. Per evitare perdite di dati involontarie, invia prima una richiesta get per recuperare i valori attuali prima di aggiornare i campi ripetuti.

Aggiornamento parziale con maschera di aggiornamento

Un update_mask ti 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 una risposta di esempio a 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": [
    "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 una risposta di esempio a una richiesta riuscita:

{
  "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"
  ]
}

Eliminare 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

• Per associare i singoli acquirenti ai livelli del tuo programma fedeltà per la personalizzazione organica sulla Ricerca Google, consulta la guida al servizio Customer Match per i programmi fedeltà.
• Per attivare o disattivare i programmi per lo shopping per il tuo account, consulta la guida alla sub-API Programs.
• Per informazioni dettagliate sulla configurazione dell'attività, sulle norme redazionali e sui report, consulta Informazioni sul programma fedeltà del commerciante nella Guida di Merchant Center.
• Per esplorare i metodi API e le definizioni delle risorse, consulta il riferimento API Merchant.