Cart

A wrapper for the Shopify AJAX cart API.

Getting started

Using Shopify Slate V1 or other ES6 project that supports imports

import Cart from 'shopify-cart';
window.cart = new Cart({ configuration })

Configuration

cart

Example

  window.cart = new Cart({ cart: window.cartJSON })

Type | Description | Default ---------|----------------------------|------------- Object | A JSON object of the cart. | null

If a cart object is no provided one will be created using an ajax request. Therefore by using this option we can improve performance by reducing the number of requests. The best way to create this cart object on page load is with liquid.

selectors

Example

window.cart = new Cart({
  selectors: {
    decreaseQuantity: '[data-minus-one]',
    increaseQuantity: '[data-plus-one]',
    addItem: '[data-add-to-cart]',
    quickAdd: '[data-quick-add]',
    quickAddQuantity: '[data-quick-add-qty]',
    quickAddProperties: '[data-quick-add-properties]',
    removeItem: '[data-remove-item]'
  }
})

[data-minus-one]

<button data-minus-one="2">
  Minus one by line index
</button>

[data-plus-one]

<button data-plus-one="2">
  Add one by line index
</button>

[data-remove-item]

<button data-remove-item="1">
  Remove by line
</button>

[data-add-to-cart]

<form>
  <input name="id" value="{{ variant.id }}" />
  <input name="quantity" value="1" /> <!-- optional, defaults to 1 -->
  <input name="properties[gift_wrap]" value="true" />
  <button data-add-to-cart="{{ variant.id }}">Add products with line item properties</button>
</form>

[data-quick-add]

<button data-quick-add="{{ variant.id }}" data-quick-add-properties='{ "gift_wrap": true }'>
  Add product
</button>

Type | Description | Default ---------|----------------------------|------------- Object | An object of css selectors. | null

If no selectors are provided the above example selectors will be used as the defaults.

options

Example

window.cart = new Cart({
  options: {
    getUrl: '/cart?view=json',
    timeout: 1000
  }
})

Type | Description | Default ---------|----------------------------|------------- Object | An object of options | null

getUrl

Type | Description | Default ---------|---------------------------------------------------------|------------- String | A url where the cart JSON should be requested from | /cart.json

The default cart response lacks information such as variant inventory or variant options. This limitation can be overcome by creating a custom cart endpoint and requesting the json from there. In this way you can customise the structure of the data too.

timeout

Type | Description | Default ----------|---------------------------------------------------------|------------- Integer | Debounce some requests by a certain amount. | 1000

The updateItemByLine method debounces requests by 1 second default. This is because these requests can be queued and sent in one request rather than making multiple requests. This is especially useful default behaviour if the site includes plus and minus quantity buttons.

Events API

There are a series of events that you can listen for from the cart.

error

Fires any time a request was unsuccessful for any reason.

document.addEventListener('cart:error', (event) => {
  console.error(event.detail.response)
})

cart:sending

Fires before a request is sent, can be useful for updating or disabling buttons before a response comes back. The response object will return the type of request that is about the be sent and the data that will be sent.

document.addEventListener('cart:sending', (event) => {
  const { response } = event.detail
})

cart:itemAdded

Fire after an item has been added to the cart. This will return the line item that was just added.

document.addEventListener('cart:itemAdded', (event) => {
  const { response } = event.detail
  console.log(response.lineItem)
})

cart:updated

Fires after the cart object has been updated. Returns the new cart object.

document.addEventListener('cart:updated', (event) => {
  const { response } = event.detail
  console.log(response.cart)
})

Methods

NOTICE: Callbacks

All methods have the option of providing custom success and error callbacks which can be useful for a host of custom behaviours. By default most will fire an event as listed above in the Events API section. By adding a custom success or error you will overwrite these events.

getCart({config})

Example

  window.cart.getCart({
    success: (cart) => {
      console.log(cart)
    },
    error: (err) => {
      console.error(err)
    }
  })

success

Default success gets a new cart object and fires a 'cart:updated' event.

addItem({item}, {config})

Example

