Productos

Mantén el catálogo de tu tienda en Emailit para las cuadrículas de productos, las recomendaciones y los artículos de los pedidos.

URL basehttps://api.emailit.com/v2Autenticación Errores Límites de velocidad

POST/products
GET/products/{id}
POST/products/{id}
GET/products
POST/products/batch
GET/products/categories
DEL/products/{id}

Crear o actualizar un producto

Añade un producto a tu catálogo, o actualízalo si ya existe un producto con el mismo id. El id es el ID del producto en tu tienda, así que puedes volver a enviar el mismo producto cada vez que cambie. Requiere una clave de API con el permiso full o events. Con una clave events, la respuesta solo contiene object, id y external_id.

id siempre es obligatorio, y title es obligatorio en un producto nuevo. Los campos solo se escriben si los envías, así que un producto que vuelves a enviar solo con un precio nuevo conserva su título, sus categorías, su imagen y todo lo demás. Para enviar muchos productos a la vez, usa Crear o actualizar productos en bloque.

Las cuadrículas de productos, las recomendaciones y los artículos de los pedidos en los emails se leen del catálogo. Consulta Productos, cupones y el carrito.

POST/products

Cuerpo de la petición

idstring | numberObligatorio

El ID del producto en tu tienda, de hasta 255 caracteres. Los números se guardan como cadenas. Se guarda como external_id. También puedes enviarlo como external_id.

titlestring

El nombre del producto, de hasta 500 caracteres. También puedes enviarlo como name. Obligatorio en un producto nuevo.

skustring

La referencia de inventario (SKU), de hasta 255 caracteres.

descriptionstring

La descripción del producto, de hasta 10.000 caracteres.

urlstring

La página del producto en tu tienda. Una URL http o https de hasta 2048 caracteres.

image_urlstring

La imagen del producto. Una URL http o https de hasta 2048 caracteres.

pricenumber | string

El precio actual, como número o como cadena numérica, por ejemplo "89.00". No puede ser negativo. Se guarda con hasta 4 decimales.

compare_at_pricenumber | string

El precio antes de un descuento, con el mismo formato que price. Si es mayor que price, el producto se considera en oferta.

currencystring

El código ISO 4217 de tres letras, por ejemplo USD o EUR. Se aceptan minúsculas. Los emails muestran los precios del producto en esta moneda, o en USD si no está definida.

categoriesstring[]

Hasta 50 nombres de categoría de hasta 191 caracteres cada uno. Los duplicados se eliminan.

brandstring

El nombre de la marca, de hasta 191 caracteres.

inventory_quantityinteger | null

Las unidades en inventario. null significa que no controlas el inventario. Las cuadrículas de productos de los emails omiten los productos con 0.

statusstring

active o archived. Los productos nuevos están en active. Los productos archivados se ocultan por defecto en Listar productos y se omiten en las cuadrículas de productos.

metadataobject

Tus propios datos de clave y valor, de hasta 16 KB en JSON. Si envías metadata, se sustituye el objeto guardado.

Devuelve

201 Created con el objeto de producto si el producto es nuevo, o 200 OK si se ha actualizado un producto existente. Devuelve 422 si un campo no es válido.

POST/products

Terminal

curl -X POST https://api.emailit.com/v2/products \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "8123456789",
    "title": "Trail running shoe",
    "sku": "TRS-BLU-42",
    "url": "https://shop.example.com/products/trail-running-shoe",
    "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
    "price": 89,
    "compare_at_price": 119,
    "currency": "USD",
    "categories": ["Shoes", "Running"],
    "brand": "Acme Outdoors",
    "inventory_quantity": 34
  }'

JSON

{
  "object": "product",
  "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
  "external_id": "8123456789",
  "sku": "TRS-BLU-42",
  "title": "Trail running shoe",
  "description": null,
  "url": "https://shop.example.com/products/trail-running-shoe",
  "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
  "price": 89,
  "compare_at_price": 119,
  "currency": "USD",
  "categories": [
    "Shoes",
    "Running"
  ],
  "brand": "Acme Outdoors",
  "inventory_quantity": 34,
  "status": "active",
  "metadata": {},
  "created_at": "2026-10-08T14:21:07.512Z",
  "updated_at": "2026-10-08T14:21:07.512Z"
}

JSON

{
  "message": "Validation failed. price: must not be negative",
  "errors": {
    "price": [
      "must not be negative"
    ]
  }
}

Obtener un producto

Obtén un producto por su ID de Emailit o por el ID del producto en tu tienda. Requiere una clave de API con el permiso full.

GET/products/{id}

Parámetros de ruta

idstringObligatorio

El ID del producto (prd_...) o el ID del producto en tu tienda (external_id). Codifica para URL los ID de tienda que contengan caracteres especiales.

Objeto de producto

objectstring

Siempre product.

idstring

El ID de Emailit del producto (prd_...).

external_idstring

