# Cupones API > Crea cupones y gestiona sus pools de códigos únicos para tus emails. URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer `. ## Crear un cupón — POST /coupons > Crea un cupón con un pool de códigos únicos, o con un código compartido, para tus emails. Alfa: solo para el equipo de Emailit. # 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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). - 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](/es/docs/api-reference/coupons/add-codes/), 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](/es/docs/api-reference/orders/create/) incluye un código en `coupon_codes`, el código se marca como canjeado. Consulta [Productos, cupones y el carrito](/es/docs/campaigns/products-and-coupons/#coupon-codes). `POST /coupons` ## Cuerpo de la petición - `key` (string, obligatorio): 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. - `name` (string, obligatorio): El nombre del cupón que se muestra en el panel, de hasta 191 caracteres. - `description` (string | null): Una nota para tu equipo. El texto más largo se corta a 1000 caracteres. - `kind` (string): `unique` (por defecto) o `static`. - `static_code` (string | 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_label` (string | null): Una descripción breve del descuento, por ejemplo `10% off`. El texto más largo se corta a 191 caracteres. - `expires_at` (string | 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. - `codes` (string[] | 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](/es/docs/api-reference/coupons/get/). Devuelve `422` si un campo no es válido o si otro cupón ya tiene esa clave. **Petición** `POST /coupons` **cURL** ```bash 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"] }' ``` **201** ```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" } ``` **422** ```json { "message": "Validation failed. key: A coupon with this key already exists.", "errors": { "key": [ "A coupon with this key already exists." ] } } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/create/ ## Obtener un cupón — GET /coupons/{id} > Obtén un cupón por su ID o su clave, con el recuento de sus códigos disponibles, asignados y canjeados. Alfa: solo para el equipo de Emailit. # 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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). `GET /coupons/{id}` ## Parámetros de ruta - `id` (string, obligatorio): El ID del cupón (`cpn_...`) o la `key` del cupón. ## Objeto de cupón - `object` (string): Siempre `coupon`. - `id` (string): El ID del cupón (`cpn_...`). - `key` (string): El nombre que usas en el contenido de los emails: `{{coupon "welcome-10"}}`. Consulta [Productos, cupones y el carrito](/es/docs/campaigns/products-and-coupons/#coupon-codes). - `name` (string): El nombre del cupón que se muestra en el panel. - `description` (string | null): Una nota para tu equipo. - `kind` (string): - `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_code` (string | 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_label` (string | null): Una descripción breve del descuento, por ejemplo `10% off`. - `expires_at` (string | null): A partir de este momento, los destinatarios de un cupón único reciben `static_code` en lugar de un código. - `codes_total` (integer): Los códigos del pool. - `codes_available` (integer): 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_assigned` (integer): Los códigos asignados a un contacto, incluidos los que ya se han canjeado. - `codes_redeemed` (integer): Los códigos usados en un [pedido](/es/docs/api-reference/orders/create/) (`coupon_codes`). - `created_at, updated_at` (string): Cuándo se creó el cupón y cuándo cambió por última vez, en formato ISO 8601 UTC. **Petición** `GET /coupons/{id}` **cURL** ```bash curl https://api.emailit.com/v2/coupons/welcome-10 \ -H "Authorization: Bearer your_api_key" ``` **200** ```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" } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/get/ ## Actualizar un cupón — POST /coupons/{id} > Cambia la clave, el nombre, el tipo, el código alternativo o estático, la etiqueta o la caducidad de un cupón. Alfa: solo para el equipo de Emailit. # 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](/es/docs/api-reference/coupons/add-codes/): `codes` se ignora en esta petición. Requiere una clave de API con el permiso `full`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). 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 - `id` (string, obligatorio): 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](/es/docs/api-reference/coupons/create/). 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](/es/docs/api-reference/coupons/get/) 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. **Petición** `POST /coupons/{id}` **cURL** ```bash 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" }' ``` **200** ```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" } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` **422** ```json { "message": "Validation failed. static_code: A static coupon needs its code.", "errors": { "static_code": [ "A static coupon needs its code." ] } } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/update/ ## Listar cupones — GET /coupons > Lista los cupones de tu espacio de trabajo, del más reciente al más antiguo, con el recuento de sus códigos. Alfa: solo para el equipo de Emailit. # 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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). `GET /coupons` ## Parámetros de consulta - `page` (integer): El número de página (mínimo: 1; por defecto: 1). - `limit` (integer): El número de cupones que se devuelven (mínimo: 1; máximo: 100; por defecto: 25). - `search` (string): Búsqueda sin distinguir entre mayúsculas y minúsculas en el nombre o la clave del cupón. - `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/). ## Filtros y ordenación Claves de filtro y de ordenación: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/). ## Devuelve Una página de [objetos de cupón](/es/docs/api-reference/coupons/get/) 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. **Petición** `GET /coupons` **cURL** ```bash curl "https://api.emailit.com/v2/coupons?kind.exact=unique" \ -H "Authorization: Bearer your_api_key" ``` **200** ```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 } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/list/ ## Eliminar un cupón — DELETE /coupons/{id} > Elimina un cupón y todos sus códigos. Alfa: solo para el equipo de Emailit. # 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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). `DELETE /coupons/{id}` ## Parámetros de ruta - `id` (string, obligatorio): El ID del cupón (`cpn_...`) o la `key` del cupón. **Petición** `DELETE /coupons/{id}` **cURL** ```bash curl -X DELETE https://api.emailit.com/v2/coupons/cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "coupon", "id": "cpn_3sMKUvFbx63T9hhDoNea7fmo1fQ", "deleted": true } ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/delete/ ## Listar los códigos de un cupón — GET /coupons/{id}/codes > Lista los códigos de un cupón con a quién se asignaron y si se canjearon, en JSON o como exportación CSV. Alfa: solo para el equipo de Emailit. # 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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). `GET /coupons/{id}/codes` ## Parámetros de ruta - `id` (string, obligatorio): El ID del cupón (`cpn_...`) o la `key` del cupón. ## Parámetros de consulta - `page` (integer): El número de página (mínimo: 1; por defecto: 1). - `limit` (integer): El número de códigos que se devuelven (mínimo: 1; máximo: 100; por defecto: 50). - `status` (string): - `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. - `format` (string): `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. - `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/). ## Filtros y ordenación Claves de filtro y de ordenación: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/). ## 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: - `object` (string): Siempre `coupon_code`. - `id` (string): El ID del código (`cpc_...`). - `code` (string): El código. - `contact_id, email` (string | null): El contacto al que está asignado el código, o `null`. - `source_id` (string | null): La campaña (`cmp_...`) o la automatización (`aut_...`) cuyo email recibió el código. - `assigned_at` (string | null): Cuándo se asignó el código. - `redeemed_at, redeemed_order_id` (string | null): Cuándo se canjeó el código y con qué pedido (`ord_...`). - `created_at` (string): Cuándo se añadió el código al pool. **Petición** `GET /coupons/{id}/codes` **cURL** ```bash curl "https://api.emailit.com/v2/coupons/welcome-10/codes?status=assigned&limit=2" \ -H "Authorization: Bearer your_api_key" ``` **200** ```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 } ``` **CSV** ```text code,status,email,assigned_at,redeemed_at WELCOME-7KQ2M9XA,redeemed,ada@example.com,2026-10-08T09:00:41.751Z,2026-10-08T14:32:10.000Z WELCOME-H4TZ8RCN,assigned,grace@example.com,2026-10-08T09:00:41.773Z, WELCOME-QX3B9NMV,available,,, ``` **404** ```json { "error": "Coupon not found", "message": "Coupon not found." } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/list-codes/ ## Añadir códigos a un cupón — POST /coupons/{id}/codes > Sube los códigos de tu tienda a un cupón único o genera códigos aleatorios en Emailit. Alfa: solo para el equipo de Emailit. # 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](/es/docs/api-reference/coupons/list-codes/) (`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`. > **Comercio electrónico está en alfa:** Comercio electrónico solo está abierto al equipo de Emailit mientras lo probamos. Las demás peticiones devuelven `403` con `error: "commerce_alpha"`. Las claves de API solo funcionan en los espacios de trabajo que pertenecen al equipo de Emailit. Consulta [Quién puede usar Comercio electrónico](/es/docs/commerce/#who-can-use-commerce). `POST /coupons/{id}/codes` ## Parámetros de ruta - `id` (string, obligatorio): 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`. - `codes` (string[] | 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`. - `generate` (object): 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 - `added` (integer): Los códigos añadidos al pool. - `skipped` (integer): Los códigos que ya estaban en el pool. - `invalid` (string[]): Los valores subidos que no son códigos válidos y no se han añadido. - `coupon` (object): El [objeto de cupón](/es/docs/api-reference/coupons/get/) 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. **Petición** `POST /coupons/{id}/codes` **cURL** ```bash 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 } }' ``` **200** ```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" } } ``` **422** ```json { "message": "Validation failed. codes: Static coupons have one code; set static_code instead.", "errors": { "codes": [ "Static coupons have one code; set static_code instead." ] } } ``` --- Fuente: https://emailit.com/es/docs/api-reference/coupons/add-codes/