Events

Basics

To bind to Snipcart events, you will need to use our subscribe public method:

Snipcart.subscribe('{eventName}', callback);

To unbind from an event, you can use the unsubscribe public method:

Snipcart.unsubscribe('{eventName}');

This event is triggered once snipcart.js file and lazy loaded localization files are finished loading. It may be useful when you need to override resources that are in any localization files other than the english one.

Usage

Snipcart.subscribe('app.ready', function() {
    console.log('app is ready');
});

cart.ready

This event is triggered once Snipcart has finished loading its initial state.

Usage

Snipcart.subscribe('cart.ready', function (data) {
    console.log(data);
});

Callback

The callback method will receive the current order information.

{
    "order": {
        "token": "f2930cf0-4dee-4fdb-b662-046a53050c74",
        "email": "geeks@snipcart.com",
        "mode": "Test",
        "status": "InProgress",
        "shipToBillingAddress": true,
        "billingAddress": {
            "name": "John Doe",
            "company": "Snipcart",
            "address1": "226 rue St-Joseph Est",
            "address2": "",
            "city": "Quebec",
            "country": "CA",
            "postalCode": "G1K3A9",
            "province": "QC",
            "phone": "418 888 8888"
        },
        "shippingAddress": {
            "name": "John Doe",
            "company": "Snipcart",
            "address1": "226 rue St-Joseph Est",
            "address2": "",
            "city": "Quebec",
            "country": "CA",
            "postalCode": "G1K3A9",
            "province": "QC",
            "phone": "418 888 8888"
        },
        "shippingInformation": {
            "fees": 20,
            "method": "Worldwide"
        },
        "items": [{
            "quantity": 1,
            "stackable": true,
            "uniqueId": "17c2ad4d-1471-4bd1-bf1a-64878b393a41",
            "token": "f2930cf0-4dee-4fdb-b662-046a53050c74",
            "id": "1",
            "name": "A poster",
            "price": 300,
            "description": "An awesome Nicolas Cage's poster",
            "url": "https://snipcart.com",
            "image": "http://placecage.com/50/50",
            "minQuantity": null,
            "maxQuantity": null,
            "shippable": true,
            "taxable": true,
            "taxes": [],
            "customFields": [],
            "duplicatable": false,
            "alternatePrices": {},
            "unitPrice": 300,
            "totalPrice": 300,
            "addedOn": "2016-04-07T19:39:08.167Z",
            "dimensions": {}
        }, {
            "quantity": 2,
            "stackable": true,
            "uniqueId": "d0e374b3-cb70-4e85-a1bc-e710b6384b39",
            "token": "f2930cf0-4dee-4fdb-b662-046a53050c74",
            "id": "SMARTPHONE",
            "name": "Smartphone",
            "price": 399,
            "description": "",
            "url": "/",
            "image": "",
            "minQuantity": null,
            "maxQuantity": null,
            "shippable": true,
            "taxable": true,
            "taxes": [],
            "customFields": [{
                "name": "Memory size",
                "options": "16GB|32GB[+50.00]",
                "type": "dropdown",
                "value": "32GB",
                "operation": "+50.00",
                "required": false,
                "sanitizedName": "snipcart_custom_Memory-size"
            }],
            "duplicatable": false,
            "alternatePrices": {},
            "unitPrice": 449,
            "totalPrice": 898,
            "addedOn": "2016-04-07T19:39:07.883Z",
            "dimensions": {}
        }],
        "discounts": [{
            "id": "b0e96b51-78d3-4a7c-8103-1ced2e0b6d8b",
            "amountSaved": 20,
            "name": "20$ off",
            "type": "FixedAmount",
            "trigger": "Code",
            "code": "Snipcart rocks",
            "affectedItems": []
        }],
        "customFields": [],
        "plans": [],
        "currency": "cad",
        "total": 1198
    }
}

cart.opened

This event is triggered when Snipcart shows up.

Usage

Snipcart.subscribe('cart.opened', function() {
    console.log('Snipcart popup is visible');
});

cart.closed

