API de ofertas

La API de ofertas se encuentra en un programa en fase beta cerrado al que solo se puede acceder mediante invitación. Contacta con tu representante de Meta para obtener acceso si has recibido la invitación para participar en el programa.

Esta API te permite añadir información sobre ofertas a los catálogos de productos para habilitar la promoción comercial en las ofertas en Facebook e Instagram. En el caso de los vendedores que tengan habilitada la finalización de compra con Facebook o Instagram, los compradores podrán canjear las ofertas directamente en la familia de aplicaciones de Meta.

Crear ofertas

Puedes crear ofertas mediante una lista de ofertas o manualmente a través de Commerce Manager.

Lista

Para crear una nueva lista de ofertas, realiza una solicitud POST al perímetro /{product_catalog_id}/product_feeds y establece feed_type en OFFER. Al publicar en este perímetro, se crea una lista de productos de tipo oferta para el catálogo especificado en el campo product_catalog_id.

Una vez creada la lista de ofertas, puedes subir los datos de las ofertas mediante una solicitud POST al perímetro /{product_feed_id}/uploads.

Columnas de la lista

Puedes establecer la mayoría de los campos disponibles que se indican a continuación como columnas en el archivo de lista. Los únicos campos que no se pueden establecer durante la creación son los marcados como “solo lectura”.

Glosario

Conjuntos de productos

Un conjunto de productos es un grupo de artículos relacionados en un catálogo de productos.

Artículos objetivo de la oferta

Se trata de los productos para los que una oferta es válida.

Requisitos previos de la oferta

Se trata de los requisitos previos que se deben cumplir para poder aplicar la oferta. Por ejemplo, puedes determinar que la oferta solo sea válida cuando los usuarios compren una cantidad mínima de productos específica o alcancen una cantidad o un valor subtotales específicos de dichos productos. Actualmente, los productos con requisitos previos se derivan de los productos objetivo. Por ejemplo, una oferta del 20 % de descuento en todos los zapatos quiere decir que los requisitos de cantidades o subtotales mínimos deben cumplirse con los zapatos del carrito.

Tipo de aplicación de la oferta

El tipo de aplicación de la oferta especifica cómo se aplica la oferta al finalizar la compra, ya sea en tu propio sitio web o en la finalización de compra de Facebook. Por ejemplo, el tipo de aplicación se puede utilizar para determinar si una oferta se aplica automáticamente durante la finalización de la compra o si hace falta un código de cupón para canjearla. El tipo de aplicación también determina la forma en que una oferta se combina con otras ofertas. Para obtener más información, consulta Combinar ofertas.

Campos básicos

Los campos a continuación se pueden utilizar para configurar todos los tipos de oferta.

Campo Descripción

