API : produits

L'API produits vous permet de récupérer vos produits, de consulter leurs statistiques de ventes et de gérer l'inventaire (niveaux de stock et variantes). Les produits ne peuvent pas être créés directement via cette ressource — ils sont générés lorsqu'une commande est complétée ou lorsque vous récupérez une URL (via le tableau de bord ou le point de terminaison POST /products ci-dessous). Définissez vos produits sur votre propre site avec nos attributs HTML ou notre SDK JavaScript.

Les requêtes sont authentifiées avec votre clé API secrète, transmise comme nom d'utilisateur en authentification HTTP Basic avec un mot de passe vide. Avec curl : -u {API_KEY}:. Voir Authentification pour plus de détails.

GET /products

Retourne une liste paginée de produits accompagnés de leurs statistiques de ventes. Chaque élément est un extrait de produit.

URL de la ressource

GET https://app.snipcart.com/api/products

En-têtes

Nom	Valeur	Obligatoire?	Description
`Accept`	`application/json`	Oui	L'API ne retourne que du `application/json`.

Paramètres de requête

Nom	Obligatoire?	Type	Description
`offset`	Non	`integer`	Nombre d'éléments à ignorer. Valeur par défaut : `0`.
`limit`	Non	`integer`	Nombre maximal d'éléments à retourner. Valeur par défaut : `20`.
`orderBy`	Non	`string`	Ordre de tri. Une des valeurs `NbrSales` (les plus vendus en premier), `SalesValue` (les ventes totales les plus élevées en premier) ou `CreationDate` (les plus récents en premier). Par défaut, le tri se fait par nombre de ventes.
`userDefinedId`	Non	`string`	Filtre les produits dont l'identifiant défini par l'utilisateur contient cette valeur.
`keywords`	Non	`string`	Filtre les produits dont le nom, la description ou l'identifiant défini par l'utilisateur contient cette valeur.
`from`	Non	`datetime`	Restreint les statistiques de ventes aux commandes complétées à cette date ou après.
`to`	Non	`datetime`	Restreint les statistiques de ventes aux commandes complétées à cette date ou avant.
`archived`	Non	`boolean`	Si `true`, inclut les produits archivés. Valeur par défaut : `false` (les produits archivés sont exclus).
`excludeZeroSales`	Non	`boolean`	Si `true`, ne retourne que les produits ayant au moins une vente. Valeur par défaut : `false`.

Exemple de requête

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/products?limit=50&offset=0" \
  -u {API_KEY}:

Exemple de réponse

{
  "totalItems": 29,
  "offset": 0,
  "limit": 50,
  "items": [
    {
      "statistics": {
        "numberOfSales": 29,
        "totalSales": 608.71
      },
      "price": 20.99,
      "categories": [],
      "id": "325bfaef-d665-4c9a-a965-f5bd6ab46934",
      "userDefinedId": "HGW",
      "account_Id": 12345,
      "mode": "Test",
      "url": "/snipcart-jekyll-integration",
      "creationDate": "2016-05-25T21:21:27.213Z",
      "modificationDate": "2016-11-01T16:20:44.377Z",
      "name": "How Google Works",
      "description": "",
      "image": "https://example.com/how-google-works.jpg",
      "archived": false,
      "customFields": [],
      "metadata": {
        "votes": 95,
        "score": 336
      },
      "fileGuid": null
    },
    {
      "statistics": {
        "numberOfSales": 0,
        "totalSales": 0.0
      },
      "totalStock": 11,
      "price": 299.99,
      "categories": [],
      "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
      "userDefinedId": "AP1",
      "account_Id": 12345,
      "mode": "Test",
      "url": "/product-examples.html",
      "creationDate": "2016-11-03T12:51:04.297Z",
      "modificationDate": "2016-11-03T12:51:28.873Z",
      "name": "Android Phone",
      "description": "",
      "image": "",
      "archived": false,
      "stock": 1,
      "allowOutOfStockPurchases": false,
      "inventoryManagementMethod": "Variant",
      "customFields": [
        {
          "name": "Size",
          "type": "dropdown",
          "options": "16GB|32GB[+50.00]|128GB[+200.00]",
          "required": false,
          "value": "128GB",
          "operation": 200.00,
          "optionsArray": [
            "16GB",
            "32GB",
            "128GB"
          ]
        }
      ],
      "variants": [
        {
          "stock": 10,
          "variation": [
            { "name": "Size", "option": "16GB" },
            { "name": "Color", "option": "Black" }
          ],
          "allowOutOfStockPurchases": true
        },
        { "...": "..." }
      ],
      "metadata": null,
      "fileGuid": null
    }
  ]
}