This event is triggered when the Snipcart popup is closed.

Usage

Snipcart.subscribe('cart.closed', function() {
    console.log('Snipcart popup has been closed');
});

order.completed

This event is triggered when an order has just been paid; this can be useful if you want to show your customers a special notice or if you want to integrate with third-party analytics tools.

Usage

Snipcart.subscribe('order.completed', function (data) {
    console.log(data);
});

Callback

The callback method receives an object containing all the order information.

{
    "token": "6bb9a364-0f3b-4b02-ad09-910151e89591",
    "email": "geeks@snipcart.com",
    "mode": "Test",
    "status": "Processed",
    "currency": "cad",
    "customFields": [{
        "name": "Slug",
        "options": "",
        "type": "textbox",
        "value": "Test",
        "required": true
    }, {
        "name": "Do you accept terms",
        "options": "true|false",
        "type": "checkbox",
        "value": "true",
        "required": true,
    }],
    "shipToBillingAddress": true,
    "billingAddress": {
        "name": "John Doe",
        "company": "Snipcart",
        "address1": "226 rue St-Joseph E",
        "address2": "",
        "city": "Quebec",
        "country": "CA",
        "postalCode": "G1K3A9",
        "province": "QC",
        "phone": "418 888 8888",
        "email": "geeks@snipcart.com",
        "shippingSameAsBilling": true,
        "errors": null
    },
    "completionDate": "2016-04-09T14:07:09.0508127Z",
    "invoiceNumber": "SNIP-1004",
    "paymentMethod": "CreditCard",
    "items": [{
        "uniqueId": "ab3a830d-0dad-4d0e-899e-06375694429b",
        "id": "1",
        "name": "Un poster",
        "price": 300,
        "description": "Un beau poster de Nicolas Cage",
        "url": "//localhost:3005",
        "quantity": 1,
        "stackable": true,
        "token": "6bb9a364-0f3b-4b02-ad09-910151e89591",
        "image": "http://placecage.com/50/50",
        "minQuantity": null,
        "maxQuantity": null,
        "shippable": true,
        "taxable": true,
        "taxes": [],
        "customFields": [],
        "duplicatable": false,
        "alternatePrices": {
            "vip": 200
        },
        "unitPrice": 300,
        "totalPrice": 300,
        "addedOn": "2016-04-09T14:05:38.463Z",
        "dimensions": {}
    }, {
        "uniqueId": "83283ac8-999c-41f6-8163-962d4315a059",
        "id": "SMARTPHONE",
        "name": "Smartphone",
        "price": 399,
        "description": "",
        "url": "/",
        "quantity": 2,
        "stackable": true,
        "token": "6bb9a364-0f3b-4b02-ad09-910151e89591",
        "image": "",
        "minQuantity": null,
        "maxQuantity": null,
        "shippable": true,
        "taxable": true,
        "taxes": [],
        "customFields": [{
            "name": "Memory size",
            "options": "16GB|32GB[+50.00]",
            "type": "dropdown",
            "value": "32GB",
            "operation": "50",
            "required": false,
            "sanitizedName": "snipcart_custom_Memory-size"
        }],
        "duplicatable": false,
        "alternatePrices": {
            "vip": 299
        },
        "unitPrice": 449,
        "totalPrice": 898,
        "addedOn": "2016-04-09T14:04:59.32Z",
        "dimensions": {}
    }],
    "discounts": [{
        "id": "a0518987-4e6f-4969-9ea8-58c65c027f4b",
        "amountSaved": 20,
        "name": "20$ off",
        "type": "FixedAmount",
        "trigger": "Code",
        "code": "Snipcart rocks",
        "affectedItems": []
    }],
    "plans": [],
    "total": 1365.9,
    "taxes": [{
        "name": "GST",
        "rate": 0.05,
        "amount": 59.4,
        "numberForInvoice": ""
    }, {
        "name": "QST",
        "rate": 0.09975,
        "amount": 118.5,
        "numberForInvoice": ""
    }],
    "shippingAddress": {
        "name": "John Doe",
        "company": "Snipcart",
        "address1": "226 rue St-Joseph E",
        "address2": "",
        "city": "Quebec",
        "country": "CA",
        "postalCode": "G1K3A9",
        "province": "QC",
        "phone": "418 888 8888",
        "email": "geeks@snipcart.com",
        "shippingSameAsBilling": true
    },
    "shippingInformation": {
        "method": "Livraison",
        "fees": 10
    },
    "card": {
        "last4Digits": "4242",
        "ownerName": "John Doe",
        "type": "Visa"
    }
}