Campo	Descripción
`id` Tipo: `numeric string`	Solo lectura. Identificador único (identificador de Facebook) del artículo.
`offer_id` Tipo: `string`	Obligatorio. Identificador proporcionado por el vendedor para la oferta. Este campo se utiliza para identificar de manera única una oferta en un catálogo.
`title` Tipo: `string`	Opcional. Título para el artículo de la oferta. Actualmente, este título solo se utiliza para ayudar a identificar las ofertas en Commerce Manager; no se muestra a los compradores.
`description` Tipo: `string`	Solo lectura. Descripción generada automáticamente de la oferta.
`application_type` Tipo: `enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}`	Obligatorio. Determina cómo y cuándo se aplica la oferta. Las opciones disponibles son las siguientes: `SALE`: los artículos marcan el precio con descuento directamente y muestran el precio anterior tachado a los compradores. Estas ofertas no necesitan que el comprador cumpla ningún requisito previo y no se ven afectadas por otros artículos durante la finalización de compra. Siempre se elige la rebaja que dé lugar al precio más bajo para un artículo, ya que las ofertas nunca se combinan. Las rebajas se pueden combinar con otros tipos de ofertas, pero siempre se aplican primero. Si un producto ya tiene establecido el campo `sale_price`, el precio final se calcula usando el valor de `sale_price` como precio base. `AUTOMATIC_AT_CHECKOUT`: la oferta se aplica automáticamente durante la finalización de compra cuando el comprador cumple los criterios de canje necesarios. Esta oferta tiene una configuración que evita que se califique como rebaja. Solo se puede combinar con ofertas de rebajas. Puede haber hasta 25 ofertas de este tipo activas al mismo tiempo. `BUYER_APPLIED`: esta oferta se aplica durante la finalización de compra en base a una acción del comprador, como puede ser introducir un código promocional. Actualmente, estas ofertas no se pueden combinar entre sí ni con ofertas que se apliquen automáticamente durante la finalización de compra. Requiere proporcionar uno de estos campos: `public_coupon_code` o `coupon_codes`.
`coupon_codes` Tipo: `Array<string>`	Lista de códigos de cupón que no distingue entre mayúsculas y minúsculas y que los clientes utilizan durante la finalización de compra para canjear la oferta. Se permite un máximo de 100 cupones. Por ejemplo: `["10OFF", "HOLIDAY_SALE"]` Los códigos de cupón solo se pueden especificar cuando el valor de `application_type` es `BUYER_APPLIED`. Si se establece este campo, el valor de `public_coupon_code` debe ser nulo.
`public_coupon_code` Tipo: `string`	Opcional. Un solo código de cupón que no distingue entre mayúsculas y minúsculas que se promocionará con la oferta y se rellenará automáticamente durante la finalización de compra si el comprador cumple los requisitos previos de la oferta. De manera predeterminada, las ofertas con códigos de cupón no se promocionan de forma visible a los compradores en las plataformas de compra de Facebook e Instagram como las páginas de detalles de productos. Esto es para evitar que los códigos privados o secretos se filtren a los compradores de forma involuntaria. Puedes modificar este comportamiento especificando un código de cupón público para su uso como promoción comercial de la oferta. Las ofertas con códigos públicos se mostrarán igual que las ofertas cuyo valor de `application_type` sea `AUTOMATIC_AT_CHECKOUT`, pero también incluirán el texto del código. Los códigos de cupón públicos no pueden exceder los 20 caracteres de longitud y tu catálogo solo puede contener un máximo de diez ofertas activas con códigos de cupón al mismo tiempo. Los códigos de cupón públicos solo se pueden configurar cuando el valor de `application_type` es `BUYER_APPLIED`. Si se establece este campo, el valor de `coupon_codes` debe ser nulo.
`start_date_time` Tipo: `timestamp`	Obligatorio. Marca de tiempo Unix en segundos, que indica cuándo empieza la oferta. Los datos de entrada pueden ser una marca de tiempo Unix en segundos o una cadena de fecha en formato ISO-8601 (p. ej., 2021-09-25T12:34:56Z).
`end_date_time` Tipo: `timestamp`	Opcional. El valor predeterminado es `null`. Marca de tiempo Unix en segundos, que indica cuándo finaliza la oferta. Si se deja vacío o con el valor `null`, la oferta no tendrá fecha final. Los datos de entrada pueden ser una marca de tiempo Unix en segundos o una cadena de fecha en formato ISO-8601 (p. ej., 2021-09-25T12:34:56Z).
`min_quantity` Tipo: `int64`	Opcional. El valor predeterminado es 0. Utiliza este campo si quieres que la oferta solo sea válida cuando el cliente compre un número mínimo de productos. Este campo representa el número de productos que el cliente debe comprar para que la oferta sea válida. Por ejemplo: “Compra cinco camisas y consigue un 20 % de descuento”. Solo se puede establecer el valor de `min_quantity` o el de `min_subtotal`.
`min_subtotal` Tipo: `string`	Opcional. El valor predeterminado es `null`. Utiliza este campo si quieres que la oferta solo sea válida cuando el pedido del cliente alcance un valor subtotal específico. El subtotal de los productos con requisitos previos debe ser igual o mayor que este valor para que la oferta se aplique. Si no se establece ningún producto con requisitos previos explícitos, los productos objetivo se utilizarán como productos con requisitos previos. Este campo debe tener como formato la cantidad seguida del código de divisa ISO de tres dígitos, con un espacio entre la cantidad y la divisa. Por ejemplo, la cadena “30,99 USD” representa un requisito previo de 30,99 USD como subtotal para que la oferta se aplique. Solo se puede establecer el valor de `min_quantity` o el de `min_subtotal`.
`redeem_limit_per_user` Tipo: `int64`	Opcional. El valor predeterminado es 0 (ilimitado). Número máximo de veces que un único usuario puede utilizar la oferta. Establece el valor de este campo en “1” para crear un código de cupón de un solo uso. Este campo solo se debe establecer si el valor de `application_type` es `BUYER_APPLIED`.
`value_type` Tipo: `enum {FIXED_AMOUNT, PERCENTAGE}`	Obligatorio. Tipo de descuento que proporciona la oferta. Las opciones disponibles son las siguientes: `FIXED_AMOUNT`: aplica un descuento con el valor tomado de `fixed_amount_off`. `PERCENTAGE`: aplica un porcentaje de descuento con el valor tomado de `percent_off`.
`fixed_amount_off` Tipo: `string`	Obligatorio si el valor de `value_type` está establecido en `FIXED_AMOUNT`. Cantidad de descuento de la oferta. El formato debe ser la cantidad seguida del código de divisa ISO de tres dígitos, con un espacio entre la cantidad y la divisa. Por ejemplo, la cadena “30,99 USD” representa un descuento de 30,99 USD. Este campo solo se debe establecer si el valor de `value_type` es `FIXED_AMOUNT`.
`percent_off` Tipo: `int64`	Obligatorio si el valor de `value_type` está establecido en `PERCENTAGE`. Porcentaje de descuento de la oferta. Debe ser un entero entre 0 y 100. Por ejemplo, el valor “30” representa un descuento del 30 %. Este campo solo se debe establecer si el valor de `value_type` es `PERCENTAGE`.
`target_granularity` Tipo: `enum {ITEM_LEVEL, ORDER_LEVEL}`	Obligatorio. Granularidad con la que se aplica el descuento de la oferta. Las opciones disponibles son las siguientes: `ITEM_LEVEL`: representa un descuento que se aplica a cada artículo objetivo del carrito. `ORDER_LEVEL`: representa un descuento que se aplica al conjunto de todos los artículos objetivo del carrito. Por ejemplo, si tienes una oferta de “30 USD de descuento en zapatos” con tres pares de zapatos en el carrito, `ITEM_LEVEL` aplicará un descuento de 30 USD a cada par de zapatos (un valor total de 90 USD), mientras que `ORDER_LEVEL` aplicará un descuento de 30 USD a la suma de los tres pares de zapatos (un valor máximo de 30 USD). Ten en cuenta que es posible que las ofertas con la granularidad `ORDER_LEVEL` den lugar a asignaciones de descuentos en la compra que no se dividen uniformemente entre los artículos del pedido. Gestionar estas asignaciones desiguales de descuentos puede conllevar una mayor complejidad a la hora de procesar los pedidos o en caso de reembolsos.
`offer_terms` Tipo: `string`	Opcional. Términos y condiciones adicionales que establecen el uso de la oferta por parte del comprador. 2500 caracteres como máximo. Facebook generará automáticamente las condiciones para describir la oferta en función de la configuración de la misma. Además de estas condiciones, puedes utilizar el campo `offer_terms` para añadir más detalles que describan tus propias condiciones de la oferta. Estas condiciones aparecerán debajo de las condiciones de la oferta de Facebook. El contenido debe cumplir nuestras políticas de contenido.

