REST Resource: accounts.promotions

Recurso: Promoción

Representa una promoción. Consulta los siguientes artículos para obtener más detalles.

A continuación, se definen los atributos de entrada de promoción obligatorios para aprobar las verificaciones de validación de datos:

Después de insertar o actualizar una entrada de promoción, es posible que debas esperar varios minutos para poder recuperar la promoción final.

Representación JSON 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
Campos
name

string

Identificador. Es el nombre de la promoción. Formato: accounts/{account}/promotions/{promotion}
promotionId

string

Obligatorio. El usuario proporcionó el ID de la promoción para identificarla de forma única. Sigue los requisitos mínimos para evitar que se rechacen promociones.
contentLanguage

string

Obligatorio. Corresponde al código de idioma ISO 639-1 de dos letras de la promoción.

Las promociones están disponibles solo para idiomas seleccionados.
targetCountry

string

Obligatorio. Es el país de destino que se usa como parte del identificador único. Se representa como un código de territorio de CLDR.

Las promociones solo están disponibles en países seleccionados. Fichas gratuitas y anuncios de Shopping Anuncios del inventario local
redemptionChannel[]

enum (RedemptionChannel)

Obligatorio. Canal de canje de la promoción. Se requiere al menos un canal.
dataSource

string

Solo salida. Es la fuente de datos principal de la promoción.
attributes

object (Attributes)

Opcional. Es una lista de atributos de la promoción.
customAttributes[]

object (CustomAttribute)

Opcional. Una lista de atributos personalizados (proporcionados por el comercio). También se puede usar para enviar cualquier atributo de la especificación de datos en su forma genérica (por ejemplo, { "name": "size type", "value": "regular" }). Esto es útil para enviar atributos que la API no expone de forma explícita.
promotionStatus

object (PromotionStatus)

Solo salida. El estado de una promoción, los problemas de validación de datos, es decir, la información sobre una promoción calculada de forma asíncrona.
versionNumber

string (int64 format)

Opcional. Representa la versión existente (actualidad) de la promoción, que se puede usar para mantener el orden correcto cuando se realizan varias actualizaciones al mismo tiempo.

Si se establece, se impide la inserción cuando el número de versión es inferior al número de versión actual de la promoción existente. La inserción nuevamente (por ejemplo, la actualización de la promoción después de 30 días) se puede realizar con el versionNumber actual.

Si se evita la operación, se arrojará la excepción abortada.

RedemptionChannel

Es el canal de una promoción.

Enumeraciones
REDEMPTION_CHANNEL_UNSPECIFIED Indica que el canal no está especificado.
IN_STORE Indica que el canal está en la tienda. Es igual que el canal local que se usa para products.
ONLINE Indica que el canal está en línea.

Atributos

Atributos

Representación JSON 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
Campos
productApplicability

enum (ProductApplicability)

Obligatorio. La aplicabilidad de la promoción a todos los productos o solo a productos específicos.
offerType

enum (OfferType)

Obligatorio. Tipo de la promoción. Usa este atributo para indicar si los clientes necesitan un código de cupón para canjear tu promoción.
genericRedemptionCode

string

Opcional. Es un código de canje genérico para la promoción. Se usa con el campo offerType y debe cumplir con los requisitos mínimos.
longTitle

string

Obligatorio. Es el título largo de la promoción.
couponValueType

enum (CouponValueType)

Obligatorio. El atributo coupon_value_type para indicar el tipo de promoción que publicas Según el tipo de valor del cupón seleccionado, se requieren algunos atributos.
promotionDestinations[]

enum (DestinationEnum)

Obligatorio. Es la lista de destinos a los que se aplica la promoción. Si no especificas un destino con un valor admitido en tu fuente de datos, la promoción se mostrará de forma predeterminada en los anuncios de Shopping y las fichas gratuitas.

Es posible que, anteriormente, hayas enviado los siguientes valores como destinos para tus productos: Acciones de Shopping, Plataformas de Google o Plataformas locales de Google. Para representar estos valores, usa FREE_LISTINGS, FREE_LOCAL_LISTINGS y LOCAL_INVENTORY_ADS. Para obtener más detalles, consulta Destino de la promoción.
itemIdInclusion[]

