Produits

Gardez le catalogue de votre boutique dans Emailit pour les grilles de produits, les recommandations et les articles des commandes.

URL de basehttps://api.emailit.com/v2Authentification Erreurs Limites de débit

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

Créer ou mettre à jour un produit

Ajoute un produit à votre catalogue, ou le met à jour si un produit avec le même id existe déjà. L’id est l’ID du produit dans votre boutique : vous pouvez donc renvoyer le même produit chaque fois qu’il change. Nécessite une clé API avec la portée full ou events. Avec une clé events, la réponse ne contient que object, id et external_id.

id est toujours obligatoire, et title est obligatoire pour un nouveau produit. Les champs ne sont écrits que si vous les envoyez : un produit renvoyé avec seulement un nouveau prix garde son titre, ses catégories, son image et le reste. Pour envoyer de nombreux produits à la fois, utilisez Créer ou mettre à jour des produits par lots.

Les grilles de produits, les recommandations et les articles des commandes dans les e-mails puisent dans le catalogue. Consultez Produits, coupons et panier.

POST/products

Corps de la requête

idstring | numberObligatoire

L’ID du produit dans votre boutique, 255 caractères au maximum. Les nombres sont enregistrés comme des chaînes. Enregistré dans external_id. Vous pouvez aussi l’envoyer sous le nom external_id.

titlestring

Nom du produit, 500 caractères au maximum. Vous pouvez aussi l’envoyer sous le nom name. Obligatoire pour un nouveau produit.

skustring

Référence de stock (SKU), 255 caractères au maximum.

descriptionstring

Description du produit, 10 000 caractères au maximum.

urlstring

Page du produit dans votre boutique. Une URL http ou https, 2 048 caractères au maximum.

image_urlstring

Image du produit. Une URL http ou https, 2 048 caractères au maximum.

pricenumber | string

Prix actuel, sous forme de nombre ou de chaîne numérique comme "89.00". Ne peut pas être négatif. Enregistré avec 4 décimales au maximum.

compare_at_pricenumber | string

Prix avant réduction, au même format que price. Quand il est supérieur à price, le produit est considéré comme en promotion.

currencystring

Code ISO 4217 à trois lettres, comme USD ou EUR. Les minuscules sont acceptées. Les e-mails formatent les prix du produit dans cette devise, ou en USD si elle n’est pas définie.

categoriesstring[]

50 noms de catégorie au maximum, de 191 caractères chacun au maximum. Les doublons sont supprimés.

brandstring

Nom de la marque, 191 caractères au maximum.

inventory_quantityinteger | null

Unités en stock. null signifie que vous ne suivez pas le stock. Les grilles de produits des e-mails excluent les produits à 0.

statusstring

active ou archived. Les nouveaux produits sont active. Les produits archivés sont masqués par défaut dans Lister les produits et exclus des grilles de produits.

metadataobject

Vos propres données clé-valeur, 16 Ko au maximum en JSON. Envoyer metadata remplace l’objet enregistré.

Réponse

Renvoie 201 Created avec l’objet produit quand le produit est nouveau, ou 200 OK quand un produit existant a été mis à jour. Renvoie 422 quand un champ n’est pas valide.

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"
    ]
  }
}

Récupérer un produit

Récupère un produit par son ID Emailit ou par l’ID du produit dans votre boutique. Nécessite une clé API avec la portée full.

GET/products/{id}

Paramètres de chemin

idstringObligatoire

L’ID du produit (prd_...) ou l’ID du produit dans votre boutique (external_id). Encodez pour l’URL les ID de boutique qui contiennent des caractères spéciaux.

L’objet produit

objectstring

Toujours product.

idstring

ID du produit dans Emailit (prd_...).

external_idstring

L’ID du produit dans votre boutique : l’id que vous avez envoyé. Les articles des commandes et des paniers désignent les produits par cet ID.

skustring | null

Référence de stock (SKU).

titlestring

Nom du produit.

descriptionstring | null

Description du produit.

urlstring | null

Page du produit dans votre boutique.

image_urlstring | null

Image du produit.

pricenumber | null

Prix actuel.

compare_at_pricenumber | null

Prix avant réduction. Un produit est en promotion quand compare_at_price est supérieur à price.

currencystring | null

Code ISO 4217 à trois lettres des prix.

categoriesstring[]

Noms des catégories.

brandstring | null

Nom de la marque.

inventory_quantityinteger | null

Unités en stock. null signifie que le stock n’est pas suivi. Les grilles de produits des e-mails excluent les produits à 0.

statusstring

active ou archived. Les grilles de produits des e-mails excluent les produits archivés.

metadataobject

Vos propres données clé-valeur.

created_atstring

Date d’ajout du produit, au format ISO 8601 UTC.

updated_atstring

Date de la dernière modification du produit, au format 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."
}

Mettre à jour un produit

Met à jour un produit qui est déjà dans votre catalogue. Seuls les champs envoyés changent. L’ID du produit dans votre boutique ne peut pas changer : un id dans le corps est ignoré. Nécessite une clé API avec la portée full ou events. Avec une clé events, la réponse ne contient que object, id et external_id.

Pour créer des produits et les mettre à jour avec le même appel, utilisez Créer ou mettre à jour un produit.

