Descripción general de los programas de lealtad

Muestra los beneficios de tu tienda en Google con los 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 el recurso 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 inclusión en la lista de entidades permitidas en el formulario de asistencia de la API de Shopping en ¿Cuál es el problema o la pregunta? > Solicitud de inclusión en la lista de entidades permitidas > Otro.

Para obtener más información sobre los requisitos de la empresa y los lineamientos de las políticas, consulta el artículo 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 se deben configurar 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 cuentas secundarias. Los proveedores de lealtad externos con acceso autorizado a la cuenta de un comercio pueden administrar el programa en su nombre.

• 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. Cada actualización correcta envía el programa de vuelta a la fila de revisión, incluso si la actualización no cambia nada importante. Google oculta el programa a los compradores durante el proceso de revisión. La revisión puede tardar hasta 48 horas.

• Regiones admitidas: Los programas de lealtad de comercios están disponibles en los países admitidos, incluidos Alemania, Australia, Brasil, Canadá, Corea del Sur, España, Estados Unidos, Francia, India, Italia, Japón, México, Países Bajos y Reino Unido.

• Regiones activas: El regionCodes de un programa de lealtad debe ser un subconjunto de las activeRegionCodes de accounts/{ACCOUNT_ID}/programs/loyalty. De lo contrario, las solicitudes de creación, actualización y eliminación fallarán con un error LOYALTY_PROGRAM_DISABLED. Google activa un país admitido cuando se habilita el complemento del programa de lealtad y la cuenta cumple con los requisitos de elegibilidad en ese país. Por ejemplo, la cuenta es apta si el programa de fichas gratuitas está habilitado y una fuente de datos de productos principal segmenta los anuncios para el país del destino FREE_LISTINGS. Para averiguar por qué un país no está activo, consulta Verifica las regiones activas.

• Requisitos de los niveles: Los niveles pueden no tener costo para unirse, 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 de estudiantes o militares).

• Ventajas y beneficios: 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, un 5% o 5 unidades monetarias 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 en tu cuenta. Puedes habilitar el complemento con cualquiera de las siguientes opciones:

  • IU de Merchant Center: Sigue las instrucciones que se indican en Configura un programa de lealtad en la Ayuda de Merchant Center.
  • Sub-API de programas: Habilita el programa de manera programática como se describe en Habilita programas en la sub-API de programas. El método accounts.programs.enable requiere acceso de administrador.

• Los países en los que quieras ofrecer tu programa de lealtad deben estar activos para tu cuenta. Para saber qué países están activos, consulta Verifica las regiones activas.

Esta es 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

Verifica las regiones activas

Después de habilitar el complemento del programa de lealtad, llama al método accounts.programs.get para accounts/{ACCOUNT_ID}/programs/loyalty. La respuesta muestra dónde puedes usar los programas de lealtad y por qué otros países admitidos están inactivos.

Nota: La API de Merchant usa el término región porque estos campos contienen códigos de región de CLDR. Otros programas pueden usar el código de región 001 para todo el mundo. En el caso de los programas de lealtad, cada código de región es un código de país, como US o JP.

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

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

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

Esta es una respuesta de ejemplo para una cuenta que habilitó el complemento y es apta solo en Estados Unidos:

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

En esta respuesta, observa los siguientes campos:

• activeRegionCodes: Son los países que puedes usar en el regionCodes de tu programa de lealtad. En el ejemplo anterior, solo US está activo.
• unmetRequirements: Es el motivo por el que los demás países admitidos están inactivos. En el caso de los programas de lealtad, este es el requisito IS_ELIGIBLE_FOR_LOYALTY.
  • affectedRegionCodes: Son los países admitidos en los que la cuenta no es apta.
  • documentationUri: Es un vínculo a los requisitos de elegibilidad.

En el ejemplo anterior, aún no puedes usar los países de affectedRegionCodes. Si el regionCodes de tu programa de lealtad incluye uno de ellos, las solicitudes de creación, actualización y eliminación fallarán con un error LOYALTY_PROGRAM_DISABLED. Para activar un país, sigue estos pasos:

1. Hacer que la cuenta sea apta en ese país Por ejemplo, habilita el programa de fichas gratuitas y establece una fuente de datos de productos principal para segmentar el país para el destino FREE_LISTINGS. Para conocer todas las formas de cumplir con los requisitos, consulta los requisitos de elegibilidad.
2. Vuelve a llamar a accounts.programs.get y verifica que el país esté en activeRegionCodes.

affectedRegionCodes puede incluir países en los que no vendes tus productos. No es necesario que realices ninguna acción para estos países. No afectan a los países de activeRegionCodes.

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 elemento program_label obligatorio establece el identificador único del programa de lealtad. Por ejemplo, si proporcionas 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 propio específico, usa el método loyaltyPrograms.get.

Nota: Incluso si no se habilitó el complemento del programa de lealtad, este extremo seguirá respondiendo con un programa de lealtad coincidente sin devolver 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 tu ID de 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 los 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 pertenecen directamente a 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"
      ]
    }
  ]
}

Cómo actualizar un programa de lealtad

Para actualizar un programa de lealtad existente, usa el método loyaltyPrograms.update. Realiza una actualización parcial con una update_mask o un reemplazo completo omitiendo la máscara. Cada actualización correcta activa una nueva revisión editorial, por lo que debes enviar una actualización solo cuando cambie un valor.

Importante: Cuando actualizas un programa de lealtad, los campos repetidos (como programDescriptions y tiers) no se pueden actualizar in situ. 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 indican en la máscara, mientras que los campos que no se indican permanecen sin cambios. Se ignora cualquier campo que se omita de la máscara de actualización, incluso si se proporciona en el cuerpo de la solicitud.

Nota: Incluso si regionCodes no está en updateMask, el servicio verifica el regionCodes actual del programa con activeRegionCodes. Si un país actual ya no está activo, la actualización falla con un error LOYALTY_PROGRAM_DISABLED. Para actualizar el programa, incluye region_codes en update_mask y solo incluye los países activos en 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 con anterioridad.

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 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 de lealtad.
• Para habilitar o inhabilitar los programas de compras en tu cuenta, consulta la guía de la API secundaria de programas.
• Para obtener detalles sobre la configuración de la empresa, las políticas editoriales y los informes, consulta el artículo 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.