API : clients

L'API des clients vous permet de lister, récupérer, mettre à jour et supprimer les clients rattachés à votre compte Snipcart, ainsi que de récupérer les commandes passées par un client donné. 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. Toutes les requêtes et réponses utilisent application/json.

⚠️ Important : Un « client » est un User Snipcart. Les clients avec le status Confirmed ont créé un compte avec un mot de passe; les clients Unconfirmed ont passé leur commande en tant qu'invités. Les points de terminaison de liste et de client individuel retournent le client sous une forme à plat (champs d'adresse préfixés billingAddress* / shippingAddress*), tandis que PUT retourne une forme différente, imbriquée (objets billingAddress / shippingAddress). Voir l'encadré sur PUT /customers/{id}.

Table des matières

GET /customers

Retourne une liste paginée des clients de votre compte, triée par défaut selon le nombre de commandes.

URL de la ressource

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

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 int Nombre de résultats à ignorer. Par défaut : 0.
limit Non int Nombre de résultats à retourner. Par défaut : 20.
status Non string Filtre par statut du client. L'une des valeurs Unconfirmed, Confirmed.
email Non string Filtre vers le client ayant ce courriel exact.
name Non string Filtre vers les clients dont le nom de facturation contient cette valeur.
from Non datetime Retourne uniquement les clients créés à partir de cette date.
to Non datetime Retourne uniquement les clients créés jusqu'à cette date.
orderBy Non string Ordre de tri. L'une des valeurs OrdersValue, NbrOrders, Date.

Exemple de requête 

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

Exemple de réponse 

{
    "totalItems": 10,
    "offset": 0,
    "limit": 50,
    "items": [
        {
            "id": "c8de947a-2483-4e36-9052-031e2aa3f0ac",
            "email": "geeks@snipcart.com",
            "mode": "Live",
            "statistics": {
                "ordersCount": 10,
                "ordersAmount": 1000.00,
                "subscriptionsCount": 0
            },
            "creationDate": "2019-10-09T18:52:19Z",
            "shippingAddressSameAsBilling": true,
            "status": "Confirmed",
            "gravatarUrl": "https://www.gravatar.com/avatar/...?s=70&d=...",
            "billingAddressFirstName": "Geeks",
            "billingAddressName": "Snipcart",
            "billingAddressCompanyName": "Snipcart",
            "billingAddressAddress1": "4885 1ere Avenue",
            "billingAddressAddress2": null,
            "billingAddressCity": "Québec",
            "billingAddressCountry": "CA",
            "billingAddressProvince": "QC",
            "billingAddressPostalCode": "G1H2T5",
            "billingAddressPhone": "",
            "shippingAddressFirstName": "Geeks",
            "shippingAddressName": "Snipcart",
            "shippingAddressCompanyName": "Snipcart",
            "shippingAddressAddress1": "4885 1ere Avenue",
            "shippingAddressAddress2": null,
            "shippingAddressCity": "Québec",
            "shippingAddressCountry": "CA",
            "shippingAddressProvince": "QC",
            "shippingAddressPostalCode": "G1H2T5",
            "shippingAddressPhone": "",
            "sessionToken": null
        },
        ...
    ]
}

GET /customers/{id}

Retourne un client unique par son identifiant, dans la même forme à plat que le point de terminaison de liste.

URL de la ressource

GET https://app.snipcart.com/api/customers/{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 Guid L'identifiant unique du client.

Exemple de requête 

curl -H "Accept: application/json" \
    https://app.snipcart.com/api/customers/c8de947a-2483-4e36-9052-031e2aa3f0ac \
    -u {API_KEY}:

Exemple de réponse 

{
    "id": "c8de947a-2483-4e36-9052-031e2aa3f0ac",
    "email": "geeks@snipcart.com",
    "mode": "Live",
    "statistics": {
        "ordersCount": 10,
        "ordersAmount": 1000.00,
        "subscriptionsCount": 0
    },
    "creationDate": "2019-10-09T18:52:19Z",
    "shippingAddressSameAsBilling": true,
    "status": "Unconfirmed",
    "gravatarUrl": "https://www.gravatar.com/avatar/...?s=70&d=...",
    "billingAddressFirstName": "Geeks",
    "billingAddressName": "Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": null,
    "billingAddressCity": "Québec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "",
    "shippingAddressFirstName": "Geeks",
    "shippingAddressName": "Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": null,
    "shippingAddressCity": "Québec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "",
    "sessionToken": null
}

GET /customers/{id}/orders

Retourne toutes les commandes passées par le client donné (les commandes encore en cours sont exclues). Chaque élément est une commande complète, dans la même forme que l'API des commandes; l'exemple ci-dessous est abrégé.

URL de la ressource

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

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 Guid L'identifiant unique du client.

