Descripción general de los programas de lealtad

Muestra los beneficios de tu tienda en Google con programas de lealtad. Puedes enviar diversos beneficios, como envío gratis, puntos canjeables y precios exclusivos para miembros. Los beneficios de tu programa de lealtad pueden aparecer en las fichas gratuitas, los anuncios de Shopping y los anuncios del inventario local en las plataformas de Google, como la Búsqueda de Google, la pestaña de Shopping y la Billetera de Google.

Con la API de Merchant, los comercios y los proveedores de lealtad externos que actúan en nombre de los comercios pueden configurar y mantener programas de lealtad de forma programática con la LoyaltyProgramService. Este servicio te permite crear, recuperar, enumerar, actualizar y borrar programas de lealtad.

Importante: El servicio solo está disponible para comercios seleccionados. Comunícate con el equipo de asistencia al cliente para expresar tu interés en participar. Para ello, envía una solicitud de lista de entidades permitidas en el formulario de asistencia al cliente de la API de Shopping en ¿Cuál es el problema o la pregunta? > Solicitud de lista de entidades permitidas > Otro.

Para obtener más información sobre los requisitos comerciales y los lineamientos de las políticas, consulta Acerca del programa de lealtad para comercios en el Centro de ayuda de Merchant Center.

Conceptos clave

Ten en cuenta los siguientes conceptos y limitaciones cuando trabajes con programas de lealtad:

• Identificador a nivel de la cuenta: La API de Merchant identifica los programas de lealtad por el ID de la cuenta de Merchant Center propietaria.
• Límite de un solo programa: La API de Merchant solo admite un programa de lealtad por cuenta de comerciante.
• Propiedad directa de la cuenta: Los programas de lealtad deben configurarse directamente en la cuenta de comerciante de destino (accounts/{ACCOUNT_ID}). El servicio no admite la administración de programas de lealtad a nivel de la cuenta avanzada para las subcuentas. Los proveedores de lealtad externos con acceso autorizado a la cuenta de un comercio pueden administrar el programa en nombre del comercio.
• Revisión editorial: Después de crear o actualizar un programa de lealtad, este se somete a una revisión. El campo review_result.review_status indica si el programa es UNDER_REVIEW, APPROVED o REJECTED.
• Regiones admitidas: Los programas de lealtad para comercios están disponibles en los países admitidos, incluidos Alemania, Australia, Brasil, Canadá, Corea del Sur, España, Estados Unidos, Francia, India, Italia, México, Países Bajos y Reino Unido.
• Requisitos de nivel: Los niveles pueden no tener costo de inscripción, requerir una tarifa de membresía, requerir un umbral de inversión o requerir una tarjeta de crédito de la marca del comercio. No se admiten los niveles basados en la ocupación (como los niveles para estudiantes o militares).
• Beneficios y ventajas: Los programas admiten envíos gratis, puntos canjeables y precios para miembros. En los anuncios, los precios para miembros requieren un descuento de al menos el 5% o 5 unidades de moneda por debajo del precio normal o de oferta.

Requisitos previos

Antes de administrar programas de lealtad con la API de Merchant, asegúrate de cumplir con los siguientes requisitos:

• Debes tener una cuenta de Merchant Center activa (o acceso autorizado a la cuenta del comercio si eres un proveedor de lealtad externo).
• Habilita el complemento del programa de lealtad para tu cuenta. Puedes habilitar el complemento con cualquiera de las siguientes opciones:
  • IU de Merchant Center: Sigue las instrucciones en Configura un programa de lealtad en la Ayuda de Merchant Center.
  • Sub-API de Programs: Habilita el programa de forma programática como se describe en Habilita programas en la sub-API de Programs.

A continuación, se muestra una solicitud de ejemplo para habilitar el complemento del programa de lealtad con la sub-API de 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

Métodos

Administra los programas de lealtad con los siguientes métodos:

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

Crea un programa de lealtad

Para crear un programa de lealtad nuevo para una cuenta, usa el método loyaltyPrograms.create. Especifica detalles como las descripciones del programa, la URL de registro y los niveles del programa con sus beneficios y requisitos únicos.