item.adding

This event is triggered before the item is added to the cart. You will receive an event object in the callback method, if you call the preventDefault on it, the item will not be added.

Usage

Snipcart.subscribe('item.adding', function (ev, item, items) {
    // You can call preventDefault method in event object if you don't want to add
    // the item to the cart.
    ev.preventDefault();
});

Callback

You will receive an event object as the first parameter that exposes the preventDefault method that will prevent the item from being added to the cart.

The second parameter is the item that is about to be added.

{   
    "id": 1,
    "name": "Nicolas Cage's poster",
    "description": "A nice poster",
    "image": "http://placecage.com/50/50",
    "customFields": [],
    "minQuantity": 2,
    "stackable": true,
    "duplicatable": false,
    "price": 300,
    "url": "/",
    "dimensions": {
        "weight": 3000,
        "width": 64,
        "height": 49,
        "length": 16
    },
    "shippable": true,
    "taxable": true,
    "alternatePrices": {
        "vip": 200
    }
}```

The third parameter is the list of the items that are already in the cart.

```json
[{
    "id": "SMARTPHONE",
    "name": "Smartphone",
    "description": "",
    "image": "",
    "quantity": 1,
    "stackable": true,
    "customFields": [{
        "name": "Memory size",
        "options": "16GB|32GB[+50.00]",
        "type": "dropdown",
        "value": "",
        "required": false,
    }],
    "minQuantity": null,
    "maxQuantity": null,
    "duplicatable": false,
    "price": 399,
    "url": "/",
    "dimensions": {
        "weight": null,
        "width": null,
        "height": null,
        "length": null
    },
    "shippable": true,
    "taxable": true,
    "alternatePrices": {
        "vip": 299
    },
    "uniqueId": "681cc8b3-c27b-46cd-b9b6-5db9cc9cb437",
    "token": "80366cad-b975-4251-bee3-c3c7e388f599",
    "taxes": [],
    "unitPrice": 399,
    "totalPrice": 399,
    "addedOn": "2016-04-09T18:47:49.9994325Z"
}]

item.added

This event is triggered when an item is added to the cart; it contains the newly added item details.

Usage

Snipcart.subscribe('item.added', function (item) {
    console.log(item);
});

Callback

The callback method contains order item information.

{
    "id": "SMARTPHONE",
    "name": "Smartphone",
    "description": "",
    "image": "",
    "quantity": 1,
    "stackable": true,
    "customFields": [{
        "name": "Memory size",
        "options": "16GB|32GB[+50.00]",
        "type": "dropdown",
        "value": "",
        "required": false,
    }],
    "minQuantity": null,
    "maxQuantity": null,
    "duplicatable": false,
    "price": 399,
    "url": "/",
    "dimensions": {
        "weight": null,
        "width": null,
        "height": null,
        "length": null
    },
    "shippable": true,
    "taxable": true,
    "alternatePrices": {
        "vip": 299
    },
    "uniqueId": "681cc8b3-c27b-46cd-b9b6-5db9cc9cb437",
    "token": "80366cad-b975-4251-bee3-c3c7e388f599",
    "taxes": [],
    "unitPrice": 399,
    "totalPrice": 399,
    "addedOn": "2016-04-09T18:47:49.9994325Z"
}

item.updated

This event is triggered when an item is updated in the cart; it contains the new item's details.

Usage

Snipcart.subscribe('item.updated', function (item) {
    console.log(item);
});

Callback

The callback method contains order item information.

