# Prodotti API > Tieni il catalogo del tuo negozio in Emailit per le griglie di prodotti, i consigli e le righe degli ordini. URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer `. ## Crea o aggiorna un prodotto — POST /products > Aggiungi un prodotto al catalogo, o aggiornalo, identificato dall’ID del prodotto nel tuo negozio. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). `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](/it/docs/api-reference/products/batch/). Le griglie di prodotti, i consigli e gli articoli degli ordini nelle email leggono dal catalogo. Vedi [Prodotti, coupon e carrello](/it/docs/campaigns/products-and-coupons/). `POST /products` ## Corpo della richiesta - `id` (string | number, obbligatorio): 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`. - `title` (string): Nome del prodotto, fino a 500 caratteri. Puoi inviarlo anche come `name`. Obbligatorio per un nuovo prodotto. - `sku` (string): Codice di magazzino (SKU), fino a 255 caratteri. - `description` (string): Descrizione del prodotto, fino a 10.000 caratteri. - `url` (string): Pagina del prodotto nel tuo negozio. Un URL `http` o `https`, fino a 2048 caratteri. - `image_url` (string): Immagine del prodotto. Un URL `http` o `https`, fino a 2048 caratteri. - `price` (number | 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_price` (number | string): Prezzo prima dello sconto, nello stesso formato di `price`. Quando è più alto di `price`, il prodotto risulta in saldo. - `currency` (string): 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. - `categories` (string[]): Fino a 50 nomi di categoria, di al massimo 191 caratteri ciascuno. I duplicati vengono rimossi. - `brand` (string): Nome del marchio, fino a 191 caratteri. - `inventory_quantity` (integer | null): Unità in giacenza. `null` significa che non tieni traccia della giacenza. Le griglie di prodotti nelle email escludono i prodotti a `0`. - `status` (string): `active` o `archived`. I nuovi prodotti sono `active`. I prodotti archiviati sono nascosti per impostazione predefinita in [Elenca i prodotti](/it/docs/api-reference/products/list/) ed esclusi dalle griglie di prodotti. - `metadata` (object): 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](/it/docs/api-reference/products/get/) quando il prodotto è nuovo, oppure `200 OK` quando è stato aggiornato un prodotto esistente. Restituisce `422` quando un campo non è valido. **Richiesta** `POST /products` **cURL** ```bash 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 }' ``` **201** ```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" } ``` **422** ```json { "message": "Validation failed. price: must not be negative", "errors": { "price": [ "must not be negative" ] } } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/create/ ## Recupera un prodotto — GET /products/{id} > Recupera un prodotto del catalogo tramite il suo ID Emailit o l’ID del prodotto nel tuo negozio. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). `GET /products/{id}` ## Parametri di percorso - `id` (string, obbligatorio): 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 - `object` (string): Sempre `product`. - `id` (string): ID del prodotto in Emailit (`prd_...`). - `external_id` (string): 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. - `sku` (string | null): Codice di magazzino (SKU). - `title` (string): Nome del prodotto. - `description` (string | null): Descrizione del prodotto. - `url` (string | null): Pagina del prodotto nel tuo negozio. - `image_url` (string | null): Immagine del prodotto. - `price` (number | null): Prezzo attuale. - `compare_at_price` (number | null): Prezzo prima dello sconto. Un prodotto è in saldo quando `compare_at_price` è più alto di `price`. - `currency` (string | null): Codice ISO 4217 di tre lettere dei prezzi. - `categories` (string[]): Nomi delle categorie. - `brand` (string | null): Nome del marchio. - `inventory_quantity` (integer | null): Unità in giacenza. `null` significa che la giacenza non viene tracciata. Le griglie di prodotti nelle email escludono i prodotti a `0`. - `status` (string): `active` o `archived`. Le griglie di prodotti nelle email escludono i prodotti archiviati. - `metadata` (object): Dati chiave-valore tuoi. - `created_at` (string): Quando è stato aggiunto il prodotto, in ISO 8601 UTC. - `updated_at` (string): Quando è cambiato l’ultima volta il prodotto, in ISO 8601 UTC. **Richiesta** `GET /products/{id}` **cURL** ```bash curl https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \ -H "Authorization: Bearer your_api_key" ``` **200** ```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" } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/get/ ## Aggiorna un prodotto — POST /products/{id} > Cambia alcuni campi di un prodotto del catalogo. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). Per creare prodotti e aggiornarli con la stessa chiamata, usa [Crea o aggiorna un prodotto](/it/docs/api-reference/products/create/). `POST /products/{id}` ## Parametri di percorso - `id` (string, obbligatorio): 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](/it/docs/api-reference/products/create/) 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](/it/docs/api-reference/products/get/) aggiornato. Restituisce `404` se nessun prodotto corrisponde a `id` e `422` quando un campo non è valido. **Richiesta** `POST /products/{id}` **cURL** ```bash 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 }' ``` **200** ```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" } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` **422** ```json { "message": "Validation failed. image_url: must be an http(s) URL", "errors": { "image_url": [ "must be an http(s) URL" ] } } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/update/ ## Elenca i prodotti — GET /products > Elenca i prodotti del catalogo, a partire dal più recente, con ricerca e filtri per categoria e stato. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). `GET /products` ## Parametri di query - `page` (integer): Numero di pagina per la paginazione (minimo: 1, predefinito: 1). - `limit` (integer): Numero di prodotti da restituire (minimo: 1, massimo: 100, predefinito: 25). - `search` (string): Corrispondenza sul titolo, sull’ID del prodotto nel tuo negozio (`external_id`) o sullo SKU, senza distinzione tra maiuscole e minuscole. - `category` (string): Solo i prodotti di questa categoria. Il nome deve corrispondere esattamente, maiuscole e minuscole comprese. - `status` (string): `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. - `ids` (string): 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. - `match` (string): `all` (predefinito) richiede che corrispondano tutti i filtri `key.condition`. Con `or` basta che ne corrisponda uno. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/). - `sort` (string): Chiave di ordinamento: `created_at` (predefinito), `updated_at`, `title` o `price`. - `order` (string): Direzione dell’ordinamento: `asc` o `desc` (predefinito). ## Filtri Chiavi di filtro e di ordinamento: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/). 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](/it/docs/api-reference/products/get/) 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. **Richiesta** `GET /products` **cURL** ```bash curl "https://api.emailit.com/v2/products?category=Running&sort=price&order=asc&limit=25" \ -H "Authorization: Bearer your_api_key" ``` **200** ```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 } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/list/ ## Crea o aggiorna prodotti in blocco — POST /products/batch > Invia fino a 1000 prodotti in una sola richiesta. Ognuno viene creato o aggiornato in base all’ID del prodotto nel tuo negozio. Alpha: aperto solo al team di Emailit. # 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](/it/docs/api-reference/products/create/): 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). 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 - `products` (object[], obbligatorio): Da 1 a 1000 prodotti, ognuno con i campi di [Crea o aggiorna un prodotto](/it/docs/api-reference/products/create/). ## Restituisce - `created` (integer): Numero di nuovi prodotti. - `updated` (integer): Numero di prodotti esistenti che sono stati aggiornati. - `rejected` (object[]): 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. **Richiesta** `POST /products/batch` **cURL** ```bash 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" } ] }' ``` **200** ```json { "created": 1, "updated": 1, "rejected": [ { "index": 2, "errors": { "products.2.title": [ "is required" ] } } ] } ``` **422** ```json { "message": "Validation failed. products: Send 1 to 1000 products.", "errors": { "products": [ "Send 1 to 1000 products." ] } } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/batch/ ## Elenca le categorie di prodotti — GET /products/categories > Elenca le categorie dei prodotti attivi del catalogo, con il numero di prodotti in ciascuna. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). Le categorie provengono dal campo `categories` di ogni prodotto. Usa il nome di una categoria con il parametro `category` di [Elenca i prodotti](/it/docs/api-reference/products/list/). `GET /products/categories` **Richiesta** `GET /products/categories` **cURL** ```bash curl https://api.emailit.com/v2/products/categories \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "data": [ { "name": "Accessories", "products": 18 }, { "name": "Running", "products": 12 }, { "name": "Shoes", "products": 27 } ] } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/categories/ ## Elimina un prodotto — DELETE /products/{id} > Rimuovi un prodotto dal catalogo. Alpha: aperto solo al team di Emailit. # 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`. > **L’e-commerce è in alpha:** L’e-commerce è aperto solo al team di Emailit mentre lo testiamo. Le altre richieste restituiscono `403` con `error: "commerce_alpha"`. Le chiavi API funzionano solo nei workspace di proprietà del team di Emailit. Vedi [Chi può usare l’e-commerce](/it/docs/commerce/#who-can-use-commerce). Se lo [script di tracciamento](/it/docs/commerce/connect-your-shop/#the-tracking-script) 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 - `id` (string, obbligatorio): L’ID del prodotto (`prd_...`) o l’ID del prodotto nel tuo negozio. **Richiesta** `DELETE /products/{id}` **cURL** ```bash curl -X DELETE https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "deleted": true } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` --- Fonte: https://emailit.com/it/docs/api-reference/products/delete/