El program_label obligatorio establece el identificador único del programa de lealtad. Por ejemplo, si se proporciona la etiqueta my-rewards, se genera un recurso name de accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

A continuación, se muestra una solicitud de ejemplo:

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

Reemplaza {ACCOUNT_ID} por el identificador único de tu cuenta de Merchant Center.

Esta es una respuesta de ejemplo de una solicitud correcta:

{
  "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 programa de lealtad

Para recuperar los detalles de un programa de lealtad específico de tu propiedad, usa el método loyaltyPrograms.get.

Nota: Incluso si no se habilitó el complemento del programa de lealtad, este extremo sigue respondiendo con un programa de lealtad coincidente sin mostrar un error.

A continuación, se muestra una solicitud de ejemplo:

HTTP

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

Reemplaza {ACCOUNT_ID} por el ID de tu cuenta y {PROGRAM_LABEL} por la etiqueta única del programa de lealtad (por ejemplo, my-rewards).

Esta es una respuesta de ejemplo de una solicitud correcta:

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

Enumera programas de lealtad

Para enumerar todos los programas de lealtad propios asociados con tu cuenta, usa el método loyaltyPrograms.list.

Nota: Este método solo enumera los programas de lealtad que son propiedad directa de la cuenta especificada, no los programas asociados con cuentas secundarias. Incluso si el complemento del programa de lealtad está inhabilitado, este extremo responde con los programas existentes sin mostrar un error.

A continuación, se muestra una solicitud de ejemplo:

HTTP

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

Esta es una respuesta de ejemplo de una solicitud correcta:

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

Actualiza un programa de lealtad

Para actualizar un programa de lealtad existente, usa el método loyaltyPrograms.update. Realiza una actualización parcial con un update_mask o un reemplazo completo omitiendo la máscara.

Importante: Cuando actualizas un programa de lealtad, los campos repetidos (como programDescriptions y tiers) no se pueden actualizar en el mismo lugar. Cualquier campo repetido incluido en una actualización reemplaza toda la lista existente. Para evitar la pérdida de datos no deseada, primero envía una solicitud get para recuperar los valores actuales antes de actualizar los campos repetidos.

Actualización parcial con máscara de actualización

Un update_mask te permite especificar los campos exactos que se deben actualizar. Solo se modifican los campos que se enumeran en la máscara, mientras que los campos no enumerados permanecen sin cambios. Se ignorará cualquier campo omitido de la máscara de actualización, incluso si se proporciona en el cuerpo de la solicitud.

En la siguiente solicitud de ejemplo, solo se actualizan programDescriptions y 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"
}

En este ejemplo, el servicio ignora signupUrl porque no se incluye en update_mask. El campo programDescriptions reemplaza por completo cualquier descripción configurada anteriormente.

Esta es una respuesta de ejemplo de una solicitud exitosa:

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

Reemplazo completo sin máscara de actualización

Cuando omites el parámetro update_mask, la solicitud realiza un reemplazo completo de la configuración del programa de lealtad.

A continuación, se muestra una solicitud de ejemplo:

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

Esta es una respuesta de ejemplo de una solicitud exitosa:

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

Cómo borrar un programa de lealtad

Para borrar un programa de lealtad de tu cuenta, usa el método loyaltyPrograms.delete.

A continuación, se muestra una solicitud de ejemplo:

HTTP

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

Si se ejecuta correctamente, el cuerpo de la respuesta está vacío.

Próximos pasos

• Para asociar a los compradores individuales con los niveles de tu programa de lealtad para la personalización orgánica en la Búsqueda de Google, consulta la guía del servicio de Segmentación por clientes leales.
• Para habilitar o inhabilitar los programas de compras en tu cuenta, consulta la guía de la sub-API de Programs.
• Para obtener detalles sobre la configuración de la empresa, las políticas editoriales y los informes, consulta Acerca del programa de lealtad de comercios en la Ayuda de Merchant Center.
• Para explorar los métodos de la API y las definiciones de recursos, consulta la referencia de la API de Merchant.