{
    "id": "SMARTPHONE",
    "name": "Smartphone",
    "description": "",
    "image": "",
    "quantity": 2,
    "stackable": true,
    "customFields": [{
        "name": "Memory size",
        "options": "16GB|32GB[+50.00]",
        "type": "dropdown",
        "value": "",
        "required": false,
    }],
    "minQuantity": null,
    "maxQuantity": null,
    "duplicatable": false,
    "price": 399,
    "url": "/",
    "dimensions": {
        "weight": null,
        "width": null,
        "height": null,
        "length": null
    },
    "shippable": true,
    "taxable": true,
    "alternatePrices": {
        "vip": 299
    },
    "uniqueId": "681cc8b3-c27b-46cd-b9b6-5db9cc9cb437",
    "token": "80366cad-b975-4251-bee3-c3c7e388f599",
    "taxes": [],
    "unitPrice": 399,
    "totalPrice": 399,
    "addedOn": "2016-04-09T18:47:49.9994325Z"
}

item.removed

This event is triggered when an item is removed from the cart; it contains the removed item details.

Usage

Snipcart.subscribe('item.removed', function (item) {
   console.log(item);
});

Callback

The callback method contains order item information.

{
    "id": "SMARTPHONE",
    "name": "Smartphone",
    "description": "",
    "image": "",
    "quantity": 1,
    "stackable": true,
    "customFields": [{
        "name": "Memory size",
        "options": "16GB|32GB[+50.00]",
        "type": "dropdown",
        "value": "",
        "required": false,
    }],
    "minQuantity": null,
    "maxQuantity": null,
    "duplicatable": false,
    "price": 399,
    "url": "/",
    "dimensions": {
        "weight": null,
        "width": null,
        "height": null,
        "length": null
    },
    "shippable": true,
    "taxable": true,
    "alternatePrices": {
        "vip": 299
    },
    "uniqueId": "681cc8b3-c27b-46cd-b9b6-5db9cc9cb437",
    "token": "80366cad-b975-4251-bee3-c3c7e388f599",
    "taxes": [],
    "unitPrice": 399,
    "totalPrice": 399,
    "addedOn": "2016-04-09T18:47:49.9994325Z"
}

plan.added

This event is triggered when a plan is added to the cart. Note that the event will not be fired when the quantity of a plan is updated, only when a new plan is added to the cart.

Usage

Snipcart.subscribe('plan.added', function (plan) {
    console.log(plan);
});

Callback

The callback method contains plan details.

{
   "orderToken":"beba84c5-6a0f-4530-941d-f0b0073c66d8",
   "intervalCount":1,
   "quantity":1,
   "name":"Monthly subscription",
   "id":"PLAN_1",
   "interval":"Month",
   "amount":20,
   "url":"/",
   "metadata": {},
   "uniqueId":"01497835-1609-4b8e-b696-a8a309d92e77",
   "creationDate":"2015-11-11T00:19:17.1906135Z",
   "modificationDate":"2015-11-11T00:19:17.1906135Z",
   "trialPeriodInDays": 10,
   "firstPaymentDate":"2015-11-11T00:00:00Z",
   "amountWithTaxes":20,
   "totalAmountWithTaxes":20,
   "totalAmount":20,
   "startsOn":"2015-11-11T00:00:00Z"
}

plan.removed

This event is triggered when a plan is removed from the cart.

Usage

Snipcart.subscribe('plan.removed', function (plan) {
    console.log(plan);
});

Callback

The callback method contains plan details.

{
   "orderToken":"beba84c5-6a0f-4530-941d-f0b0073c66d8",
   "intervalCount":1,
   "quantity":1,
   "name":"Monthly subscription",
   "id":"PLAN_1",
   "interval":"Month",
   "amount":20,
   "url":"/",
   "metadata": {},
   "uniqueId":"01497835-1609-4b8e-b696-a8a309d92e77",
   "creationDate":"2015-11-11T00:19:17.1906135Z",
   "modificationDate":"2015-11-11T00:19:17.1906135Z",
   "trialPeriodInDays": 10,
   "firstPaymentDate":"2015-11-11T00:00:00Z",
   "amountWithTaxes":20,
   "totalAmountWithTaxes":20,
   "totalAmount":20,
   "startsOn":"2015-11-11T00:00:00Z"
}

