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 principalmente los atributos de entrada de promoción obligatorios para aprobar las verificaciones de validación de datos:

Después de insertarla y actualizar una entrada de promoción, pueden pasar varios minutos antes de que se pueda 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 promoción para identificar la promoción de manera inequívoca. 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. Indica el país de segmentación que se utiliza 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. Es el 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 formato genérico (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, problemas de validación de datos, es decir, 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 reinserción (por ejemplo, la actualización de una promoción después de 30 días) se puede realizar con el versionNumber actual.

Si se impide la operación, se arrojará la excepción anulada.

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 al canal local que se usa en 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. Es el tipo de promoción. Usa este atributo para indicar si los clientes necesitan o no 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 debe usar con el campo offerType y debe cumplir con los requisitos mínimos.
longTitle

string

Obligatorio. Título largo de la promoción.
couponValueType

enum (CouponValueType)

Obligatorio. El atributo coupon value type para indicar el tipo de promoción que publica 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: Shopping Actions, Surfaces across Google o Local Spaces across Google. Para representar estos valores, usa FREE_LISTINGS, FREE_LOCAL_LISTINGS y LOCAL_INVENTORY_ADS. Para obtener más detalles, consulta Destino de las promociones
itemIdInclusion[]

string

Opcional. Filtro de producto por ID de artículo 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.
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. Filtra productos por ID de grupo de artículos para la promoción. Los atributos del filtro de productos solo se aplican cuando el atributo productos aptos para la promoción del producto [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 productos aptos para la promoción de productos aptos para la promoción productApplicability 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 productos aptos para la promoción de productos aptos para la promoción productApplicability está configurado en specific_products.
brandExclusion[]

string

Opcional. Filtra de productos por exclusión de marcas 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 productos aptos para la promoción de productos aptos para la promoción productApplicability está configurado en specific_products. exclusión de la promoción.
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 productos aptos para la promoción de productos aptos para la promoción productApplicability 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 descuento porcentual 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. Indica 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 de regalo de cortesía para 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. Representación de TimePeriod 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. Con este atributo, se especifica la fecha y el período en los 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. Si la promoción se aplica a todas las tiendas o solo a las 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 como 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 se establece en specific_stores.

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

string

Opcional. Códigos de tienda que se deben excluir de 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 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 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 porcentaje de descuento del n del 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 Compre una cantidad M y obtenga dinero de descuento. minimumPurchaseQuantity y moneyOffAmount deben estar presentes.
BUY_M_GET_PERCENT_OFF Compre una cantidad M y obtenga dinero de 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 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.

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 Se desconocen los códigos de tienda a los que 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. Son los destinos previstos de 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 compensación, 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 compensación, 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

El estado actual de la promoción.

Enumeraciones
STATE_UNSPECIFIED Se desconoce el estado de la promoción.
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. Es 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. Indica 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 descripción breve 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. Lista de códigos de país (ISO 3166-1 alpha-2) donde 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 desciende de nivel y es más probable 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 su cuenta de Merchant Center.

insert

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

list

 Muestra una lista de las promociones en tu cuenta de Merchant Center.