GET /products/{id}

Retourne un seul produit par identifiant. {id} peut être soit l'identifiant unique généré par Snipcart (un GUID), soit l'identifiant défini par l'utilisateur que vous avez défini sur votre bouton d'achat.

URL de la ressource

GET https://app.snipcart.com/api/products/{id}

En-têtes

Nom	Valeur	Obligatoire?	Description
`Accept`	`application/json`	Oui	L'API ne retourne que du `application/json`.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`string`	Le GUID généré par Snipcart, ou l'identifiant défini par l'utilisateur du produit.

Exemple de requête

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/products/AP1 \
  -u {API_KEY}:

Exemple de réponse

{
  "totalStock": 11,
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": false,
  "inventoryManagementMethod": "Variant",
  "stock": 1,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "customFields": [
    {
      "name": "Size",
      "type": "dropdown",
      "options": "16GB|32GB[+50.00]|128GB[+200.00]",
      "required": false,
      "value": "128GB",
      "operation": 200.00,
      "optionsArray": [
        "16GB",
        "32GB",
        "128GB"
      ]
    }
  ],
  "variants": [
    {
      "stock": 10,
      "variation": [
        { "name": "Size", "option": "16GB" },
        { "name": "Color", "option": "Black" }
      ],
      "allowOutOfStockPurchases": true
    },
    {
      "stock": 1,
      "variation": [
        { "name": "Size", "option": "32GB" },
        { "name": "Color", "option": "Red" }
      ],
      "allowOutOfStockPurchases": false
    }
  ],
  "metadata": null
}

POST /products

Récupère l'URL passée dans le corps de la requête et importe les produits trouvés sur la page. Lorsque fetchUrl pointe vers une page HTML standard, Snipcart importe tous les boutons portant la classe CSS snipcart-add-item. Vous pouvez aussi faire pointer fetchUrl vers un document JSON — consultez l'indexeur JSON pour connaître la structure attendue.

La réponse est un tableau JSON des produits qui ont été importés.

⚠️ Important : Ce point de terminaison est soumis à une limite de débit. Ne l'appelez pas dans une boucle serrée.

URL de la ressource

POST https://app.snipcart.com/api/products

En-têtes

Nom	Valeur	Obligatoire?	Description
`Accept`	`application/json`	Oui	L'API ne retourne que du `application/json`.
`Content-Type`	`application/json`	Oui	Le corps de la requête est en JSON.

Paramètres du corps

Nom	Obligatoire?	Type	Description
`fetchUrl`	Oui	`string`	L'URL où les détails du produit seront trouvés. Si aucun schéma n'est fourni, `http://` est présumé.

Exemple de requête

curl https://app.snipcart.com/api/products \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d '{ "fetchUrl": "https://yoursite.com/products.json" }'

Exemple de réponse

[
  {
    "price": 10.00,
    "categories": [],
    "id": "3e330cf2-6962-4875-8c9d-73f337b6de3e",
    "userDefinedId": "123",
    "account_Id": 12345,
    "mode": "Test",
    "url": "/products.json",
    "name": "Product 123",
    "description": null,
    "image": null,
    "fileGuid": null,
    "creationDate": "2016-12-13T15:54:24.5595583Z",
    "modificationDate": "2016-12-13T15:54:24.5595583Z",
    "archived": false,
    "statistics": {
      "numberOfSales": 0,
      "totalSales": 0.0
    },
    "metadata": null
  },
  {
    "price": 40.00,
    "categories": [],
    "id": "c148bdb5-92ea-4c50-a7ec-46763dd1217a",
    "userDefinedId": "456",
    "account_Id": 12345,
    "mode": "Test",
    "url": "/products.json",
    "name": "Product 456",
    "description": null,
    "image": null,
    "fileGuid": null,
    "creationDate": "2016-12-13T15:54:24.5908458Z",
    "modificationDate": "2016-12-13T15:54:24.5908458Z",
    "archived": false,
    "statistics": {
      "numberOfSales": 0,
      "totalSales": 0.0
    },
    "metadata": null
  }
]