page.validating

This event is triggered when saving a form. It can be used to add custom validation logic to the cart's pages.

Usage

Snipcart.subscribe('page.validating', function (ev, data) {
    if(ev.type == '{some-page}' && isValid(data)) {
        ev.addError('{field name}', 'There is an error in this field');
    }
});

Callback

The callback method will receive an event object and the data of the current page. You can use ev.preventDefault() to prevent the form from being saved or preferably ev.addError('{key}', '{message}') to show error messages.

For more information about how to use page.validating event, please look at our Javascript API Reference section about custom validation.

page.change

This event is triggered when your customer is navigating between cart tabs. It can be useful when you want to track custom events in an analytics platform.

Usage

Snipcart.subscribe('page.change', function (page) {
    console.log(page);
});

Callback

The callback method will receive the page name in string. The values can be: forgot-password, billing-address, login, order-confirm, order-details, order-infos, payment-method , shipping-address, shipping-method

page.changed

This event is triggered when a page of the cart has finished rendering and loading its data. It can be useful when you want to track custom HTML in a cart's page.

Usage

Snipcart.subscribe('page.changed', function (page) {
    console.log(page);
});

Callback

authentication.success

This event is triggered when a customer is login into the cart. You will receive the customer email in the callback method.

Usage

Snipcart.subscribe('authentication.success', function (email) {
   console.log(email);
});

Callback

The callack method will receive the user email in string.

authentication.fail

This event is triggered when a customer fails to login into the cart. You will receive the customer email in the callback method.

Usage

Snipcart.subscribe('authentication.fail', function (email) {
   console.log(email);
});

Callback

The callack method will receive the user email in string.

user.loggedout

This event is triggered when a customer logouts from the cart.

Usage

Snipcart.subscribe('user.loggedout', function () {
   console.log('User logged out');
});

shippingmethod.changed

This event is triggered when a customer changes the selected shipping method. You will receive the shipping rate information in the callback function.

Usage

Snipcart.subscribe('shippingmethod.changed', function (method) {
   console.log(method);
});

Callback

You will receive the shipping method in the callback function.

{
    "cost": 10,
    "description": "Livraison",
    "currencyCode": "CAD",
    "deliveryMessage": "5 business days",
    "guaranteedDaysToDelivery": 5,
    "slug": "livraison",
    "selected": true
}

billingaddress.changed

This event is triggerred when a customer updates the billing address. You will receive the billing address information in the callback function.

Usage

Snipcart.subscribe('billingaddress.changed', function (address) {
    console.log(address);
})

Callback

You will receive the billing address information.

{
    "name": "John Doe",
    "company": "Snipcart",
    "address1": "226 rue St-Joseph Est",
    "address2": "",
    "city": "Quebec",
    "country": "CA",
    "postalCode": "G1K3A9",
    "province": "QC",
    "phone": "",
    "email": "geeks@snipcart.com",
    "shippingSameAsBilling": true,
}

shippingaddress.changed

This event is triggerred when a customer updates the shipping address. You will receive the shipping address information in the callback function.

Usage

Snipcart.subscribe('shippingaddress.changed', function (address) {
    console.log(address);
})

Callback

You will receive the shipping address information.

{
    "name": "John Doe",
    "company": "Snipcart",
    "address1": "226 rue St-Joseph Est",
    "address2": "",
    "city": "Quebec",
    "country": "CA",
    "postalCode": "G1K3A9",
    "province": "QC",
    "phone": "",
    "email": "geeks@snipcart.com"
}

currency.changed

This event is triggered when the currency is changed. It can be useful to update your currency selector value if there is one.

Usage

Snipcart.subscribe('currency.changed', function (currency) {
  console.log('The new currency is : ' + currency);
});

Events

Was this article helpful?