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}');
app.ready
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: 'cc45d85d-e8b2-41a9-ba8a-245068607b4b',
billingAddress: {
email: 'geeks@snipcart.com',
address1: '4885 1ere Avenue',
address2: 'Floor 2',
companyname: 'Snipcart',
country: 'CA',
province: 'QC',
phone: '800 000 0000',
shippingSameAsBilling: true
},
billingAddress: {
address1: '4885 1ere Avenue',
address2: 'Floor 2',
companyname: 'Snipcart',
country: 'CA',
province: 'QC',
phone: '800 000 0000'
},
items: [{
id: 'ITEM_ID',
name: 'Poster',
price: 300,
quantity: 1,
shippable: true,
taxable: true,
uniqueId: '959664c0-e53a-46e8-9b3b-1f2b92c4e15c'
},
...],
promocodes: [{
amount: 60,
code: '20%',
rate: 20,
type: 'Rate',
name: '20% on order'
},
...],
taxes: [{
amount: 12,
numberForInvoice: 'TAX-1',
taxName: 'TPS',
taxRate: 0.05
}, {
amount: 23.94,
numberForInvoice: 'TAX-2',
taxName: 'TVQ',
taxRate: 0.09975
},
...]
subtotal: 240,
grandTotal: 275.94,
shippingMethod: {
cost: 0,
description: 'Free shipping',
guaranteedDaysToDelivery: 3
}
}
}
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: 'cc45d85d-e8b2-41a9-ba8a-245068607b4b',
billingAddress: {
email: 'geeks@snipcart.com',
address1: '4885 1ere Avenue',
address2: 'Floor 2',
companyname: 'Snipcart',
country: 'CA',
province: 'QC',
phone: '800 000 0000',
shippingSameAsBilling: true
},
billingAddress: {
address1: '4885 1ere Avenue',
address2: 'Floor 2',
companyname: 'Snipcart',
country: 'CA',
province: 'QC',
phone: '800 000 0000'
},
items: [{
id: 'ITEM_ID',
name: 'Poster',
price: 300,
quantity: 1,
shippable: true,
taxable: true,
uniqueId: '959664c0-e53a-46e8-9b3b-1f2b92c4e15c'
},
...],
promocodes: [{
amount: 60,
code: '20%',
rate: 20,
type: 'Rate',
name: '20% on order'
},
...],
taxes: [{
amount: 12,
numberForInvoice: 'TAX-1',
taxName: 'TPS',
taxRate: 0.05
}, {
amount: 23.94,
numberForInvoice: 'TAX-2',
taxName: 'TVQ',
taxRate: 0.09975
},
...]
subtotal: 240,
grandTotal: 275.94,
shippingMethod: {
cost: 0,
description: 'Free shipping',
guaranteedDaysToDelivery: 3
}
}
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: 'ITEM-ID',
isNew: true,
name: 'Your product',
price: 20.00,
quantity: 2,
shippable: true,
taxable: true,
customFields:[{
name: 'Size',
options: 'S|M|L',
type: 'dropdown',
value: 'M'
},
...],
getCustomFieldValue: function (name)
}
The third parameter is the list of the items that are already in the cart.
[{
id: 'ITEM-ID',
uniqueId: '35ccbee1-3906-40da-854d-1dc0e85fc886',
isNew: true,
name: 'Your product',
price: 20.00,
quantity: 2,
shippable: true,
taxable: true,
customFields:[{
name: 'Size',
options: 'S|M|L',
type: 'dropdown',
value: 'M'
},
...],
getCustomFieldValue: function (name)
},
...]
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: 'ITEM-ID',
uniqueId: '35ccbee1-3906-40da-854d-1dc0e85fc886',
isNew: true,
name: 'Your product',
price: 20.00,
quantity: 2,
shippable: true,
taxable: true,
customFields:[{
name: 'Size',
options: 'S|M|L',
type: 'dropdown',
value: 'M'
},
...],
getCustomFieldValue: function (name)
}
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": "ITEM-ID",
"uniqueId": "35ccbee1-3906-40da-854d-1dc0e85fc886",
"isNew": true,
"name": "Your product",
"price": 20.00,
"quantity": 2,
"shippable": true,
"taxable": true,
"customFields":[{
"name": "Size",
"options": "S|M|L",
"type": "dropdown",
"value": "M"
},
...],
getCustomFieldValue: function (name)
}
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.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
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
.
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: 20.99,
description: "UPS Express"
guaranteedDaysToDelivery: 5
slug: "ups-express"
}
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.
{
"address1": "4885 1ere Avenue",
"address2": "Suite 200",
"city": "Québec",
"companyname": "Snipcart",
"country": "CA",
"email": "geeks@snipcart.com",
"name": "Snipcart team",
"phone": "1-877-301-4813",
"postalCode": "G1H2T5",
"province": "QC",
"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.
{
address1: "4885 1ere Avenue"
address2: "Suite 200"
city: "Québec"
companyname: "Snipcart"
complete: false
country: "CA"
name: "Snipcart team"
phone: "1-877-301-4813"
postalCode: "G1H2T5"
province: "QC"
}
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);
});