PUT /products/{id}

Met à jour les paramètres d'inventaire d'un produit. {id} peut être le GUID généré par Snipcart ou l'identifiant défini par l'utilisateur.

Comme les produits sont définis sur votre propre site plutôt que dans Snipcart, seuls les champs liés à l'inventaire peuvent être modifiés ici. Le corps de la requête est un objet produit, mais seuls inventoryManagementMethod, stock, variants et allowOutOfStockPurchases sont lus — tous les autres champs du corps sont ignorés.

⚠️ Important : La mise à jour d'un produit le désarchive également (archived est défini à false).

URL de la ressource

PUT https://app.snipcart.com/api/products/{id}

En-têtes

Nom	Valeur	Obligatoire?	Description
`Accept`	`application/json`	Oui	L'API ne retourne que du `application/json`.
`Content-Type`	`application/json`	Oui	Le corps de la requête est en JSON.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`string`	Le GUID généré par Snipcart, ou l'identifiant défini par l'utilisateur du produit. Transmis dans l'URL, et non dans le corps.

Paramètres du corps

Nom	Obligatoire?	Type	Description
`inventoryManagementMethod`	Non	`string`	La façon dont l'inventaire est suivi pour ce produit. Une des valeurs `Single`, `Variant` ou `Disabled`. Utilisez `Variant` lorsque le produit comporte des champs personnalisés `dropdown`.
`stock`	Non	`integer`	Nombre d'articles en stock. Utilisé lorsque `inventoryManagementMethod` est `Single`.
`variants`	Non	`array`	Niveaux de stock par variante. Utilisés lorsque `inventoryManagementMethod` est `Variant`. Voir les champs des variantes ci-dessous.
`allowOutOfStockPurchases`	Non	`boolean`	Si `true`, le produit peut être acheté même lorsqu'il est en rupture de stock (le stock peut devenir négatif). Si `false`, les achats en rupture de stock sont bloqués.

Chaque entrée de variants comporte les champs suivants :

Nom	Obligatoire?	Type	Description
`variation`	Oui	`array`	La combinaison qui identifie cette variante, sous forme de paires `name`/`option` correspondant aux valeurs des champs personnalisés du produit, p. ex. `[{ "name": "Size", "option": "32GB" }, { "name": "Color", "option": "Black" }]`.
`stock`	Non	`integer`	Nombre d'articles de cette variante en stock.
`allowOutOfStockPurchases`	Non	`boolean`	Si `true`, cette variante peut être achetée même lorsqu'elle est en rupture de stock (le stock peut devenir négatif). Si `false`, les achats en rupture de stock sont bloqués.

Exemple de requête

curl https://app.snipcart.com/api/products/AP1 \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d '{ "inventoryManagementMethod": "Single", "stock": 20 }'

Exemple de réponse

{
  "totalStock": 20,
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": false,
  "inventoryManagementMethod": "Single",
  "stock": 20,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "metadata": null
}

DELETE /products/{id}

Archive un produit. {id} peut être le GUID généré par Snipcart ou l'identifiant défini par l'utilisateur. Le produit archivé est retourné dans la réponse.

⚠️ Important : Cette opération ne supprime pas définitivement le produit — elle définit archived à true. Un produit archivé n'apparaît plus dans la liste de produits par défaut, mais il est automatiquement restauré s'il est de nouveau ajouté à un panier ou récupéré à nouveau.

URL de la ressource

DELETE https://app.snipcart.com/api/products/{id}

En-têtes

Nom	Valeur	Obligatoire?	Description
`Accept`	`application/json`	Oui	L'API ne retourne que du `application/json`.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`string`	Le GUID généré par Snipcart, ou l'identifiant défini par l'utilisateur du produit. Transmis dans l'URL, et non dans le corps.

Exemple de requête

curl https://app.snipcart.com/api/products/AP1 \
  -X DELETE \
  -H "Accept: application/json" \
  -u {API_KEY}:

Exemple de réponse

{
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": true,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "metadata": null
}