Saltar al contenido
Docs

Cupones

Crea cupones y gestiona sus pools de códigos únicos para tus emails.

URL basehttps://api.emailit.com/v2AutenticaciónErroresLímites de velocidad

Crear un cupón

Crea un cupón. Ponlo en un email con {{coupon "key"}}: al renderizar el email, cada destinatario recibe un código. Requiere una clave de API con el permiso full.

  • Un cupón único contiene un pool de códigos de un solo uso. A cada destinatario se le asigna el código libre más antiguo, uno por campaña o automatización, y recibe de nuevo el mismo código cada vez que ese email se renderiza para él. Sube aquí los códigos de tu tienda o con Añadir códigos a un cupón, o genera los códigos en Emailit e impórtalos en tu tienda.
  • Un cupón estático tiene un solo código, static_code, para todos.

Cuando un pedido incluye un código en coupon_codes, el código se marca como canjeado. Consulta Productos, cupones y el carrito.

POST/coupons

Cuerpo de la petición

keystringObligatorio

El nombre que usas en el contenido, único en el espacio de trabajo. De 1 a 64 letras minúsculas, dígitos, - o _, empezando por una letra o un dígito. Las mayúsculas se convierten en minúsculas.

namestringObligatorio

El nombre del cupón que se muestra en el panel, de hasta 191 caracteres.

descriptionstring | null

Una nota para tu equipo. El texto más largo se corta a 1000 caracteres.

kindstring

unique (por defecto) o static.

static_codestring | null

Hasta 191 caracteres. Obligatorio en un cupón estático: el código que reciben todos. En un cupón único, el texto que reciben los destinatarios cuando el pool está vacío o el cupón ha caducado. Sin él, reciben una cadena vacía.

discount_labelstring | null

Una descripción breve del descuento, por ejemplo 10% off. El texto más largo se corta a 191 caracteres.

expires_atstring | null

Una fecha y hora en formato ISO 8601. A partir de ella, los destinatarios de un cupón único reciben static_code en lugar de un código, también en los emails que se vuelven a renderizar. Emailit no aplica la caducidad en tu tienda.

codesstring[] | string

Los códigos que se añaden al pool: un array, o texto con un código por línea. En un texto CSV, se lee la primera columna y se omite una cabecera como code o coupon_code. Un código tiene de 2 a 64 letras, dígitos, -, _ o ., y empieza por una letra o un dígito. Los códigos no válidos se omiten y los duplicados se añaden una sola vez. Hasta 10.000 códigos.

Devuelve

201 Created con el objeto de cupón. Devuelve 422 si un campo no es válido o si otro cupón ya tiene esa clave.

POST/coupons
Terminal
curl -X POST https://api.emailit.com/v2/coupons \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "welcome-10",
    "name": "Welcome 10% off",
    "description": "First-order discount for new subscribers.",
    "kind": "unique",
    "static_code": "WELCOME10",
    "discount_label": "10% off",
    "expires_at": "2026-12-31T23:59:59Z",
    "codes": ["WELCOME-7KQ2M9XA", "WELCOME-H4TZ8RCN", "WELCOME-P2WD6YFE"]
  }'
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "codes_total": 3,
  "codes_available": 3,
  "codes_assigned": 0,
  "codes_redeemed": 0,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-01T09:00:12.304Z"
}

Obtener un cupón

Obtén un cupón por su ID o su clave, con el recuento de sus códigos. Requiere una clave de API con el permiso full.

GET/coupons/{id}

Parámetros de ruta

idstringObligatorio

El ID del cupón (cpn_...) o la key del cupón.

Objeto de cupón

objectstring

Siempre coupon.

idstring

El ID del cupón (cpn_...).

keystring

El nombre que usas en el contenido de los emails: {{coupon "welcome-10"}}. Consulta Productos, cupones y el carrito.

namestring

El nombre del cupón que se muestra en el panel.

descriptionstring | null

Una nota para tu equipo.