string

Opcional. Filtro de productos por ID de artículo para la promoción Los atributos del filtro de productos solo se aplican cuando el atributo aplicabilidad del producto productApplicability de los productos aptos para la promoción está configurado en specific_products.
brandInclusion[]

string

Opcional. Filtro de productos por marca para la promoción Los atributos del filtro de productos solo se aplican cuando el atributo productos aptos para la promoción de productos aptos para la promoción productApplicability está configurado en specific_products.
itemGroupIdInclusion[]

string

Opcional. Filtro de productos por ID de grupo de artículos para la promoción Los atributos del filtro de productos solo se aplican cuando el atributo aplicabilidad del producto apto para la promoción [productApplicability] está configurado en specific_products.
productTypeInclusion[]

string

Opcional. Filtro de productos por tipo de producto para la promoción. Los atributos del filtro de productos solo se aplican cuando el atributo aplicabilidad del producto productApplicability de los productos aptos para la promoción está configurado en specific_products.
itemIdExclusion[]

string

Opcional. Filtro de producto por exclusión de ID de artículo para la promoción. Los atributos del filtro de productos solo se aplican cuando el atributo aplicabilidad del producto productApplicability de los productos aptos para la promoción está configurado en specific_products.
brandExclusion[]

string

Opcional. Filtro de productos por exclusión de marca para la promoción Los atributos del filtro de productos solo se aplican cuando el atributo productos aptos para la promoción de productos aptos para la promoción productApplicability está configurado en specific_products.
itemGroupIdExclusion[]

string

Opcional. Filtro de productos por ID de grupo de artículos Los atributos del filtro de productos solo se aplican cuando el atributo productApplicability de aplicabilidad del producto apto para la promoción está configurado en specific_products.
productTypeExclusion[]

string

Opcional. Filtro de productos por exclusión de tipo de producto para la promoción Los atributos del filtro de productos solo se aplican cuando el atributo aplicabilidad del producto productApplicability de los productos aptos para la promoción está configurado en specific_products.
minimumPurchaseAmount

object (Price)

Opcional. Es el importe mínimo de compra para la promoción.
minimumPurchaseQuantity

string (int64 format)

Opcional. Es la cantidad mínima de compra de la promoción.
limitQuantity

string (int64 format)

Opcional. Cantidad máxima de compra para la promoción.
limitValue

object (Price)

Opcional. Precio máximo del producto para la promoción.
percentOff

string (int64 format)

Opcional. Es el porcentaje de descuento que se ofrece en la promoción.
moneyOffAmount

object (Price)

Opcional. Es el importe de descuento que se ofrece en la promoción.
getThisQuantityDiscounted

string (int64 format)

Opcional. Es la cantidad de artículos con descuento en la promoción. El atributo se establece cuando couponValueType es igual a buy_m_get_n_money_off o buy_m_get_n_percent_off.
freeGiftValue

object (Price)

Opcional. Valor del regalo de cortesía de la promoción.
freeGiftDescription

string

Opcional. Descripción del regalo de cortesía de la promoción.
freeGiftItemId

string

Opcional. ID de artículo de regalo de cortesía de la promoción.
promotionEffectiveTimePeriod

object (Interval)

Obligatorio. TimePeriod representación de las fechas de entrada en vigencia de la promoción. Con este atributo, se especifica que la promoción se puede probar en tu tienda en línea durante este período.
promotionDisplayTimePeriod

object (Interval)

Opcional. Representación de TimePeriod de las fechas de visualización de la promoción. En este atributo, se especifica la fecha y hora en que se publicará la promoción en Google.com y en los anuncios de Shopping. Si no se especifica el atributo período de visualización de la promoción promotionDisplayTimePeriod, el período de vigencia de la promoción promotionEffectiveTimePeriod determinará la fecha y el período en los que se publicará la promoción en Google.com y en los anuncios de Shopping.
storeApplicability

enum (StoreApplicability)