POST/products/{id}

Paramètres de chemin

idstringObligatoire

L’ID du produit (prd_...) ou l’ID du produit dans votre boutique.

Corps de la requête

N’importe lequel des champs de Créer ou mettre à jour un produit sauf id : title, sku, description, url, image_url, price, compare_at_price, currency, categories, brand, inventory_quantity, status et metadata. Les mêmes règles s’appliquent. categories et metadata sont remplacés en entier.

Réponse

Renvoie 200 OK avec l’objet produit mis à jour. Renvoie 404 si aucun produit ne correspond à id et 422 quand un champ n’est pas valide.

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"
    ]
  }
}

Lister les produits

Liste les produits de votre catalogue, du plus récent au plus ancien. Sans status, seuls les produits actifs sont listés. Nécessite une clé API avec la portée full.

GET/products

Paramètres de requête

pageinteger

Numéro de page pour la pagination (minimum : 1, par défaut : 1).

limitinteger

Nombre de produits à renvoyer (minimum : 1, maximum : 100, par défaut : 25).

searchstring

Correspondance insensible à la casse sur le titre, l’ID du produit dans votre boutique (external_id) ou le SKU.

categorystring

Uniquement les produits de cette catégorie. Le nom doit correspondre exactement, casse comprise.

statusstring

active (par défaut), archived ou all. Utilisez all quand vous filtrez sur la clé status ci-dessous, car la valeur par défaut limite déjà la liste aux produits actifs.

idsstring

Liste de 100 ID de produit au maximum, séparés par des virgules. Chacun peut être l’ID Emailit (prd_...) ou l’ID du produit dans votre boutique.

matchstring

all (par défaut) exige que chaque filtre key.condition corresponde. or accepte n’importe lequel d’entre eux. Consultez Filtrage et tri.

sortstring

Clé de tri : created_at (par défaut), updated_at, title ou price.

orderstring

Sens du tri : asc ou desc (par défaut).

Filtres

Les filtres de liste sont des paramètres de requête key.condition=value sur un seul niveau. Consultez Filtrage et tri pour match, order, direction et la liste des conditions par type.

Clés de filtre

Clé	Type	Conditions	Remarques
`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	Valeurs : `active`, `archived`
`created_at`	date	exact, before, after, empty, not_empty
`updated_at`	date	exact, before, after, empty, not_empty

Clés de tri

Cet endpoint trie avec sort défini sur l’une de ces clés et order sur asc ou desc (order=<key> renvoie 400 ici) : created_at, updated_at, title, price

Sur cet endpoint, order n’accepte que asc ou desc. Transmettez la clé de tri dans sort, par exemple sort=price&order=asc.

Réponse

Renvoie une page d’objets produit dans data, avec total_records, next_page_url et previous_page_url. Les URL de page ne contiennent que page et limit : ajoutez de nouveau votre recherche et vos filtres quand vous les suivez.

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
}

Créer ou mettre à jour des produits par lots

Envoie jusqu’à 1 000 produits en une requête, par exemple pour importer votre catalogue ou le synchroniser à intervalles réguliers. Chaque produit suit les règles de Créer ou mettre à jour un produit : il est créé ou mis à jour selon son id, un nouveau produit a besoin d’un title, et les champs ne sont écrits que si vous les envoyez. Nécessite une clé API avec la portée full ou events. Avec une clé events, la réponse ne contient que object, id et external_id.

Les produits non valides sont ignorés et listés dans rejected ; les autres sont enregistrés. La requête renvoie tout de même 200.

POST/products/batch

Corps de la requête

productsobject[]Obligatoire

De 1 à 1 000 produits, chacun avec les champs de Créer ou mettre à jour un produit.

Réponse

createdinteger

Nombre de nouveaux produits.

updatedinteger

Nombre de produits existants qui ont été mis à jour.

rejectedobject[]

Les produits qui n’ont pas été enregistrés. Chaque élément contient l’index du produit dans votre tableau products et errors, dont les clés sont des chemins de champ comme products.3.price.

Renvoie 422 si products est vide ou contient plus de 1 000 éléments.

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."
    ]
  }
}

Lister les catégories de produits

Liste les catégories utilisées par les produits actifs, par ordre alphabétique, avec le nombre de produits actifs dans chacune. Les produits archivés ne sont pas comptés. Renvoie 1 000 catégories au maximum, sans pagination. Nécessite une clé API avec la portée full.

Les catégories proviennent des categories de chaque produit. Utilisez un nom de catégorie avec le paramètre category de Lister les produits.

GET/products/categories

JSON

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

Supprimer un produit

Retire un produit de votre catalogue. Les commandes qui le contiennent gardent leurs articles, qui conservent leur propre titre, leur prix et l’ID du produit. Pour masquer un produit sans le supprimer, passez plutôt son status à archived. Nécessite une clé API avec la portée full.

Si le script de suivi signale la consultation d’un produit supprimé avec son titre, le produit est de nouveau ajouté au catalogue à partir des données de la page.

DELETE/products/{id}

Paramètres de chemin

idstringObligatoire

L’ID du produit (prd_...) ou l’ID du produit dans votre boutique.

JSON

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

JSON

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