JavaScript SDK API

The JS API allows you to retrieve relevant information about the current Snipcart session and apply certain operations to the cart.

The JS API exposes multiple services:

All async methods return promises and throw an SDKError in case of failure. If you are not familiar with the concept of promises, consider reading this introduction.

Cart

update

The update method updates the current cart's data with the provided payload argument. The payload is an object of type UpdateCartPayload.

Updates can be partial, i.e. they can contain only a subset of the fields defined in the UpdateCartPayload interface.

You can also update cart metadata with this method.

It's important to note that it's not currently possible to partially update the billing and shipping addresses, all required properties must be provided.

try {
    await Snipcart.api.cart.update({
        email: 'john.doe@example.com',
        metadata: {
            customMetadataKey: 'value'
        },
        billingAddress:{
            name: 'John Doe',
            address1: '3671 Garfield Road',
            city: 'Neponset',
            country: 'US',
            province: 'IL',
            postalCode: '61345'
        }
    });
} catch (error) {
    console.log(error);
}

applyDiscount

The applyDiscount method applies a discount to the cart. It takes a discount code as an argument and returns a promise of type DiscountAppliedResponse.

try {
    await Snipcart.api.cart.applyDiscount('{discountCode}');
} catch (error) {
    console.log(error);
}

removeDiscount

The removeDiscount method removes a discount from the cart. It takes the discount code as an argument and returns a promise of type DiscountRemovedResponse.

try {
    await Snipcart.api.cart.removeDiscount('{discountCode}');
} catch (error) {
    console.log(error);
}

fetchShippingRates

The fetchShippingRates method retrieves a list of available shipping rates for the cart and returns a promise of type ShippingRatesResponse.

try {
    const response = await Snipcart.api.cart.fetchShippingRates();
} catch (error) {
    console.log(error);
}

setShippingInformation

The setShippingInformation method provides the shipping information for the cart. It takes an argument of type ShippingInformation and returns a promise.

try {
    await Snipcart.api.cart.setShippingInformation({
        method: '{shippingMethod}',
        cost: 0,
    });
} catch (error) {
    console.log(error)
}

Items

add

The add method adds an item to the cart. It can take a ProductDefinition or multiple ProductDefinition separated by a comma as an argument and returns a promise of type CartItemAddedResponse.

try {
    await Snipcart.api.cart.items.add({
        id: 'PRODUCT_ID',
        name: 'Product 1',
        price: 1.11,
        url: '/',
        quantity: 1,
    },{
        id: 'PRODUCT2_ID',
        name: 'Product 2',
        price: 1.11,
        url: '/',
        quantity: 1,
    });
} catch (error) {
    console.log(error)
}

If you use alternate price discounts, you'll need to define these prices when adding item via our JavaScript SDK, this can be done via a property named alternatePrices. Let's say you have an alternate price list discount named: vip:

try {
    await Snipcart.api.cart.items.add({
        id: 'PRODUCT_ID',
        name: 'Product 1',
        price: 20.00,
        alternatePrices: {
            vip: 10.00
        },
        url: '/',
        quantity: 1,
    });
} catch (error) {
    console.log(error)
}

remove

The remove method removes an item from the cart. It takes the item's unique ID as a parameter and returns a promise of type CartItemRemovedResponse.

try {
    await Snipcart.api.cart.items.remove('{itemUniqueId}');
} catch (error) {
    console.log(error)
}

update

The update method updates an item in the cart. It takes an argument of type CartItem and returns a promise of type CartItemUpdatedResponse.

Please note that to update an item, the parameter uniqueId is required, this is how we'll find which product needs to be updated. The uniqueId is a guid generated on our site when an item is added to a cart.

try {
    await Snipcart.api.cart.items.update({
      uniqueId: '70f3899b-9f2b-47fa-9eb5-648f2c2ae216',
      name: 'Updated name'
    });
} catch (error) {
    console.log(error)
}

Customer

fetchOrders

The fetchOrders method retrieves a customer's order. It takes the order's token as a parameter and returns a promise of type CartResponse.

try {
    const response = await Snipcart.api.customer.fetchOrders('{orderToken}');
} catch (error) {
    console.log(error)
}

signout

The signout method will sign out the currently signed-in customer. It returns a promise of type void.

try {
    await Snipcart.api.customer.signout();
} catch (error) {
    console.log(error)
}

Theme

cart.open

The cart.open method opens the cart.

Snipcart.api.theme.cart.open()

customization.registerPaymentFormCustomization

To customize the payment form, you can use the customization.registerPaymentFormCustomization method.

  • This has to be done before the payment form is loaded.
Snipcart.api.theme.customization.registerPaymentFormCustomization({
  input: {
    backgroundColor: 'red',
    color: '#303030',
    border: '1px solid black',
    fontSize: '16px',
    placeholder: {
      color: 'blue',
    },
  },
  label: {
    color: '#fff',
    fontSize: '20px',
  }
});

cart.close

The cart.close method closes the cart.

Snipcart.api.theme.cart.close()

Was this article helpful?