Opcional. Indica si la promoción se aplica a todas las tiendas o solo a tiendas específicas. Las promociones de anuncios del inventario local arrojan un error si no se incluye aplicabilidad de la tienda. Se genera un error INVALID_ARGUMENT si storeApplicability se establece en ALL_STORES y storeCodesInclusion o score_code_exclusion se establece en un valor.
storeCodesInclusion[]

string

Opcional. Códigos de tienda que se deben incluir para la promoción Los atributos del filtro de tiendas solo se aplican cuando el atributo storeApplicability está configurado en specific_stores.

Código de tienda (el ID de la tienda de tu Perfil de Negocio) de la tienda física en la que se vende el producto Consulta las especificaciones de datos de inventario de productos locales para obtener más información.
storeCodesExclusion[]

string

Opcional. Códigos de tiendas que se excluirán para la promoción. Los atributos del filtro de tiendas solo se aplican cuando el atributo storeApplicability se establece en specific_stores.
promotionUrl

string

Opcional. Es la URL de la página del sitio del comercio en la que se muestra la promoción. Las promociones de anuncios del inventario local arrojan un error si no se incluye promotionUrl. La URL se usa para confirmar que la promoción es válida y se puede canjear.

ProductApplicability

A qué producto o lista de productos se aplica la promoción.

Enumeraciones
PRODUCT_APPLICABILITY_UNSPECIFIED Se desconocen los productos a los que se aplica la promoción.
ALL_PRODUCTS Se aplica a todos los productos.
SPECIFIC_PRODUCTS Solo se aplica a un solo producto o a una lista de productos.

OfferType

Es el tipo de oferta de una promoción.

Enumeraciones
OFFER_TYPE_UNSPECIFIED El tipo de oferta es desconocido.
NO_CODE Tipo de oferta sin código
GENERIC_CODE Tipo de oferta con un código Se requiere un código de canje genérico para la promoción cuando offerType = GENERIC_CODE.

CouponValueType

Es el tipo de valor del cupón de una promoción.

Enumeraciones
COUPON_VALUE_TYPE_UNSPECIFIED Indica que no se especificó el tipo de valor del cupón.
MONEY_OFF Tipo de valor del cupón de descuento.
PERCENT_OFF Es el tipo de valor del cupón de porcentaje de descuento.
BUY_M_GET_N_MONEY_OFF Compra una cantidad M y obtén N de descuento en el tipo de valor del cupón. minimumPurchaseQuantity y getThisQuantityDiscounted deben estar presentes. moneyOffAmount también debe estar presente.
BUY_M_GET_N_PERCENT_OFF Compre una cantidad M y obtenga un n% de descuento en el tipo de valor del cupón. minimumPurchaseQuantity y getThisQuantityDiscounted deben estar presentes. percent_off_percentage también debe estar presente.
BUY_M_GET_MONEY_OFF Comprar M para obtener un descuento. minimumPurchaseQuantity y moneyOffAmount deben estar presentes.
BUY_M_GET_PERCENT_OFF Compre una cantidad M y obtenga un descuento. minimumPurchaseQuantity y percent_off_percentage deben estar presentes.
FREE_GIFT Regalo de cortesía solo con la descripción.
FREE_GIFT_WITH_VALUE Regalo de cortesía con valor monetario.
FREE_GIFT_WITH_ITEM_ID Regalo de cortesía con ID de artículo
FREE_SHIPPING_STANDARD Tipo de valor del cupón de envío gratis estándar.
FREE_SHIPPING_OVERNIGHT Tipo de valor del cupón de envío gratis al día siguiente.
FREE_SHIPPING_TWO_DAY Tipo de valor del cupón de envío gratis en dos días.

DestinationEnum

Valores de destino