id

Tipo: numeric string

Solo lectura.

Identificador único (identificador de Facebook) del artículo.

offer_id

Tipo: string

Obligatorio.

Identificador proporcionado por el vendedor para la oferta.

Este campo se utiliza para identificar de manera única una oferta en un catálogo.

title

Tipo: string

Opcional.

Título para el artículo de la oferta.

Actualmente, este título solo se utiliza para ayudar a identificar las ofertas en Commerce Manager; no se muestra a los compradores.

description

Tipo: string

Solo lectura.

Descripción generada automáticamente de la oferta.

application_type

Tipo: enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}

Obligatorio.

Determina cómo y cuándo se aplica la oferta. Las opciones disponibles son las siguientes:

SALE: los artículos marcan el precio con descuento directamente y muestran el precio anterior tachado a los compradores. Estas ofertas no necesitan que el comprador cumpla ningún requisito previo y no se ven afectadas por otros artículos durante la finalización de compra. Siempre se elige la rebaja que dé lugar al precio más bajo para un artículo, ya que las ofertas nunca se combinan. Las rebajas se pueden combinar con otros tipos de ofertas, pero siempre se aplican primero. Si un producto ya tiene establecido el campo sale_price, el precio final se calcula usando el valor de sale_price como precio base.
AUTOMATIC_AT_CHECKOUT: la oferta se aplica automáticamente durante la finalización de compra cuando el comprador cumple los criterios de canje necesarios. Esta oferta tiene una configuración que evita que se califique como rebaja. Solo se puede combinar con ofertas de rebajas. Puede haber hasta 25 ofertas de este tipo activas al mismo tiempo.
BUYER_APPLIED: esta oferta se aplica durante la finalización de compra en base a una acción del comprador, como puede ser introducir un código promocional. Actualmente, estas ofertas no se pueden combinar entre sí ni con ofertas que se apliquen automáticamente durante la finalización de compra. Requiere proporcionar uno de estos campos: public_coupon_code o coupon_codes.

coupon_codes

Tipo: Array<string>

Lista de códigos de cupón que no distingue entre mayúsculas y minúsculas y que los clientes utilizan durante la finalización de compra para canjear la oferta. Se permite un máximo de 100 cupones. Por ejemplo: ["10OFF", "HOLIDAY_SALE"]

Los códigos de cupón solo se pueden especificar cuando el valor de application_type es BUYER_APPLIED.

Si se establece este campo, el valor de public_coupon_code debe ser nulo.

public_coupon_code

Tipo: string

Opcional.

Un solo código de cupón que no distingue entre mayúsculas y minúsculas que se promocionará con la oferta y se rellenará automáticamente durante la finalización de compra si el comprador cumple los requisitos previos de la oferta.

De manera predeterminada, las ofertas con códigos de cupón no se promocionan de forma visible a los compradores en las plataformas de compra de Facebook e Instagram como las páginas de detalles de productos. Esto es para evitar que los códigos privados o secretos se filtren a los compradores de forma involuntaria. Puedes modificar este comportamiento especificando un código de cupón público para su uso como promoción comercial de la oferta. Las ofertas con códigos públicos se mostrarán igual que las ofertas cuyo valor de application_type sea AUTOMATIC_AT_CHECKOUT, pero también incluirán el texto del código.

