Descripción general de la API de Promociones

Usa promociones para mostrar ofertas especiales de los productos que vendes en Google. Las promociones se muestran en diferentes Propiedades de Google, como la Búsqueda de Google, Shopping y Chrome. Las promociones deben cumplir con ciertos criterios para que se aprueben. Para obtener más información, consulta Criterios de promoción.

Cuando agregas una promoción a tus productos, los compradores ven un vínculo de oferta especial. Por ejemplo, “15% de descuento” o “Envío gratis”. Los vínculos de ofertas pueden aumentar el atractivo de tus productos y animar a los compradores a realizar compras. Todas las promociones se aplican en el momento de la confirmación de compra o en el punto de venta.

Para obtener más información, consulta Conceptos básicos de las promociones.

Requisitos previos

Google requiere que proporciones información específica sobre tu empresa y tus productos antes de mostrar tus promociones. Debes tener lo siguiente:

Además, debes inscribir tu cuenta de comerciante en el programa Promociones. Si no estás seguro de si ya te inscribiste, consulta Merchant Center.

Si no estás inscrito, completa el formulario de solicitud. El equipo de promociones te avisará cuando todo esté listo para comenzar con la implementación.

Para obtener más información, consulta criterios y políticas de participación.

Cómo crear una fuente de datos

Puedes usar el método accounts.dataSources.create para crear una fuente de datos de promociones. Si hay una fuente de datos de promociones existente disponible, usa el método accounts.dataSources.list para recuperar todas las fuentes de datos. Luego, puedes usar el campo name de la fuente de datos de promociones para crear promociones.

En la siguiente solicitud, se muestra cómo crear una fuente de datos para agregar promociones:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Reemplaza lo siguiente:

  • {ACCOUNT_ID}: Es el identificador único de tu cuenta tal como aparece en la IU de Merchant Center.
  • {DISPLAY_NAME}: Es el nombre visible de la fuente de datos.
  • {CONTENT_LANGUAGE}: Es el código de idioma ISO 639-1 de dos letras de los productos en la fuente de datos.
  • {TARGET_COUNTRY}: Es el código de territorio de CLDR del país de segmentación en el que deseas que se vean las promociones.

Después de que la solicitud se ejecute correctamente, verás la siguiente respuesta que contiene detalles sobre la fuente de datos de promociones creada recientemente:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Crea promociones

Puedes usar el método accounts.promotions.insert para crear o actualizar una promoción. El método accounts.promotions.insert toma un recurso promotions y un nombre de fuente de datos como entrada. Devuelve la promoción nueva o actualizada, si se realiza correctamente.

Para crear una promoción, se requiere el nombre de la fuente de datos. También debes proporcionar valores para los siguientes campos en tu solicitud:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google revisa y aprueba tus promociones antes de distribuirlas. Para obtener más información, consulta el proceso de aprobación de promociones.

Te recomendamos que revises las políticas de promociones para asegurarte de que las promociones que crees agreguen valor y cumplan con las políticas de anuncios de Shopping.

En la siguiente solicitud, se muestra cómo crear una promoción en línea:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Para obtener información sobre las reglas aplicables para configurar el ID de promoción, consulta Requisitos mínimos para el atributo ID de promoción.

Los valores válidos para el campo obligatorio offerType son NO_CODE y GENERIC_CODE. Si no proporcionas uno de estos valores, la solicitud a la API falla con la respuesta HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Se muestra un mensaje de error similar si no proporcionas ninguno de los campos obligatorios.

Si no proporcionas un valor para el campo attributes.genericRedemptionCode, la solicitud fallará con la respuesta HTTP 400 [genericRedemptionCode] No redemption code provided.

Los valores de los campos promotion.attributes.promotionDisplayTimePeriod.startTime y promotion.attributes.promotionDisplayTimePeriod.endTime deben tener el formato yyyy-mm-ddThh:mm:ssZ. Asegúrate de reemplazar los valores de estos campos por fechas futuras.

Para obtener más información, consulta la especificación de datos de promociones.

Para conocer las prácticas recomendadas sobre cómo crear una promoción, consulta Prácticas recomendadas para las promociones.

Para obtener una lista de los atributos relacionados con las promociones, consulta Agrega atributos de datos estructurados.

Después de que la solicitud de creación de promoción se ejecute correctamente, es posible que la promoción tarde unos minutos en poder recuperarse con la API o en aparecer en Merchant Center.

A continuación, se incluyen algunas promociones de ejemplo que puedes usar para comenzar.

Una promoción local aplicable a todos los productos y todas las tiendas

En la siguiente solicitud de ejemplo, se muestra cómo crear una promoción local que se aplique a todos los productos de tu cuenta de Merchant Center y a todas las tiendas que se agregaron a tu cuenta vinculada del Perfil de Negocio.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