kindstring

  • unique: un pool de códigos de un solo uso. Cada destinatario recibe su propio código, uno por campaña o automatización, y el mismo código otra vez cuando el email se vuelve a renderizar.

  • static: un solo código, static_code, para todos.

static_codestring | null

El código compartido de un cupón estático. En un cupón único, el texto que reciben los destinatarios cuando no quedan códigos o el cupón ha caducado. Sin él, reciben una cadena vacía.

discount_labelstring | null

Una descripción breve del descuento, por ejemplo 10% off.

expires_atstring | null

A partir de este momento, los destinatarios de un cupón único reciben static_code en lugar de un código.

codes_totalinteger

Los códigos del pool.

codes_availableinteger

Los códigos que todavía se pueden repartir: no están asignados a ningún contacto ni se han usado en ningún pedido.

codes_assignedinteger

Los códigos asignados a un contacto, incluidos los que ya se han canjeado.

codes_redeemedinteger

Los códigos usados en un pedido (coupon_codes).

created_at, updated_atstring

Cuándo se creó el cupón y cuándo cambió por última vez, en formato ISO 8601 UTC.

GET/coupons/{id}
Terminal
curl https://api.emailit.com/v2/coupons/welcome-10 \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "codes_total": 5000,
  "codes_available": 3812,
  "codes_assigned": 1188,
  "codes_redeemed": 143,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-01T09:00:12.304Z"
}

Actualizar un cupón

Actualiza un cupón. Solo cambian los campos que envías. Para añadir códigos, usa Añadir códigos a un cupón: codes se ignora en esta petición. Requiere una clave de API con el permiso full.

Si cambias la key, actualiza también las etiquetas {{coupon "key"}} de tus emails: Emailit busca los cupones por la clave que aparece en el contenido.

POST/coupons/{id}

Parámetros de ruta

idstringObligatorio

El ID del cupón (cpn_...) o la key actual del cupón.

Cuerpo de la petición

Cualquiera de estos campos: key, name, description, kind, static_code, discount_label y expires_at, con las reglas de Crear un cupón. Envía null en description, static_code, discount_label o expires_at para vaciarlo. Un cupón que es static, o que pasa a serlo, debe conservar un static_code.

Devuelve

200 OK con el objeto de cupón actualizado. Devuelve 404 si ningún cupón coincide con id y 422 si un campo no es válido o la clave nueva ya está en uso.

POST/coupons/{id}
Terminal
curl -X POST https://api.emailit.com/v2/coupons/welcome-10 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2027-01-31T23:59:59Z" }'
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "key": "welcome-10",
  "name": "Welcome 10% off",
  "description": "First-order discount for new subscribers.",
  "kind": "unique",
  "static_code": "WELCOME10",
  "discount_label": "10% off",
  "expires_at": "2027-01-31T23:59:59.000Z",
  "codes_total": 5000,
  "codes_available": 3812,
  "codes_assigned": 1188,
  "codes_redeemed": 143,
  "created_at": "2026-10-01T09:00:12.304Z",
  "updated_at": "2026-10-09T15:47:20.061Z"
}

Listar cupones

Lista los cupones de tu espacio de trabajo, del más reciente al más antiguo, con el recuento de sus códigos. Requiere una clave de API con el permiso full.

GET/coupons

Parámetros de consulta

pageinteger

El número de página (mínimo: 1; por defecto: 1).

limitinteger

El número de cupones que se devuelven (mínimo: 1; máximo: 100; por defecto: 25).

searchstring

Búsqueda sin distinguir entre mayúsculas y minúsculas en el nombre o la clave del cupón.

matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

Filtros y ordenación

Los filtros de listado son un único nivel de parámetros de consulta key.condition=value. Consulta Filtrado para ver match, order, direction y la lista de condiciones de cada tipo.

Claves de filtro

ClaveTipoCondicionesNotas
keystringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
namestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
kindenumexact, not_exactValores: unique, static
expires_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Claves de ordenación

Pasa en order una de estas claves y en direction el valor asc o desc: key, name, kind, expires_at, created_at

Devuelve

