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: '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);
});

Events

Was this article helpful?