Customers API

The Customers API lets you list, retrieve, update and delete the customers attached to your Snipcart account, and fetch the orders a given customer has placed. Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details. All requests and responses use application/json.

⚠️ Important: A "customer" is a Snipcart User. Customers with status Confirmed created an account with a password; Unconfirmed customers checked out as guests. The list and single-customer endpoints return the customer in a flat shape (address fields prefixed billingAddress* / shippingAddress*), while PUT returns a different, nested shape (billingAddress / shippingAddress objects). See the callout on PUT /customers/{id}.

Table of contents

GET /customers

Returns a paginated list of the customers on your account, ordered by number of orders by default.

Resource URL

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

Headers

Name Value Required Description
Accept application/json Yes The API only returns application/json.

Query Parameters

Name Required Type Description
offset No integer Number of results to skip. Default is 0.
limit No integer Number of results to return. Default is 20.
status No string Filter by customer status. One of Unconfirmed, Confirmed.
email No string Filter to the customer with this exact email.
name No string Filter to customers whose billing name contains this value.
from No datetime Return only customers created on or after this date.
to No datetime Return only customers created on or before this date.
orderBy No string Sort order. One of OrdersValue, NbrOrders, Date.

Example request 

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

Example response 

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

Returns a single customer by ID, in the same flat shape as the list endpoint.

Resource URL

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

Headers

Name Value Required Description
Accept application/json Yes The API only returns application/json.

Path Parameters

Name Required Type Description
id Yes Guid The customer's unique ID.

Example request 

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

Example response 

{
    "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

Returns every order placed by the given customer (orders still in progress are excluded). Each entry is a full order in the same shape as the Orders API; the example below is abridged.

Resource URL

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

Headers

Name Value Required Description
Accept application/json Yes The API only returns application/json.

Path Parameters

Name Required Type Description
id Yes Guid The customer's unique ID.

Example request 

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

Example response 

[
    {
        "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}

Updates an existing customer. Only email, billingAddress and shippingAddress (and an optional cartToken) are accepted in the body, and they are supplied as nested address objects.

⚠️ Important: Unlike the list and single-customer endpoints, both the request body and the response of PUT use nested billingAddress / shippingAddress objects (with fields name, firstName, company, address1, address2, city, province, country, postalCode, phone, vatNumber). The response is a CustomerDto, not the flat customer entity — its addresses are nested and it also exposes confirmed (boolean) instead of the flat status string.

Resource URL

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

Headers

Name Value Required Description
Accept application/json Yes The API only returns application/json.
Content-Type application/json Yes The request body must be JSON.

Path Parameters

Name Required Type Description
id Yes Guid The customer's unique ID.

Body Parameters

Name Required Type Description
email Yes string The customer's email address (max 500 characters).
billingAddress No object Nested billing address (name, firstName, company, address1, address2, city, province, country, postalCode, phone, vatNumber).
shippingAddress No object Nested shipping address, same fields as billingAddress.
cartToken No string Optional cart token to associate with the update.

Example request 

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

Example response 

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

Deletes a customer. Returns 204 No Content on success, or 404 Not Found if no customer matches the ID.

Resource URL

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

Headers

Name Value Required Description
Accept application/json Yes The API only returns application/json.

Path Parameters

Name Required Type Description
id Yes Guid The customer's unique ID.

Example request 

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

Example response 

204 No Content

Was this article helpful?