Una página de objetos de cupón en data, con total_records, next_page_url y previous_page_url. Las URL de las páginas solo llevan page y limit, así que vuelve a añadir tu búsqueda y tus filtros cuando las sigas.

GET/coupons
Terminal
curl "https://api.emailit.com/v2/coupons?kind.exact=unique" \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "object": "coupon",
      "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
      "key": "welcome-10",
      "name": "Welcome 10% off",
      "description": "First-order discount for new subscribers.",
      "kind": "unique",
      "static_code": "WELCOME10",
      "discount_label": "10% off",
      "expires_at": "2026-12-31T23:59:59.000Z",
      "codes_total": 5000,
      "codes_available": 3812,
      "codes_assigned": 1188,
      "codes_redeemed": 143,
      "created_at": "2026-10-01T09:00:12.304Z",
      "updated_at": "2026-10-01T09:00:12.304Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Eliminar un cupón

Elimina un cupón junto con todos sus códigos, incluidos los asignados y los canjeados. Los pedidos conservan los códigos en su coupon_codes. Requiere una clave de API con el permiso full.

DELETE/coupons/{id}

Parámetros de ruta

idstringObligatorio

El ID del cupón (cpn_...) o la key del cupón.

DELETE/coupons/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "coupon",
  "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
  "deleted": true
}

Listar los códigos de un cupón

Lista los códigos de un cupón, del más antiguo al más reciente: el orden en que se reparten. Usa format=csv para exportarlos, por ejemplo para importar en tu tienda los códigos generados. Requiere una clave de API con el permiso full.

GET/coupons/{id}/codes

Parámetros de ruta

idstringObligatorio

El ID del cupón (cpn_...) o la key del cupón.

Parámetros de consulta

pageinteger

El número de página (mínimo: 1; por defecto: 1).

limitinteger

El número de códigos que se devuelven (mínimo: 1; máximo: 100; por defecto: 50).

statusstring

  • available: no está asignado a ningún contacto ni se ha usado en ningún pedido, así que todavía se puede repartir.

  • assigned: está asignado a un contacto y no se ha canjeado.

  • redeemed: se ha usado en un pedido.

formatstring

json (por defecto) o csv. CSV devuelve en un solo archivo todos los códigos que coinciden con status, sin paginación, con las columnas code, status, email, assigned_at y redeemed_at. Los filtros key.condition y la ordenación no se aplican al CSV.

matchstring

all (por defecto) exige que se cumplan todos los filtros. or coincide con cualquier filtro. Consulta Filtrado.

orderstring

Clave de ordenación de esta lista. Consulta las claves de ordenación más abajo.

directionstring

asc o desc.

Filtros y ordenación

Los filtros de listado son un único nivel de parámetros de consulta key.condition=value. Consulta Filtrado para ver match, order, direction y la lista de condiciones de cada tipo.

Claves de filtro

ClaveTipoCondicionesNotas
codestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
assigned_atdateexact, before, after, empty, not_empty
redeemed_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Claves de ordenación

Pasa en order una de estas claves y en direction el valor asc o desc: code, email, assigned_at, redeemed_at, created_at

Devuelve

Una página de códigos de cupón en data, con total_records, next_page_url y previous_page_url. Cada código tiene:

objectstring

Siempre coupon_code.

idstring

El ID del código (cpc_...).

codestring

El código.

contact_id, emailstring | null

El contacto al que está asignado el código, o null.

source_idstring | null

La campaña (cmp_...) o la automatización (aut_...) cuyo email recibió el código.

assigned_atstring | null

Cuándo se asignó el código.

redeemed_at, redeemed_order_idstring | null

Cuándo se canjeó el código y con qué pedido (ord_...).

created_atstring

Cuándo se añadió el código al pool.

