Prodotti

Tieni il catalogo del tuo negozio in Emailit per le griglie di prodotti, i consigli e le righe degli ordini.

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

Crea o aggiorna un prodotto

Aggiungi un prodotto al catalogo, oppure aggiornalo se esiste già un prodotto con lo stesso id. L’id è l’ID del prodotto nel tuo negozio, quindi puoi inviare di nuovo lo stesso prodotto ogni volta che cambia. Richiede una chiave API con il permesso full o events. Con una chiave events, la risposta contiene solo object, id e external_id.

id è sempre obbligatorio e title è obbligatorio per un nuovo prodotto. I campi vengono scritti solo quando li invii, quindi un prodotto che invii di nuovo con il solo nuovo prezzo mantiene titolo, categorie, immagine e tutto il resto. Per inviare molti prodotti in una volta, usa Crea o aggiorna prodotti in blocco.

Le griglie di prodotti, i consigli e gli articoli degli ordini nelle email leggono dal catalogo. Vedi Prodotti, coupon e carrello.

POST/products

Corpo della richiesta

idstring | numberObbligatorio

L’ID del prodotto nel tuo negozio, fino a 255 caratteri. I numeri vengono salvati come stringhe. Salvato come external_id. Puoi inviarlo anche come external_id.

titlestring

Nome del prodotto, fino a 500 caratteri. Puoi inviarlo anche come name. Obbligatorio per un nuovo prodotto.

skustring

Codice di magazzino (SKU), fino a 255 caratteri.

descriptionstring

Descrizione del prodotto, fino a 10.000 caratteri.

urlstring

Pagina del prodotto nel tuo negozio. Un URL http o https, fino a 2048 caratteri.

image_urlstring

Immagine del prodotto. Un URL http o https, fino a 2048 caratteri.

pricenumber | string

Prezzo attuale, come numero o stringa numerica, ad esempio "89.00". Non può essere negativo. Salvato con al massimo 4 cifre decimali.

compare_at_pricenumber | string

Prezzo prima dello sconto, nello stesso formato di price. Quando è più alto di price, il prodotto risulta in saldo.

currencystring

Codice ISO 4217 di tre lettere, come USD o EUR. Le minuscole sono accettate. Le email formattano i prezzi del prodotto in questa valuta, oppure in USD quando non è impostata.

categoriesstring[]

Fino a 50 nomi di categoria, di al massimo 191 caratteri ciascuno. I duplicati vengono rimossi.

brandstring

Nome del marchio, fino a 191 caratteri.

inventory_quantityinteger | null

Unità in giacenza. null significa che non tieni traccia della giacenza. Le griglie di prodotti nelle email escludono i prodotti a 0.

statusstring

active o archived. I nuovi prodotti sono active. I prodotti archiviati sono nascosti per impostazione predefinita in Elenca i prodotti ed esclusi dalle griglie di prodotti.

metadataobject

Dati chiave-valore tuoi, fino a 16 KB in JSON. Se invii metadata, l’oggetto salvato viene sostituito.

Restituisce

201 Created con l’oggetto prodotto quando il prodotto è nuovo, oppure 200 OK quando è stato aggiornato un prodotto esistente. Restituisce 422 quando un campo non è valido.

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

Recupera un prodotto

Recupera un prodotto tramite il suo ID Emailit o l’ID del prodotto nel tuo negozio. Richiede una chiave API con il permesso full.

GET/products/{id}

Parametri di percorso

idstringObbligatorio

L’ID del prodotto (prd_...) o l’ID del prodotto nel tuo negozio (external_id). Codifica nell’URL gli ID del negozio che contengono caratteri speciali.

L’oggetto prodotto

objectstring

Sempre product.

idstring

ID del prodotto in Emailit (prd_...).

external_idstring

L’ID del prodotto nel tuo negozio: l’id che hai inviato. Gli articoli degli ordini e dei carrelli fanno riferimento ai prodotti con questo ID.

skustring | null

Codice di magazzino (SKU).

titlestring

Nome del prodotto.

descriptionstring | null

Descrizione del prodotto.

urlstring | null

Pagina del prodotto nel tuo negozio.

image_urlstring | null

Immagine del prodotto.

pricenumber | null

Prezzo attuale.

compare_at_pricenumber | null

Prezzo prima dello sconto. Un prodotto è in saldo quando compare_at_price è più alto di price.

currencystring | null

Codice ISO 4217 di tre lettere dei prezzi.

categoriesstring[]

Nomi delle categorie.

brandstring | null

Nome del marchio.

inventory_quantityinteger | null

Unità in giacenza. null significa che la giacenza non viene tracciata. Le griglie di prodotti nelle email escludono i prodotti a 0.

statusstring

active o archived. Le griglie di prodotti nelle email escludono i prodotti archiviati.

metadataobject

Dati chiave-valore tuoi.

created_atstring

Quando è stato aggiunto il prodotto, in ISO 8601 UTC.

updated_atstring

Quando è cambiato l’ultima volta il prodotto, in 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."
}

Aggiorna un prodotto

Aggiorna un prodotto già presente nel catalogo. Cambiano solo i campi che invii. L’ID del prodotto nel tuo negozio non può cambiare: un id nel corpo viene ignorato. Richiede una chiave API con il permesso full o events. Con una chiave events, la risposta contiene solo object, id e external_id.