El ID del producto en tu tienda: el id que enviaste. Los artículos de los pedidos y de los carritos hacen referencia a los productos con este ID.

skustring | null

La referencia de inventario (SKU).

titlestring

El nombre del producto.

descriptionstring | null

La descripción del producto.

urlstring | null

La página del producto en tu tienda.

image_urlstring | null

La imagen del producto.

pricenumber | null

El precio actual.

compare_at_pricenumber | null

El precio antes de un descuento. Un producto está en oferta si compare_at_price es mayor que price.

currencystring | null

El código ISO 4217 de tres letras de los precios.

categoriesstring[]

Los nombres de las categorías.

brandstring | null

El nombre de la marca.

inventory_quantityinteger | null

Las unidades en inventario. null significa que no se controla el inventario. Las cuadrículas de productos de los emails omiten los productos con 0.

statusstring

active o archived. Las cuadrículas de productos de los emails omiten los productos archivados.

metadataobject

Tus propios datos de clave y valor.

created_atstring

Cuándo se añadió el producto, en formato ISO 8601 UTC.

updated_atstring

Cuándo cambió el producto por última vez, en formato ISO 8601 UTC.

JSON

{
  "object": "product",
  "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
  "external_id": "8123456789",
  "sku": "TRS-BLU-42",
  "title": "Trail running shoe",
  "description": "Lightweight shoe with a grippy sole for wet trails.",
  "url": "https://shop.example.com/products/trail-running-shoe",
  "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
  "price": 89,
  "compare_at_price": 119,
  "currency": "USD",
  "categories": [
    "Shoes",
    "Running"
  ],
  "brand": "Acme Outdoors",
  "inventory_quantity": 34,
  "status": "active",
  "metadata": {
    "color": "blue"
  },
  "created_at": "2026-10-02T08:15:22.418Z",
  "updated_at": "2026-10-08T14:21:07.512Z"
}

JSON

{
  "error": "Product not found",
  "message": "Product not found."
}

Actualizar un producto

Actualiza un producto que ya está en tu catálogo. Solo cambian los campos que envías. El ID del producto en tu tienda no puede cambiar: se ignora cualquier id en el cuerpo. Requiere una clave de API con el permiso full o events. Con una clave events, la respuesta solo contiene object, id y external_id.

Para crear productos y actualizarlos con la misma llamada, usa Crear o actualizar un producto.

POST/products/{id}

Parámetros de ruta

idstringObligatorio

El ID del producto (prd_...) o el ID del producto en tu tienda.

Cuerpo de la petición

Cualquiera de los campos de Crear o actualizar un producto salvo id: title, sku, description, url, image_url, price, compare_at_price, currency, categories, brand, inventory_quantity, status y metadata. Se aplican las mismas reglas. categories y metadata se sustituyen por completo.

Devuelve

200 OK con el objeto de producto actualizado. Devuelve 404 si ningún producto coincide con id y 422 si un campo no es válido.

POST/products/{id}

Terminal

curl -X POST https://api.emailit.com/v2/products/8123456789 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "price": 79, "inventory_quantity": 20 }'

JSON

{
  "object": "product",
  "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
  "external_id": "8123456789",
  "sku": "TRS-BLU-42",
  "title": "Trail running shoe",
  "description": "Lightweight shoe with a grippy sole for wet trails.",
  "url": "https://shop.example.com/products/trail-running-shoe",
  "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
  "price": 79,
  "compare_at_price": 119,
  "currency": "USD",
  "categories": [
    "Shoes",
    "Running"
  ],
  "brand": "Acme Outdoors",
  "inventory_quantity": 20,
  "status": "active",
  "metadata": {
    "color": "blue"
  },
  "created_at": "2026-10-02T08:15:22.418Z",
  "updated_at": "2026-10-09T10:02:41.205Z"
}

JSON

{
  "error": "Product not found",
  "message": "Product not found."
}

JSON

{
  "message": "Validation failed. image_url: must be an http(s) URL",
  "errors": {
    "image_url": [
      "must be an http(s) URL"
    ]
  }
}

Listar productos

Lista los productos de tu catálogo, del más reciente al más antiguo. Sin status, solo se listan los productos activos. Requiere una clave de API con el permiso full.

GET/products

Parámetros de consulta

pageinteger

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

limitinteger

El número de productos 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 título, el ID del producto en tu tienda (external_id) o el SKU.

categorystring

Solo los productos de esta categoría. El nombre debe coincidir exactamente, incluidas las mayúsculas y minúsculas.

statusstring

active (por defecto), archived o all. Usa all si filtras por la clave status que se describe más abajo, porque el valor por defecto ya limita la lista a los productos activos.

idsstring

Una lista separada por comas de hasta 100 ID de producto. Cada uno puede ser el ID de Emailit (prd_...) o el ID del producto en tu tienda.

matchstring