Los códigos de cupón públicos no pueden exceder los 20 caracteres de longitud y tu catálogo solo puede contener un máximo de diez ofertas activas con códigos de cupón al mismo tiempo.

Los códigos de cupón públicos solo se pueden configurar cuando el valor de application_type es BUYER_APPLIED.

Si se establece este campo, el valor de coupon_codes debe ser nulo.

start_date_time

Tipo: timestamp

Obligatorio.

Marca de tiempo Unix en segundos, que indica cuándo empieza la oferta.

Los datos de entrada pueden ser una marca de tiempo Unix en segundos o una cadena de fecha en formato ISO-8601 (p. ej., 2021-09-25T12:34:56Z).

end_date_time

Tipo: timestamp

Opcional. El valor predeterminado es null.

Marca de tiempo Unix en segundos, que indica cuándo finaliza la oferta. Si se deja vacío o con el valor null, la oferta no tendrá fecha final.

Los datos de entrada pueden ser una marca de tiempo Unix en segundos o una cadena de fecha en formato ISO-8601 (p. ej., 2021-09-25T12:34:56Z).

min_quantity

Tipo: int64

Opcional. El valor predeterminado es 0.

Utiliza este campo si quieres que la oferta solo sea válida cuando el cliente compre un número mínimo de productos.

Este campo representa el número de productos que el cliente debe comprar para que la oferta sea válida. Por ejemplo: “Compra cinco camisas y consigue un 20 % de descuento”.

Solo se puede establecer el valor de min_quantity o el de min_subtotal.

min_subtotal

Tipo: string

Opcional. El valor predeterminado es null.

Utiliza este campo si quieres que la oferta solo sea válida cuando el pedido del cliente alcance un valor subtotal específico.

El subtotal de los productos con requisitos previos debe ser igual o mayor que este valor para que la oferta se aplique. Si no se establece ningún producto con requisitos previos explícitos, los productos objetivo se utilizarán como productos con requisitos previos.

Este campo debe tener como formato la cantidad seguida del código de divisa ISO de tres dígitos, con un espacio entre la cantidad y la divisa. Por ejemplo, la cadena “30,99 USD” representa un requisito previo de 30,99 USD como subtotal para que la oferta se aplique.

Solo se puede establecer el valor de min_quantity o el de min_subtotal.

redeem_limit_per_user

Tipo: int64

Opcional. El valor predeterminado es 0 (ilimitado).

Número máximo de veces que un único usuario puede utilizar la oferta.

Establece el valor de este campo en “1” para crear un código de cupón de un solo uso.

Este campo solo se debe establecer si el valor de application_type es BUYER_APPLIED.

value_type

Tipo: enum {FIXED_AMOUNT, PERCENTAGE}

Obligatorio.

Tipo de descuento que proporciona la oferta.

Las opciones disponibles son las siguientes:

FIXED_AMOUNT: aplica un descuento con el valor tomado de fixed_amount_off.
PERCENTAGE: aplica un porcentaje de descuento con el valor tomado de percent_off.

fixed_amount_off

Tipo: string

Obligatorio si el valor de value_type está establecido en FIXED_AMOUNT.

Cantidad de descuento de la oferta. El formato debe ser la cantidad seguida del código de divisa ISO de tres dígitos, con un espacio entre la cantidad y la divisa. Por ejemplo, la cadena “30,99 USD” representa un descuento de 30,99 USD.

Este campo solo se debe establecer si el valor de value_type es FIXED_AMOUNT.

percent_off

Tipo: int64

Obligatorio si el valor de value_type está establecido en PERCENTAGE.

Porcentaje de descuento de la oferta. Debe ser un entero entre 0 y 100. Por ejemplo, el valor “30” representa un descuento del 30 %.

Este campo solo se debe establecer si el valor de value_type es PERCENTAGE.

target_granularity

Tipo: enum {ITEM_LEVEL, ORDER_LEVEL}

Obligatorio.

Granularidad con la que se aplica el descuento de la oferta.

Las opciones disponibles son las siguientes:

ITEM_LEVEL: representa un descuento que se aplica a cada artículo objetivo del carrito.
ORDER_LEVEL: representa un descuento que se aplica al conjunto de todos los artículos objetivo del carrito. Por ejemplo, si tienes una oferta de “30 USD de descuento en zapatos” con tres pares de zapatos en el carrito, ITEM_LEVEL aplicará un descuento de 30 USD a cada par de zapatos (un valor total de 90 USD), mientras que ORDER_LEVEL aplicará un descuento de 30 USD a la suma de los tres pares de zapatos (un valor máximo de 30 USD).