Per creare prodotti e aggiornarli con la stessa chiamata, usa Crea o aggiorna un prodotto.

POST/products/{id}

Parametri di percorso

idstringObbligatorio

L’ID del prodotto (prd_...) o l’ID del prodotto nel tuo negozio.

Corpo della richiesta

Uno qualsiasi dei campi di Crea o aggiorna un prodotto tranne id: title, sku, description, url, image_url, price, compare_at_price, currency, categories, brand, inventory_quantity, status e metadata. Valgono le stesse regole. categories e metadata vengono sostituiti per intero.

Restituisce

200 OK con l’oggetto prodotto aggiornato. Restituisce 404 se nessun prodotto corrisponde a id e 422 quando un campo non è valido.

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

Elenca i prodotti

Elenca i prodotti del catalogo, a partire dal più recente. Senza status vengono elencati solo i prodotti attivi. Richiede una chiave API con il permesso full.

GET/products

Parametri di query

pageinteger

Numero di pagina per la paginazione (minimo: 1, predefinito: 1).

limitinteger

Numero di prodotti da restituire (minimo: 1, massimo: 100, predefinito: 25).

searchstring

Corrispondenza sul titolo, sull’ID del prodotto nel tuo negozio (external_id) o sullo SKU, senza distinzione tra maiuscole e minuscole.

categorystring

Solo i prodotti di questa categoria. Il nome deve corrispondere esattamente, maiuscole e minuscole comprese.

statusstring

active (predefinito), archived o all. Usa all quando filtri sulla chiave status qui sotto, perché il valore predefinito limita già l’elenco ai prodotti attivi.

idsstring

Elenco separato da virgole di al massimo 100 ID di prodotto. Ognuno può essere l’ID Emailit (prd_...) o l’ID del prodotto nel tuo negozio.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri key.condition. Con or basta che ne corrisponda uno. Vedi Filtri e ordinamento.

sortstring

Chiave di ordinamento: created_at (predefinito), updated_at, title o price.

orderstring

Direzione dell’ordinamento: asc o desc (predefinito).

Filtri

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

Chiave	Tipo	Condizioni	Note
`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	Valori: `active`, `archived`
`created_at`	date	exact, before, after, empty, not_empty
`updated_at`	date	exact, before, after, empty, not_empty

Chiavi di ordinamento

Questo endpoint ordina con sort impostato su una di queste chiavi e order impostato su asc o desc (qui order=<key> restituisce 400): created_at, updated_at, title, price

In questo endpoint, order accetta solo asc o desc. Passa la chiave di ordinamento in sort, ad esempio sort=price&order=asc.

Restituisce

Una pagina di oggetti prodotto in data, con total_records, next_page_url e previous_page_url. Gli URL delle pagine riportano solo page e limit, quindi aggiungi di nuovo la ricerca e i filtri quando li segui.

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
}

Crea o aggiorna prodotti in blocco

Invia fino a 1000 prodotti in una sola richiesta, ad esempio per importare il catalogo o per sincronizzarlo a intervalli regolari. Ogni prodotto segue le regole di Crea o aggiorna un prodotto: viene creato o aggiornato in base al suo id, un nuovo prodotto richiede un title e i campi vengono scritti solo quando li invii. Richiede una chiave API con il permesso full o events. Con una chiave events, la risposta contiene solo object, id e external_id.

I prodotti non validi vengono saltati ed elencati in rejected; gli altri vengono salvati. La richiesta restituisce comunque 200.

POST/products/batch

Corpo della richiesta

productsobject[]Obbligatorio

Da 1 a 1000 prodotti, ognuno con i campi di Crea o aggiorna un prodotto.

Restituisce

createdinteger

Numero di nuovi prodotti.

updatedinteger

Numero di prodotti esistenti che sono stati aggiornati.

rejectedobject[]

Prodotti che non sono stati salvati. Ogni elemento ha l’index del prodotto nel tuo array products ed errors, con chiavi che sono percorsi di campo come products.3.price.

Restituisce 422 se products è vuoto o ha più di 1000 elementi.

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

Elenca le categorie di prodotti

Elenca le categorie usate dai prodotti attivi, in ordine alfabetico, con il numero di prodotti attivi in ciascuna. I prodotti archiviati non vengono contati. Restituisce fino a 1000 categorie e non è paginato. Richiede una chiave API con il permesso full.

Le categorie provengono dal campo categories di ogni prodotto. Usa il nome di una categoria con il parametro category di Elenca i prodotti.

GET/products/categories

JSON

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

Elimina un prodotto

Rimuovi un prodotto dal catalogo. Gli ordini che lo contengono mantengono i loro articoli, che salvano titolo, prezzo e ID del prodotto per conto proprio. Per nascondere un prodotto senza eliminarlo, imposta invece il suo status su archived. Richiede una chiave API con il permesso full.

Se lo script di tracciamento registra una visualizzazione di un prodotto eliminato con il suo titolo, il prodotto viene aggiunto di nuovo al catalogo con i dati della pagina.

DELETE/products/{id}

Parametri di percorso

idstringObbligatorio

L’ID del prodotto (prd_...) o l’ID del prodotto nel tuo negozio.

JSON

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

JSON

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