El campo productApplicability es obligatorio. Indica la aplicabilidad de la promoción a todos los productos o solo a algunos. Los valores admitidos son ALL_PRODUCTS y SPECIFIC_PRODUCTS. Para obtener más información, consulta Elige productos para tu promoción.

El campo couponValueType es obligatorio. Indica el tipo de promoción que estás publicando. Para obtener la lista de valores admitidos, consulta Tipo de valor del cupón. Según el tipo de valor del cupón que hayas seleccionado, algunos atributos son obligatorios.

El campo minimumPurchaseQuantity te permite establecer el valor de la cantidad mínima de compra necesaria para canjear la oferta de la promoción. Para obtener más información, consulta Cantidad mínima de compra para la promoción.

Del mismo modo, puedes usar el campo minimumPurchaseAmount para establecer el importe mínimo de compra necesario para canjear la promoción. Para obtener más información, consulta Importe mínimo de compra.

Para obtener más información sobre los valores que debes proporcionar para crear una promoción local, consulta Especificaciones de la fuente de datos para promociones locales.

Una promoción en línea que se aplica a productos seleccionados con un código de canje

En la siguiente solicitud de muestra, se muestra cómo crear una promoción en línea que se aplica a productos seleccionados con un código de canje.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Ver promociones

Para ver una promoción, usa accounts.promotions.get. Esta solicitud de GET es de solo lectura. Requiere tu merchantId y el ID de la promoción. El método GET muestra el recurso de promociones correspondiente.

Por ejemplo:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Reemplaza lo siguiente:

  • {ACCOUNT_ID}: Es el identificador único de tu cuenta de Merchant Center.
  • {PROMOTION_ID}: Es el identificador único de la promoción que deseas recuperar. El formato es {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Ten en cuenta que una promoción recién creada tarda unos minutos en poder recuperarse con la API.

Cómo ver una promoción local

En la siguiente solicitud de muestra, se recupera una promoción local cuyo ID de promoción es in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

Después de que la solicitud se realice correctamente, verás la siguiente respuesta:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

El campo moneyOffAmount de esta muestra proporciona el descuento que se ofrece en la promoción. Para obtener más información, consulta Importe del descuento monetario de una promoción.

El campo promotionUrl de este ejemplo proporciona el vínculo al sitio web de la tienda, en el que los compradores pueden encontrar más información sobre la promoción. Las promociones de anuncios del inventario local muestran un error si no incluyes el campo promotionUrl.

Ver una promoción en línea

La siguiente solicitud de ejemplo recupera una promoción en línea cuyo ID de promoción es online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

El campo itemIdInclusion que se usa en este ejemplo menciona los productos que son aptos para la promoción. Para obtener más información, consulta ID de producto para la promoción.

Cómo ver la lista de promociones

Puedes usar el método promotions.list para ver todas las promociones creadas.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

La respuesta contiene la lista de todas las promociones de tu cuenta. Para cada promoción, puedes ver detalles como promotionId, redemptionChannel, dataSource, promotionStatus y mucho más.

Cómo consultar el estado de una promoción

Para ver el estado de una promoción, consulta el atributo promotionStatus que muestra el método promotions.get o promotions.list.

El campo promotionStatus puede tener los siguientes valores:

  • IN_REVIEW: La promoción aún está en revisión.
  • REJECTED: Se rechazó el ascenso.
  • LIVE: La promoción está aprobada y activa.
  • STOPPED: La cuenta detiene la promoción.
  • EXPIRED: La promoción ya no está activa.
  • PENDING: La promoción no se detiene y se aprueban todas las opiniones, pero la fecha de activación es futura.
  • STATE_UNSPECIFIED: Estado de promoción desconocido.

Para comprender el proceso de aprobación de una promoción que creaste, consulta el proceso de aprobación de promociones.

Ejemplo de estado de la promoción

En los siguientes ejemplos, se muestra la diferencia entre las solicitudes que se realizan correctamente y las que fallan.

Falta la asignación de productos

En el siguiente cuerpo de respuesta, se muestra una promoción en línea que se rechazó debido a que falta la asignación de productos.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

Para solucionar problemas relacionados con las promociones rechazadas y aprender a evitar rechazos futuros, consulta Cómo solucionar problemas relacionados con promociones rechazadas.

Si no se aprueba una promoción que creaste, recibirás un correo electrónico en el que se mencionará el motivo del rechazo y las instrucciones para solucionar los problemas.

Promoción en proceso de evaluación

En el siguiente cuerpo de respuesta, se muestra una promoción que aún se está evaluando.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

Una promoción aprobada y publicada

En el siguiente cuerpo de respuesta, se muestra una promoción que los compradores pueden ver.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

Para obtener más información, consulta las Preguntas frecuentes sobre el estado de las promociones.

Más información