Ten en cuenta que es posible que las ofertas con la granularidad ORDER_LEVEL den lugar a asignaciones de descuentos en la compra que no se dividen uniformemente entre los artículos del pedido. Gestionar estas asignaciones desiguales de descuentos puede conllevar una mayor complejidad a la hora de procesar los pedidos o en caso de reembolsos.

offer_terms

Tipo: string

Opcional.

Términos y condiciones adicionales que establecen el uso de la oferta por parte del comprador. 2500 caracteres como máximo.

Facebook generará automáticamente las condiciones para describir la oferta en función de la configuración de la misma. Además de estas condiciones, puedes utilizar el campo offer_terms para añadir más detalles que describan tus propias condiciones de la oferta. Estas condiciones aparecerán debajo de las condiciones de la oferta de Facebook.

El contenido debe cumplir nuestras políticas de contenido.

Especificar los productos que cumplen los requisitos

Tanto los artículos objetivo para los que una oferta es válida como los artículos con requisitos previos que el comprador debe comprar para canjear la oferta se definen por conjuntos de productos. La API de ofertas admite varias formas de especificar estos conjuntos de productos, pero solo se puede usar un método por cada tipo de conjunto de productos y oferta.

Campo Descripción

Campo	Descripción
`target_selection` Tipo: `enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}`	Obligatorio. Este campo se utiliza para distinguir entre las ofertas aplicables a todo un catálogo de productos y las ofertas restringidas a un subconjunto de artículos específico en un catálogo. Las opciones disponibles son las siguientes: `ALL_CATALOG_PRODUCTS`: la oferta es aplicable a cualquier producto del catálogo. `SPECIFIC_PRODUCTS`: la oferta solo se puede aplicar a los productos objetivo especificados por `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` o `target_product_set_retailer_ids`. Si el valor de `target_selection` es `SPECIFIC_PRODUCTS`, se requiere uno de los siguientes campos: `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` o `target_product_set_retailer_ids`.
`target_filter` Tipo: `JSON-encoded string`	Opcional. Regla de filtro para identificar los productos a los que se puede aplicar la oferta. Utiliza la misma lógica de reglas de filtro que se usa para añadir productos a un conjunto de productos. Si la regla de filtro especificada coincide con el filtro de un conjunto de productos existente, la oferta se dirigirá a ese conjunto de productos. En caso contrario, se creará un nuevo conjunto de productos. Este campo solo debe especificarse si el valor de `target_selection` está establecido en `SPECIFIC_PRODUCTS`.
`target_product_retailer_ids` Tipo: `Array<product_retailer_id>`	Opcional. Lista con los identificadores de producto del minorista de los productos a los que se puede aplicar la oferta. Este campo solo debe especificarse si el valor de `target_selection` está establecido en `SPECIFIC_PRODUCTS`.
`target_product_group_retailer_ids` Tipo: `Array<product_group_retailer_id>`	Opcional. Lista con los identificadores de grupos de productos del minorista de los productos a los que se puede aplicar la oferta. Todas las variantes de productos incluidas en el grupo de productos cumplirán los requisitos para la oferta. Este campo solo debe especificarse si el valor de `target_selection` está establecido en `SPECIFIC_PRODUCTS`.
`target_product_set_retailer_ids` Tipo: `Array<product_set_retailer_id>`	Opcional. Lista con los identificadores del minorista de conjuntos de productos que contienen productos a los que se puede aplicar la oferta. La oferta se aplicará a la unión de todos los productos obtenidos al evaluar los conjuntos de productos especificados.
`prerequisite_filter` Tipo: `JSON-encoded string`	Opcional. Regla de filtro para identificar los productos que deben comprarse para que el comprador pueda canjear la oferta. Utiliza la misma lógica de reglas de filtro que se usa para añadir productos a un conjunto de productos. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”. Si la regla de filtro especificada coincide con el filtro de un conjunto de productos existente, la oferta utilizará el conjunto de productos para definir los productos con requisitos previos. En caso contrario, se creará un nuevo conjunto de productos. Si se establece este campo, el valor de `prerequisite_product_retailer_ids`, `prerequisite_product_group_retailer_ids` y `prerequisite_product_set_retailer_ids` debe ser `null`.
`prerequisite_product_retailer_ids` Tipo: `Array<product_retailer_id>`	Opcional. Identificadores del minorista de los productos que el comprador debe comprar para canjear la oferta. Los artículos que se incluyan en esta lista cumplirán los requisitos para que el comprador los utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”. Si se establece este campo, el valor de `prerequisite_filter`, `prerequisite_product_group_retailer_ids` y `prerequisite_product_set_retailer_ids` debe ser `null`.
`prerequisite_product_group_retailer_ids` Tipo: `Array<product_group_retailer_id>`	Opcional. Identificadores del minorista de los grupos de productos que el comprador debe comprar para canjear la oferta. Las variantes de productos incluidas en cada grupo cumplen los requisitos para que el comprador las utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”. Si se establece este campo, el valor de `prerequisite_filter`, `prerequisite_product_retailer_ids` y `prerequisite_product_set_retailer_ids` debe ser `null`.
`prerequisite_product_set_retailer_ids` Tipo: `Array<product_set_retailer_id>`	Opcional. Identificadores del minorista de los conjuntos de productos que incluyen artículos que el comprador debe comprar para canjear la oferta. Los artículos obtenidos de la unión de las evaluaciones de los conjuntos de productos cumplirán los requisitos para que el comprador los utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”. Si se establece este campo, el valor de `prerequisite_filter`, `prerequisite_product_retailer_ids` y `prerequisite_product_group_retailer_ids` debe ser `null`.
`exclude_sale_priced_products` Tipo: `bool enum {YES, NO}`	Opcional. Determina si la oferta es aplicable a productos que ya muestren el precio reducido en el catálogo, definido con el campo `sale_price` del producto. Establece el valor del campo en `YES` para evitar la posible duplicación de descuentos sobre productos. Omite este campo o establece su valor en `NO` para incluir los productos del catálogo que tengan un valor de `sale_price` menor. Cuando este campo está establecido, se aplica tanto a los productos objetivo como a los productos con requisitos previos de una oferta.