GET/coupons/{id}/codes
Terminal
curl "https://api.emailit.com/v2/coupons/welcome-10/codes?status=assigned&limit=2" \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "object": "coupon_code",
      "id": "cpc_3s6oCjlRbLFujYObEAcuiZmGKqu",
      "code": "WELCOME-H4TZ8RCN",
      "contact_id": "con_3MjLVacsYA6keJucAbOs3o3XhyA",
      "email": "grace@example.com",
      "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "assigned_at": "2026-10-08T09:00:41.773Z",
      "redeemed_at": null,
      "redeemed_order_id": null,
      "created_at": "2026-10-01T09:00:12.304Z"
    },
    {
      "object": "coupon_code",
      "id": "cpc_3u9TrZTopqOgaqT9FcZFareUFGj",
      "code": "WELCOME-P2WD6YFE",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "source_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "assigned_at": "2026-10-08T09:00:41.802Z",
      "redeemed_at": null,
      "redeemed_order_id": null,
      "created_at": "2026-10-01T09:00:12.304Z"
    }
  ],
  "total_records": 1045,
  "next_page_url": "/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ/codes?page=2&limit=2",
  "previous_page_url": null
}

Añadir códigos a un cupón

Añade códigos al pool de un cupón único. Sube con codes los códigos que ya existen en tu tienda, o deja que Emailit cree códigos aleatorios con generate e impórtalos después en tu tienda con Listar los códigos de un cupón (format=csv). Los códigos que ya están en el pool se omiten. Los cupones estáticos tienen un solo código y devuelven 422. Requiere una clave de API con el permiso full.

POST/coupons/{id}/codes

Parámetros de ruta

idstringObligatorio

El ID del cupón (cpn_...) o la key del cupón.

Cuerpo de la petición

Envía codes o generate. Si envías ambos, se usa generate.

codesstring[] | string

Hasta 10.000 códigos: un array, o texto con un código por línea. En un texto CSV, se lee la primera columna y se omite una cabecera como code o coupon_code. Un código tiene de 2 a 64 letras, dígitos, -, _ o ., y empieza por una letra o un dígito. Los códigos que no cumplen estas reglas se devuelven en invalid.

generateobject

Crea códigos aleatorios con letras mayúsculas y dígitos, sin 0, O, 1 ni I, que se confunden fácilmente.

  • count (entero, obligatorio): de 1 a 10.000 códigos.

  • prefix (cadena): hasta 20 letras, dígitos, - o _, que se ponen delante de cada código. Por ejemplo, WELCOME-.

  • length (entero): los caracteres aleatorios después del prefijo, de 4 a 32. Por defecto, 8. Los valores fuera del rango se ajustan al límite más próximo.

Devuelve

addedinteger

Los códigos añadidos al pool.

skippedinteger

Los códigos que ya estaban en el pool.

invalidstring[]

Los valores subidos que no son códigos válidos y no se han añadido.

couponobject

El objeto de cupón con los recuentos nuevos.

Devuelve 404 si ningún cupón coincide con id, y 422 si el cupón es estático, si no se ha enviado ningún código válido, si se han enviado más de 10.000 códigos o si generate.count o generate.prefix están fuera del rango.

POST/coupons/{id}/codes
Terminal
curl -X POST https://api.emailit.com/v2/coupons/welcome-10/codes \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "generate": { "count": 5000, "prefix": "WELCOME-", "length": 8 } }'
JSON
{
  "added": 5000,
  "skipped": 0,
  "invalid": [],
  "coupon": {
    "object": "coupon",
    "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ",
    "key": "welcome-10",
    "name": "Welcome 10% off",
    "description": "First-order discount for new subscribers.",
    "kind": "unique",
    "static_code": "WELCOME10",
    "discount_label": "10% off",
    "expires_at": "2026-12-31T23:59:59.000Z",
    "codes_total": 5003,
    "codes_available": 5003,
    "codes_assigned": 0,
    "codes_redeemed": 0,
    "created_at": "2026-10-01T09:00:12.304Z",
    "updated_at": "2026-10-01T09:00:12.304Z"
  }
}

¿Te ha resultado útil esta página?

Gracias por tu opinión.

Gracias. Leemos todos los mensajes.

Esc

Populares

↑↓para moverte↵para abrirEscpara cerrar