cartRequestAdd

Performs a request to the Shopify Cart API POST /cart/add.js endpoint.

Takes the request’s body as a first parameter, the options object as the second parameter.

See what parameters Shopify expects from the request’s body in the /cart/add.js documentation.

<script type="module">
  import { cartRequestAdd } from '{{ "liquid-ajax-cart-v1.11.2.js" | asset_url }}'

  const options = {
    firstComplete: ( requestState ) => {
      // The first callback that will be called after the request is finished:
      // state object is not updated yet,
      // sections are not updated yet,
      // everything is not updated yet.
    },
    lastComplete: ( requestState ) => {
      // The last callback that will be called after the request is finished:
      // state is updated,
      // sections are updated,
      // everything is updated.
    },
    info: {
      // Any additional data you want to attach
      // Don't use the "initiator" and the "cancel" keys
      my_parameter: 'value'
    },
    newQueue: true // whether the request should go to a new or the first queue
  }

  cartRequestAdd({ 
    items: [
      {
        id: 40934235668668,
        quantity: 1
      }
    ]  
  }, options )
</script>

Options

The options parameter is an object and it might have the following properties:

firstComplete

The firstComplete parameter is a function that will be called right after the request is finished and before any other callbacks that are subscribed to the request.

This function is called before updating of the State object, the data-ajax-cart-section sections, the body CSS classes, the data-ajax-cart-bind-state elements.

The firstComplete function will be called with the only parameter — the Request state object.

lastComplete

The lastComplete parameter is a function that will be called after the request is finished and after any other callbacks that are subscribed to the request.

You can use the getCartState function to read the State object because it is already updated.

Also the data-ajax-cart-section sections, the body CSS classes, the data-ajax-cart-bind-state are updated when the function is called.

The lastComplete function will be called with the only parameter — the Request state object.

info

The info parameter is a simple Javascript object that will be attached to the Request state object. You can add your own data to the request state using the info parameter.

Don’t use the initiator and the cancel keys:

Product forms and Controls that send Cart Ajax API requests attach their HTMLElement objects to the initiator property of the info parameter.
If the info parameter has the cancel property and it is true, the request will not be performed. It might be useful when you intercept a Shopify Cart API request using the subscribeToCartAjaxRequests function and decide to cancel the request.

newQueue

If the newQueue property is true then a new queue will be created and the request will be added to the new queue. Use it for requests that get performed on user actions:

const button = document.querySelector('[data-my-button]');
if (button) {
  button.addEventListener('click', () => {
    cartRequestAdd({…}, { newQueue: true });
  })
}

If the newQueue is not defined or false, the request will be added to the end of the current queue. Use it for requests within firstComplete, lastComplete or subscribeToCartAjaxRequests callback functions when you want to have a request chain:

subscribeToCartAjaxRequests(( requestState, subscribeToResult ) => {
  if ( requestState.requestType === 'add' ) {
    subscribeToResult( requestState => {

      // The cartRequestChange depends on any "add" request —
      // the cartRequestChange should be performed right after any "add" request is finished,
      // but before any other request from a next queue is started.
      // Omit the "newQueue" parameter or set it to false:
      cartRequestChange({…});
    })
  }
});