target_selection

Tipo: enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}

Obligatorio.

Este campo se utiliza para distinguir entre las ofertas aplicables a todo un catálogo de productos y las ofertas restringidas a un subconjunto de artículos específico en un catálogo.

Las opciones disponibles son las siguientes:

ALL_CATALOG_PRODUCTS: la oferta es aplicable a cualquier producto del catálogo.
SPECIFIC_PRODUCTS: la oferta solo se puede aplicar a los productos objetivo especificados por target_filter, target_product_retailer_ids, target_product_group_retailer_ids o target_product_set_retailer_ids.

Si el valor de target_selection es SPECIFIC_PRODUCTS, se requiere uno de los siguientes campos: target_filter, target_product_retailer_ids, target_product_group_retailer_ids o target_product_set_retailer_ids.

target_filter

Tipo: JSON-encoded string

Opcional.

Regla de filtro para identificar los productos a los que se puede aplicar la oferta. Utiliza la misma lógica de reglas de filtro que se usa para añadir productos a un conjunto de productos.

Si la regla de filtro especificada coincide con el filtro de un conjunto de productos existente, la oferta se dirigirá a ese conjunto de productos. En caso contrario, se creará un nuevo conjunto de productos.

Este campo solo debe especificarse si el valor de target_selection está establecido en SPECIFIC_PRODUCTS.

target_product_retailer_ids

Tipo: Array<product_retailer_id>

Opcional.

Lista con los identificadores de producto del minorista de los productos a los que se puede aplicar la oferta.

Este campo solo debe especificarse si el valor de target_selection está establecido en SPECIFIC_PRODUCTS.

target_product_group_retailer_ids

Tipo: Array<product_group_retailer_id>

Opcional.

Lista con los identificadores de grupos de productos del minorista de los productos a los que se puede aplicar la oferta.

Todas las variantes de productos incluidas en el grupo de productos cumplirán los requisitos para la oferta.

Este campo solo debe especificarse si el valor de target_selection está establecido en SPECIFIC_PRODUCTS.

target_product_set_retailer_ids

Tipo: Array<product_set_retailer_id>

Opcional.

Lista con los identificadores del minorista de conjuntos de productos que contienen productos a los que se puede aplicar la oferta. La oferta se aplicará a la unión de todos los productos obtenidos al evaluar los conjuntos de productos especificados.

prerequisite_filter

Tipo: JSON-encoded string

Opcional.

Regla de filtro para identificar los productos que deben comprarse para que el comprador pueda canjear la oferta. Utiliza la misma lógica de reglas de filtro que se usa para añadir productos a un conjunto de productos. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”.

Si la regla de filtro especificada coincide con el filtro de un conjunto de productos existente, la oferta utilizará el conjunto de productos para definir los productos con requisitos previos. En caso contrario, se creará un nuevo conjunto de productos.

Si se establece este campo, el valor de prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids y prerequisite_product_set_retailer_ids debe ser null.

prerequisite_product_retailer_ids

Tipo: Array<product_retailer_id>

Opcional.

Identificadores del minorista de los productos que el comprador debe comprar para canjear la oferta. Los artículos que se incluyan en esta lista cumplirán los requisitos para que el comprador los utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”.

Si se establece este campo, el valor de prerequisite_filter, prerequisite_product_group_retailer_ids y prerequisite_product_set_retailer_ids debe ser null.

prerequisite_product_group_retailer_ids

Tipo: Array<product_group_retailer_id>

Opcional.

Identificadores del minorista de los grupos de productos que el comprador debe comprar para canjear la oferta. Las variantes de productos incluidas en cada grupo cumplen los requisitos para que el comprador las utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”.

Si se establece este campo, el valor de prerequisite_filter, prerequisite_product_retailer_ids y prerequisite_product_set_retailer_ids debe ser null.