all (por defecto) exige que coincidan todos los filtros key.condition. or exige que coincida cualquiera de ellos. Consulta Filtrado.

sortstring

El campo de ordenación: created_at (por defecto), updated_at, title o price.

orderstring

La dirección de ordenación: asc o desc (por defecto).

Filtros

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

Clave	Tipo	Condiciones	Notas
`title`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`external_id`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`sku`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`brand`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`currency`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`price`	number	exact, not_exact, gt, gte, lt, lte, empty, not_empty
`inventory_quantity`	number	exact, not_exact, gt, gte, lt, lte, empty, not_empty
`status`	enum	exact, not_exact	Valores: `active`, `archived`
`created_at`	date	exact, before, after, empty, not_empty
`updated_at`	date	exact, before, after, empty, not_empty

Claves de ordenación

Este endpoint ordena con sort igual a una de estas claves y order igual a asc o desc (aquí order=<key> devuelve 400): created_at, updated_at, title, price

En este endpoint, order solo admite asc o desc. Indica el campo de ordenación en sort, por ejemplo sort=price&order=asc.

Devuelve

Una página de objetos de producto 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.

JSON

{
  "data": [
    {
      "object": "product",
      "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
      "external_id": "8123456789",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "description": "Lightweight shoe with a grippy sole for wet trails.",
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
      "price": 89,
      "compare_at_price": 119,
      "currency": "USD",
      "categories": [
        "Shoes",
        "Running"
      ],
      "brand": "Acme Outdoors",
      "inventory_quantity": 34,
      "status": "active",
      "metadata": {
        "color": "blue"
      },
      "created_at": "2026-10-02T08:15:22.418Z",
      "updated_at": "2026-10-08T14:21:07.512Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}

Crear o actualizar productos en bloque

Envía hasta 1000 productos en una sola petición, por ejemplo para importar tu catálogo o para sincronizarlo de forma periódica. Cada producto sigue las reglas de Crear o actualizar un producto: se crea o se actualiza según su id, un producto nuevo necesita un title y los campos solo se escriben si los envías. Requiere una clave de API con el permiso full o events. Con una clave events, la respuesta solo contiene object, id y external_id.

Los productos no válidos se omiten y se indican en rejected; los demás se guardan. La petición devuelve igualmente 200.

POST/products/batch

Cuerpo de la petición

productsobject[]Obligatorio

De 1 a 1000 productos, cada uno con los campos de Crear o actualizar un producto.

Devuelve

createdinteger

El número de productos nuevos.

updatedinteger

El número de productos existentes que se han actualizado.

rejectedobject[]

Los productos que no se han guardado. Cada elemento tiene el index del producto en tu array products y errors, con la ruta del campo como clave, por ejemplo products.3.price.

Devuelve 422 si products está vacío o tiene más de 1000 elementos.

POST/products/batch

Terminal

curl -X POST https://api.emailit.com/v2/products/batch \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "id": "8123456789", "title": "Trail running shoe", "price": 89, "currency": "USD", "categories": ["Shoes", "Running"] },
      { "id": "8123456790", "title": "Merino running socks", "price": 18, "currency": "USD", "categories": ["Accessories"] },
      { "id": "8123456791", "price": 49, "currency": "USD" }
    ]
  }'

JSON

{
  "created": 1,
  "updated": 1,
  "rejected": [
    {
      "index": 2,
      "errors": {
        "products.2.title": [
          "is required"
        ]
      }
    }
  ]
}

JSON

{
  "message": "Validation failed. products: Send 1 to 1000 products.",
  "errors": {
    "products": [
      "Send 1 to 1000 products."
    ]
  }
}

Listar las categorías de productos

Lista las categorías que usan los productos activos, en orden alfabético, con el número de productos activos de cada una. Los productos archivados no se cuentan. Devuelve hasta 1000 categorías y no tiene paginación. Requiere una clave de API con el permiso full.

Las categorías proceden del campo categories de cada producto. Usa el nombre de una categoría con el parámetro category de Listar productos.

GET/products/categories

JSON

{
  "data": [
    {
      "name": "Accessories",
      "products": 18
    },
    {
      "name": "Running",
      "products": 12
    },
    {
      "name": "Shoes",
      "products": 27
    }
  ]
}

Eliminar un producto

Quita un producto de tu catálogo. Los pedidos que lo contienen conservan sus artículos, que guardan su propio título, su precio y el ID del producto. Para ocultar un producto sin eliminarlo, cambia su status a archived. Requiere una clave de API con el permiso full.

Si el script de seguimiento registra una vista de un producto eliminado con su título, el producto se vuelve a añadir al catálogo a partir de los datos de la página.

DELETE/products/{id}

Parámetros de ruta

idstringObligatorio

El ID del producto (prd_...) o el ID del producto en tu tienda.

JSON

{
  "object": "product",
  "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
  "deleted": true
}

JSON

{
  "error": "Product not found",
  "message": "Product not found."
}