Exemple de requête 

curl -H "Accept: application/json" \
    https://app.snipcart.com/api/customers/c8de947a-2483-4e36-9052-031e2aa3f0ac/orders \
    -u {API_KEY}:

Exemple de réponse 

[
    {
        "token": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70",
        "creationDate": "2019-10-21T20:36:26.46Z",
        "modificationDate": "2019-10-21T20:36:26.46Z",
        "status": "Processed",
        "paymentMethod": "CreditCard",
        "email": "geeks@snipcart.com",
        "cardHolderName": "Geeks Snipcart",
        "creditCardLast4Digits": "4242",
        "currency": "usd",
        "finalGrandTotal": 443.00,
        "shippingFees": 0,
        "shippingMethod": "Free shipping",
        "billingAddressName": "Snipcart",
        "billingAddressCountry": "CA",
        "shippingAddressSameAsBilling": true,
        "willBePaidLater": false,
        "customFieldsJson": "[]",
        ...
    },
    ...
]

PUT /customers/{id}

Met à jour un client existant. Seuls email, billingAddress et shippingAddress (et un cartToken facultatif) sont acceptés dans le corps, et ils sont fournis sous forme d'objets d'adresse imbriqués.

⚠️ Important : Contrairement aux points de terminaison de liste et de client individuel, le corps de la requête et la réponse de PUT utilisent tous deux des objets billingAddress / shippingAddress imbriqués (avec les champs name, firstName, company, address1, address2, city, province, country, postalCode, phone, vatNumber). La réponse est un CustomerDto, et non l'entité client à plat — ses adresses sont imbriquées et elle expose confirmed (booléen) au lieu de la chaîne status à plat.

URL de la ressource

PUT https://app.snipcart.com/api/customers/{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 doit être du JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui Guid L'identifiant unique du client.

Paramètres du corps

Nom Obligatoire? Type Description
email Oui string L'adresse courriel du client (max. 500 caractères).
billingAddress Non object Adresse de facturation imbriquée (name, firstName, company, address1, address2, city, province, country, postalCode, phone, vatNumber).
shippingAddress Non object Adresse de livraison imbriquée, mêmes champs que billingAddress.
cartToken Non string Jeton de panier facultatif à associer à la mise à jour.

Exemple de requête 

curl -X PUT \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -u {API_KEY}: \
    -d '{
        "email": "geeks@snipcart.com",
        "billingAddress": {
            "name": "Geeks Snipcart",
            "address1": "4885 1ere Avenue",
            "city": "Québec",
            "country": "CA",
            "province": "QC",
            "postalCode": "G1H2T5"
        },
        "shippingAddress": {
            "name": "Geeks Snipcart",
            "address1": "4885 1ere Avenue",
            "city": "Québec",
            "country": "CA",
            "province": "QC",
            "postalCode": "G1H2T5"
        }
    }' \
    https://app.snipcart.com/api/customers/c8de947a-2483-4e36-9052-031e2aa3f0ac

Exemple de réponse 

{
    "id": "c8de947a-2483-4e36-9052-031e2aa3f0ac",
    "email": "geeks@snipcart.com",
    "mode": "Live",
    "statistics": {
        "ordersCount": 10,
        "ordersAmount": 1000.00,
        "subscriptionsCount": 0
    },
    "creationDate": "2019-10-09T18:52:19Z",
    "gravatarUrl": "https://www.gravatar.com/avatar/...?s=70&d=...",
    "confirmed": true,
    "billingAddress": {
        "fullName": "Geeks Snipcart",
        "firstName": null,
        "name": "Geeks Snipcart",
        "company": null,
        "address1": "4885 1ere Avenue",
        "address2": null,
        "fullAddress": "4885 1ere Avenue",
        "city": "Québec",
        "country": "CA",
        "postalCode": "G1H2T5",
        "province": "QC",
        "phone": null,
        "vatNumber": null
    },
    "shippingAddress": {
        "fullName": "Geeks Snipcart",
        "name": "Geeks Snipcart",
        "address1": "4885 1ere Avenue",
        "city": "Québec",
        "country": "CA",
        "postalCode": "G1H2T5",
        "province": "QC",
        ...
    }
}

DELETE /customers/{id}

Supprime un client. Retourne 204 No Content en cas de succès, ou 404 Not Found si aucun client ne correspond à l'identifiant.

URL de la ressource

DELETE https://app.snipcart.com/api/customers/{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 Guid L'identifiant unique du client.

Exemple de requête 

curl -X DELETE \
    -H "Accept: application/json" \
    -u {API_KEY}: \
    https://app.snipcart.com/api/customers/c8de947a-2483-4e36-9052-031e2aa3f0ac

Exemple de réponse 

204 No Content