prerequisite_product_set_retailer_ids

Tipo: Array<product_set_retailer_id>

Opcional.

Identificadores del minorista de los conjuntos de productos que incluyen artículos que el comprador debe comprar para canjear la oferta. Los artículos obtenidos de la unión de las evaluaciones de los conjuntos de productos cumplirán los requisitos para que el comprador los utilice como requisito previo para canjear la oferta. Normalmente, se utiliza en ofertas del estilo “Compra X y consigue Y”.

Si se establece este campo, el valor de prerequisite_filter, prerequisite_product_retailer_ids y prerequisite_product_group_retailer_ids debe ser null.

exclude_sale_priced_products

Tipo: bool enum {YES, NO}

Opcional.

Determina si la oferta es aplicable a productos que ya muestren el precio reducido en el catálogo, definido con el campo sale_price del producto.

Establece el valor del campo en YES para evitar la posible duplicación de descuentos sobre productos. Omite este campo o establece su valor en NO para incluir los productos del catálogo que tengan un valor de sale_price menor.

Cuando este campo está establecido, se aplica tanto a los productos objetivo como a los productos con requisitos previos de una oferta.

Ofertas de envío

La API de ofertas admite tanto las ofertas que aplican descuentos sobre el precio de los productos en la compra del cliente como las ofertas que descuentan los gastos de envío de dichos productos. Al igual que las ofertas para productos, las ofertas de envío se pueden aplicar mediante códigos de cupón o de manera automática con o sin requisitos previos adicionales para el comprador.

Para crear una oferta de envío, el valor de target_type debe establecerse en SHIPPING. Actualmente, solo se admiten las ofertas de envío gratis. Por lo tanto, el valor de value_type siempre debe establecerse en PERCENTAGE con el valor de percent_off establecido en “100”.

Campo Descripción

Campo	Descripción
`target_type` Tipo: `enum{LINE_ITEM, SHIPPING}`	Obligatorio. Tipo de objeto al que se aplica la oferta: `LINE_ITEM`: la oferta se aplica a los propios productos. `SHIPPING`: la oferta se aplica a los gastos de envío. Esta opción solo es válida cuando el valor de `target_granularity` es `ITEM_LEVEL`.
`target_shipping_option_types` Tipo: `Array<shipping_service_tier>`	Obligatorio si el valor de `target_type` es `SHIPPING`. Lista de niveles de servicios de envío (p. ej., `STANDARD`, `RUSH`, `EXPEDITED`) para los que la oferta es válida. Por ejemplo, para especificar una oferta de envío que se aplique a los envíos estándar y urgentes, pero no a los envíos al día siguiente, utiliza: `SHIPPING` como valor para `target_type` `["STANDARD", "RUSH"]` como valor para `target_shipping_option_types` En el caso de los vendedores que tengan habilitada la finalización de compra con Facebook o Instagram, puedes utilizar la API de perfiles de envío para administrar los perfiles de envío en tu cuenta comercial.

target_type

Tipo: enum{LINE_ITEM, SHIPPING}

Obligatorio.

Tipo de objeto al que se aplica la oferta:

LINE_ITEM: la oferta se aplica a los propios productos.
SHIPPING: la oferta se aplica a los gastos de envío. Esta opción solo es válida cuando el valor de target_granularity es ITEM_LEVEL.

target_shipping_option_types

Tipo: Array<shipping_service_tier>

Obligatorio si el valor de target_type es SHIPPING.

Lista de niveles de servicios de envío (p. ej., STANDARD, RUSH, EXPEDITED) para los que la oferta es válida.

Por ejemplo, para especificar una oferta de envío que se aplique a los envíos estándar y urgentes, pero no a los envíos al día siguiente, utiliza:

SHIPPING como valor para target_type
["STANDARD", "RUSH"] como valor para target_shipping_option_types

En el caso de los vendedores que tengan habilitada la finalización de compra con Facebook o Instagram, puedes utilizar la API de perfiles de envío para administrar los perfiles de envío en tu cuenta comercial.

Ofertas del tipo “Compra X y consigue Y”

Las ofertas del tipo “Compra X y consigue Y” permiten a los clientes comprar una cantidad determinada de X productos seleccionados y obtener uno o varios productos Y a precio reducido o gratis. También se admiten las ofertas del tipo “Gasta X y consigue Y”, en las que el comprador debe alcanzar una cantidad de gasto mínima en un conjunto de X productos para obtener un descuento. Para crear una oferta del tipo “Compra X y consigue Y”, establece el campo target_quantity, así como el campo min_quantity o min_subtotal.

En algunos casos, como la habitual oferta de dos por uno, “X” e “Y” pueden hacer referencia al mismo conjunto de productos. Sin embargo, también puedes utilizar los campos prerequisite_filter, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids y prerequisite_product_set_retailer_ids para especificar un conjunto de productos X distintos de los productos objetivo Y. Consulta Especificar los productos que cumplen los requisitos para obtener información sobre cómo configurar estos campos.