Enumeraciones
DESTINATION_ENUM_UNSPECIFIED No se especifica.
SHOPPING_ADS Shopping ads [anuncios de Shopping].
DISPLAY_ADS Anuncios gráficos.
LOCAL_INVENTORY_ADS Anuncios del inventario local.
FREE_LISTINGS Fichas gratuitas.
FREE_LOCAL_LISTINGS Fichas de productos locales gratuitas.
YOUTUBE_SHOPPING YouTube Shopping.
YOUTUBE_SHOPPING_CHECKOUT Confirmación de la compra en YouTube Shopping.
YOUTUBE_AFFILIATE Afiliado de YouTube.
FREE_VEHICLE_LISTINGS Fichas de vehículos gratuitas
VEHICLE_ADS Anuncios de vehículos.
CLOUD_RETAIL la venta minorista en la nube.
LOCAL_CLOUD_RETAIL Venta minorista local en la nube.

StoreApplicability

Códigos de tienda o listas de códigos de tienda a los que se aplica la promoción Solo para las promociones de anuncios del inventario local.

Enumeraciones
STORE_APPLICABILITY_UNSPECIFIED No se sabe a qué códigos de tienda se aplica la promoción.
ALL_STORES La promoción se aplica a todas las tiendas.
SPECIFIC_STORES La promoción se aplica solo a las tiendas especificadas.

PromotionStatus

Es el estado de la promoción.

Representación JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Campos
destinationStatuses[]

object (DestinationStatus)

Solo salida. Los destinos previstos para la promoción.
itemLevelIssues[]

object (ItemLevelIssue)

Solo salida. Una lista de problemas asociados con la promoción.
creationDate

string (Timestamp format)

Solo salida. Es la fecha en la que se creó la promoción en formato ISO 8601: fecha, hora y desplazamiento, por ejemplo, 2020-01-02T09:00:00+01:00 o 2020-01-02T09:00:00Z.
lastUpdateDate

string (Timestamp format)

Solo salida. Es la fecha en la que se actualizó por última vez el estado de la promoción en formato ISO 8601: fecha, hora y desplazamiento, por ejemplo, 2020-01-02T09:00:00+01:00 o 2020-01-02T09:00:00Z.

DestinationStatus

El estado del destino especificado.

Representación JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
Campos
reportingContext

enum (ReportingContextEnum)

Solo salida. Es el nombre del destino de la promoción.
status

enum (State)

Solo salida. El estado del destino especificado.

Estado

Es el estado actual de la promoción.

Enumeraciones
STATE_UNSPECIFIED Estado de promoción desconocido.
IN_REVIEW La promoción está en proceso de revisión.
REJECTED Se rechazó la promoción.
LIVE La promoción está aprobada y activa.
STOPPED El comercio detuvo la promoción.
EXPIRED La promoción ya no está activa.
PENDING La promoción no se detiene y se aprueban todas las revisiones, pero la fecha de activación es posterior a la actual.

ItemLevelIssue

El problema asociado con la promoción

Representación JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
Campos
code

string

Solo salida. El código de error del problema.
severity

enum (Severity)

Solo salida. Cómo afecta este problema a la publicación de la promoción
resolution

string

Solo salida. Si el comercio puede resolver el problema.
attribute

string

Solo salida. El nombre del atributo, si el problema se debe a un solo atributo.
reportingContext

enum (ReportingContextEnum)

Solo salida. El destino al que se aplica el problema.
description

string

Solo salida. Una breve descripción del problema en inglés.
detail

string

Solo salida. Una descripción detallada del problema en inglés.
documentation

string

Solo salida. La URL de una página web para ayudar a resolver este problema
applicableCountries[]

string

Solo salida. Es la lista de códigos de país (ISO 3166-1 alpha-2) en los que el problema se aplica a la oferta.

Gravedad

La gravedad del problema.

Enumeraciones
SEVERITY_UNSPECIFIED No se especifica.
NOT_IMPACTED Este problema representa una advertencia y no tiene un efecto directo en la promoción.
DEMOTED La promoción se degrada y, lo más probable, es que tenga un rendimiento limitado en los resultados de la búsqueda.
DISAPPROVED El problema rechaza la promoción.

Métodos

get

 Recupera la promoción de tu cuenta de Merchant Center.

insert

 Inserta una promoción para tu cuenta de Merchant Center.

list

 Muestra las promociones de tu cuenta de Merchant Center.