Skip to main content
POST
Promotions se habilita por organizaciónEste endpoint funciona solo después de que Yuno habilite Promotions para tu organización. Hasta entonces responde 404 PROMOTION_NOT_FOUND. Pide la habilitación a tu Technical Account Manager o Key Account Manager. Consulta Promotions.
Las promociones no se pueden editarNo existe un endpoint para actualizar ni para eliminar. Para cambiar un descuento, una fecha, una condición o el código, deshabilita la promoción y crea una nueva.
Este endpoint crea promociones con código. Un cliente canjea una cuando tu servidor envía su código en Crear pago. Consulta Códigos promocionales para ver el flujo completo.

Qué necesita la solicitud

  • La cuenta se toma del encabezado X-Account-Code. La promoción pertenece a esa cuenta. Un cuerpo que incluya account_id se rechaza con 400 INVALID_PARAMETERS, y también un cuerpo que repita redemption o alguno de sus miembros (los nombres se comparan sin distinguir mayúsculas de minúsculas).
  • X-Idempotency-Key es obligatorio. Es cualquier texto de 1 a 64 caracteres. La misma clave en la misma cuenta devuelve la primera promoción con 201, y Yuno no compara el cuerpo. Una solicitud sin una clave válida se rechaza con 400 antes de leer el cuerpo.
  • redemption.mode es CODE y envías exactamente uno de redemption.code y redemption.prefix. Si no envías ninguno, la respuesta es 400 INVALID_REQUEST con redemption: CODE_OR_PREFIX_REQUIRED, y si envías ambos, la respuesta es redemption: CODE_AND_PREFIX_EXCLUSIVE. Cada respuesta agrega el mensaje Send exactly one of redemption.code or redemption.prefix.. Un null, un texto vacío y un texto con solo espacios cuentan como no enviados. Un redemption.code que no es válido, enviado junto con un prefijo, cuenta como ambos.
  • Un código que envías tiene de 3 a 32 caracteres: letras, dígitos, _ y -, en mayúsculas o minúsculas. Yuno recorta los espacios alrededor y lo guarda en mayúsculas. Un código con un carácter fuera de ese conjunto responde redemption.code: CODE_CHARACTERS, y uno de longitud incorrecta responde redemption.code: CODE_LENGTH.
  • Un prefijo construye el código. El prefijo tiene de 1 a 8 letras o dígitos (A-Z, a-z, 0-9). Yuno lo convierte a mayúsculas y construye el código con el prefijo y un sufijo aleatorio de 5 caracteres de A-Z y 2-9, sin 0, O, 1, I y L. Por ejemplo, el prefijo SUMMER puede dar SUMMERK7P2X. El 201 muestra el código en redemption.code. Un carácter fuera de A-Z, a-z y 0-9 responde redemption.prefix: FORMAT, y más de 8 caracteres responde redemption.prefix: LENGTH. Yuno nunca construye un código que ya tenga otra promoción de tu cuenta, sin importar su estado. Una creación con prefijo nunca responde 409 CODE_ALREADY_EXISTS. La misma X-Idempotency-Key devuelve la misma promoción con el mismo código. Si Yuno no puede construir un código, la creación falla con 500 INTERNAL_ERROR y Yuno no guarda nada: reintenta la solicitud.
  • Un código es único por cuenta. Otra promoción de la cuenta que no esté deshabilitada, con un calendario que se superponga al de la nueva, no puede tener el mismo código, y ningún código de lote de la cuenta puede tenerlo tampoco: la solicitud responde 409 CODE_ALREADY_EXISTS. Un código vuelve a estar libre cuando la promoción anterior se deshabilita, o cuando su calendario termina en el momento de inicio de la nueva o antes.
  • Las condiciones son countries y amounts. Un código se aplica a todo el pago, sin importar el método de pago. Una condición bins, payment_methods o card_types responde 400 INVALID_REQUEST con conditions.bins: FORBIDDEN, conditions.payment_methods: FORBIDDEN o conditions.card_types: FORBIDDEN.
  • limits.total es opcional. Es el máximo de usos que acepta el código, un número entero de 1 a 2147483647. Una promoción sin limits no tiene tope, y su respuesta muestra limits: null. Yuno cuenta un uso cuando un pago toma el código. Consulta Usos y límites.
  • El cuerpo pesa como máximo 256 KiB. Un cuerpo más grande responde 413 REQUEST_ENTITY_TOO_LARGE.

Qué contiene la respuesta

201 devuelve la promoción, tal como la describe El objeto Promotion, con status calculado a partir de schedule y con limits.used en 0. Todos los miembros están presentes, con null para un valor ausente. redemption.code contiene el código, ya sea el que enviaste o el que Yuno construyó a partir de tu prefijo. Existen dos tipos de 400. INVALID_PARAMETERS proviene de las comprobaciones que Yuno hace antes de leer la promoción: los encabezados, account_id, redemption.mode. INVALID_REQUEST proviene de las reglas de la promoción en sí, con un mensaje path: RULE por cada ruta que falla, en el orden de las comprobaciones. Códigos de error de Promotion los enumera.

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

X-Account-Code
string
required

The account_id found in your Yuno Dashboard (UUID). Required. A promotion belongs to one account, and this header names it. Omitting it returns 400 INVALID_PARAMETERS ("x-account-code header is required.").

X-Idempotency-Key
string
required

Required. Any text of 1 to 64 characters. The same key on the same account returns the first promotion with 201, and Yuno does not compare the body.

Required string length: 1 - 64

Body

application/json
name
string
required

The promotion name (1 to 255 characters).

Required string length: 1 - 255
schedule
object
required

The window in which the promotion runs. UTC.

redemption
object
required
discount
object
required

What the customer saves. For FIXED, when the promotion also has an amounts condition, discount.amounts and conditions.amounts.values must list the same currencies, or the request returns 400.

description
string

Optional. Up to 1000 characters.

Required string length: 1 - 1000
conditions
object

The conditions a payment must meet. AND across keys, OR inside each key's values list. A code applies to the whole payment, whatever the payment method, so only countries and amounts are accepted. A bins, payment_methods or card_types condition returns 400 INVALID_REQUEST with the messages conditions.bins: FORBIDDEN, conditions.payment_methods: FORBIDDEN or conditions.card_types: FORBIDDEN.

limits
object

Optional. Without it the code has no cap.

Response

  1. The promotion. The same answer returns when the account repeats the X-Idempotency-Key.

A promotion. Every member is present, with null for an absent value.

id
string<uuid>

The id of the promotion (UUID). Assigned by Yuno.

account_id
string<uuid>

The account the promotion belongs to.

name
string
description
string | null
schedule
object
redemption
object
discount
object
conditions
object

One key for each dimension, null when the promotion has no condition on it. A code promotion created with this API holds countries and amounts only.

limits
object | null

The cap of the code and the uses counted so far. null when the promotion has no cap.

status
enum<string>

Computed from schedule and from the disable at the moment you read the promotion.

Available options:
SCHEDULED,
ACTIVE,
EXPIRED,
DISABLED
created_at
string<date-time>
disabled_at
string<date-time> | null

null while the promotion is not disabled.