window.cart.addItem(
  {
    id: 3284983453455,
    quantity: 1,
    properties: {
      propertyName: 'propertyValue'
    }
  },
  {
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success fires a 'cart:itemAdded' event.

removeItemById(id, {config})

Example

window.cart.addItem(3284983453455,
  {
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success gets a new cart object and fires a 'cart:updated' event.

removeItemByLine(line, {config})

line: is a the 1 indexed location of the item that you wish to remove. If you wish to remove the first item in the cart pass 1.

Example

window.cart.removeItemByLine(1,
  {
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success gets a new cart object and fires a 'cart:updated' event.

updateItemById(id, quantity, {config})

id: Id of the variant you wish to modify. quantity: The new desired quantity.

Example

window.cart.updateItemById(12345234243, 4,
  {
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success gets a new cart object and fires a 'cart:updated' event.

updateItemByLine(line, quantity, {config})

line: 1 indexed line of the variant you wish to modify. quantity: The new quantity.

Example

window.cart.updateItemByLine(1, 4,
  {
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success gets a new cart object and fires a 'cart:updated' event.

setAttributes({config})

config.attributes: Object of the attributes that you wish to modify.

Example

window.cart.setAttributes({
  attributes: {
    pickup_store_id: location.location.store_id,
    pickup_store_name: location.name
  },
  success: (item) => {
    console.log(item)
  },
  error: (err) => {
    console.error(err)
  }
})

success

Default success gets a new cart object and fires a 'cart:updated' event.

changeItemByLine(line, quantity, {config})

line: 1 indexed line of the variant you wish to modify. quantity: The new quantity.

Example

window.cart.changeItemByLine(1, 4,
  {
    properties: {
      propertyName: 'propertyValue'
    }
    beforeSend: (requestType, requestData) => {
      console.log(requestData)
    },
    success: (item) => {
      console.log(item)
    },
    error: (err) => {
      console.error(err)
    }
  }
)

success

Default success gets a new cart object and fires a 'cart:updated' event.

getShippingRates({config})

Example

window.cart.getShippingRates({
  data: 'shipping_address[zip]=3141&shipping_address[country]=Australia&shipping_address[province]=Victoria',
  success: (item) => {
    console.log(item)
  },
  error: (err) => {
    console.error(err)
  }
})

More examples

Example custom cart object with getUrl

templates/cart.json.liquid

{%- layout none -%}
{%- include 'cart-json' -%}

snippets/cart-json.liquid

{
  "token": "{{ cart.token }}",
  "note": "{{ cart.note }}",
  "attributes": {{ cart.attributes | json }},
  "original_total_price": {{ cart.original_total_price }},
  "total_price": {{ cart.total_price }},
  "total_discount": {{ cart.total_discount }},
  "total_weight": {{ cart.total_weight }},
  "item_count": {{ cart.item_count }},
  "items": [
    {%- for item in cart.items -%}
      {%- assign selected_size = item.variant.options[1]  -%}
      {%- assign selected_colour = item.variant.options[0]  -%}
      {%- capture variants -%}
        [
          {% if item.product.variants.size > 1 %}
            {%- assign first = true -%}
            {%- for variant in item.product.variants -%}
              {%- if variant.options[0] == selected_colour -%}
                {%- unless first -%},{%- endunless -%}{
                  {% assign first = false %}
                  "id": {{ variant.id }},
                  "title": {{ variant.title | json }},
                  "available": {{ variant.available }},
                  "selected": {% if variant.options[1] == selected_size %}true{% else %}false{% endif %},
                  "size": {{ variant.options[01] | json }}
                }
              {%- endif -%}
            {%- endfor -%}
          {% else %}
            {%- for variant in item.product.variants -%}
              {
                "id": {{ variant.id }},
                "title": {{ variant.title | json }},
                "available": {{ variant.available }},
                "selected": {% if variant.options[1] == selected_size %}true{% else %}false{% endif %},
                "size": {{ variant.options[1] | json }}
              }{%- unless forloop.last -%},{%- endunless -%}
            {%- endfor -%}
          {% endif %}
        ]
      {%- endcapture -%}
      {
        "id": {{ item.id }},
        "properties": { {%- for property in item.properties -%}
          "{{ property | first }}": "{{ property | last }}"{% unless forloop.last %},{% endunless -%}
        {%- endfor -%} },
        "quantity": {{ item.quantity }},
        "variant_id": {{ item.variant_id }},
        "key": "{{ item.key }}",
        "title": "{{ item.title }}",
        "price": {{ item.price }},
        "tags": {{ item.product.tags | json }},
        "original_price": {{ item.original_price }},
        "compare_at_price": {% if item.variant.compare_at_price %}{{ item.variant.compare_at_price }}{% else %}null{% endif %},
        "compare_at_line_price": {% if item.variant.compare_at_price %}{{ item.variant.compare_at_price | times: item.quantity }}{% else %}null{% endif %},
        "discounted_price": {{ item.discounted_price }},
        "line_price": {{ item.line_price }},
        "original_line_price": {{ item.original_line_price }},
        "total_discount": {{ item.total_discount }},
        "discounts": {{ item.discounts | json }},
        "sku": "{{ item.sku }}",
        "grams": {{ item.grams }},
        "vendor": "{{ item.vendor }}",
        "taxable": {{ item.taxable }},
        "product_id": {{ item.product_id }},
        "gift_card": {{ item.gift_card }},
        "url": "{{ item.url }}",
        "image": "{% if item.image == blank %}{{ settings.no_image | img_url: '500x' }}{% else %}{{ item.image | img_url: '500x' }}{% endif %}",
        "handle": "{{ item.product.handle }}",
        "requires_shipping": {{ item.requires_shipping }},
        "product_type": "{{ item.product.type }}",
        "product_title": "{{ item.product.title }}",
        "product_description": {{ item.product.description | json }},
        "variant_title": "{{ item.variant.title }}",
        "variant_options": {{ item.variant.options | json }},
        "options_with_values": {{ item.product.options_with_values | json }},
        "options": {{ item.product.options | json }},
        "inventory_quantity": {{ item.variant.inventory_quantity }},
        "inventory_policy": {{ item.variant.inventory_policy | json }},
        "selected_colour": {% if selected_colour %}"{{ selected_colour }}"{% else %}null{% endif %},
        "variants": {{ variants }}
      }{%- unless forloop.last -%},{%- endunless -%}
    {%- endfor -%}
  ]
}

License

The code is available under an ISC License.