Campo Descripción

Campo	Descripción
`target_quantity` Tipo: `int64`	Opcional. El valor predeterminado es 0 (ilimitado). Número de productos que se descontará en cada canje de la oferta. Al establecer un valor de `target_quantity` mayor que 0, se crea una oferta del tipo “Compra X y consigue Y”. Utiliza este campo para controlar cuántos productos se descuentan cuando el comprador cumple los requisitos previos para el canje. Por ejemplo, en la oferta “compra dos y consigue uno al 50 %”, la cantidad objetivo es uno, mientras que en la oferta “compra cinco y consigue dos gratis”, la cantidad objetivo es dos.
`redemption_limit_per_order` Tipo: `int64`	Opcional. El valor predeterminado es 0 (ilimitado). Número de veces que la oferta puede canjearse por pedido. Utiliza este campo para limitar el número de veces que una oferta puede aplicarse a los productos en la compra de un cliente. Por ejemplo, en la oferta “compra una camisa y consigue otra gratis”, el cliente que compre seis camisas recibirá tres a precio sin descuento y tres gratis de forma predeterminada. Sin embargo, en este mismo ejemplo, si el valor de `redemption_limit_per_order` se establece en “2”, el comprador recibirá dos camisas gratis y 4 a precio sin descuento. Si se establece este campo, el valor de `target_quantity` debe ser mayor que 0.

target_quantity

Tipo: int64

Opcional. El valor predeterminado es 0 (ilimitado).

Número de productos que se descontará en cada canje de la oferta. Al establecer un valor de target_quantity mayor que 0, se crea una oferta del tipo “Compra X y consigue Y”.

Utiliza este campo para controlar cuántos productos se descuentan cuando el comprador cumple los requisitos previos para el canje. Por ejemplo, en la oferta “compra dos y consigue uno al 50 %”, la cantidad objetivo es uno, mientras que en la oferta “compra cinco y consigue dos gratis”, la cantidad objetivo es dos.

redemption_limit_per_order

Tipo: int64

Opcional. El valor predeterminado es 0 (ilimitado).

Número de veces que la oferta puede canjearse por pedido.

Utiliza este campo para limitar el número de veces que una oferta puede aplicarse a los productos en la compra de un cliente. Por ejemplo, en la oferta “compra una camisa y consigue otra gratis”, el cliente que compre seis camisas recibirá tres a precio sin descuento y tres gratis de forma predeterminada. Sin embargo, en este mismo ejemplo, si el valor de redemption_limit_per_order se establece en “2”, el comprador recibirá dos camisas gratis y 4 a precio sin descuento.

Si se establece este campo, el valor de target_quantity debe ser mayor que 0.

Combinar ofertas

En el caso de los vendedores que tengan habilitada la finalización de compra en Facebook o Instagram, existe una limitación para combinar varias ofertas en una sola transacción. Que una oferta se pueda combinar con otras ofertas lo determina principalmente su tipo de aplicación y su tipo de objetivo. Actualmente, los vendedores no pueden configurar este comportamiento. Las siguientes reglas resumen el comportamiento de apilamiento de ofertas:

Si en relación con un producto concreto, hay ofertas que dan lugar a un precio tachado (application_type = SALE), se aplica la oferta que dé como resultado el precio más bajo. Esto se repite para todos los artículos en el carrito del comprador. El nuevo precio con descuento del artículo se utilizará en todos los cálculos de requisitos previos para ofertas.
En un único pedido, el comprador puede canjear una oferta BUYER_APPLIED o una oferta AUTOMATIC_AT_CHECKOUT por cada target_type (LINE_ITEM o SHIPPING). Por ejemplo, un comprador puede aplicar un cupón de envío gratis y un cupón de dos por uno, pero no puede canjear dos ofertas que apliquen descuentos a los precios de los productos.
En determinadas ocasiones, es posible que Meta financie ofertas para atraer a clientes nuevos y habituales sin coste alguno para los vendedores. Las ofertas financiadas por Meta siempre se pueden combinar con las ofertas financiadas por los vendedores.

Restringir la idoneidad de un usuario para recibir ofertas

Por el momento, las ofertas creadas mediante la API de ofertas no pueden promocionarse comercialmente de manera selectiva para grupos de usuarios específicos. Las ofertas creadas en Commerce Manager se pueden configurar con restricciones de idoneidad de usuarios. Las ofertas promocionadas creadas mediante la API de ofertas se mostrarán a todos los compradores. Además, cualquier comprador que cumpla los requisitos previos de una oferta (incluido el introducir códigos de cupón) en la finalización de compra en Facebook o Instagram podrá canjear dicha oferta.

En el futuro, la API de ofertas permitirá limitar las ofertas a países concretos en el caso de vendedores internacionales, así como restringir la idoneidad de las ofertas a grupos de usuarios determinados, como los compradores nuevos o los seguidores de la página de Facebook del vendedor.