Shopping Cart

Cart Functional Overview

All carts have a similar set of functions. They must be able to add items to the cart, change quantity of items in the cart and remove items from the cart. Ideally they should also be able to estimate shipping and taxes for an order and optionally allow for entry of promotional codes (aka coupons).

Because StoreBuilder is designed for customization with an open development layer, you can implement these core functions any way you like or remove/hide these functions.

Cart Implementation Details

The cart page by default will be routed to the /cart url. The cart page will be rendered using the CartViewModel class (including any mixins or extenders for customization) and the sb-cart handlebars template in your active StoreBuilder theme.

POST Request Parameters

You may POST to /cart with either a JSON payload or Form Url Encoded values payload. It the incoming request has a Content-Type:application/json header present then StoreBuilder will look for a JSON payload. If the incoming POST request has a Content-Type:application/x-www-form-urlencoded header present then StoreBuilder will look for Form values.

GET/POST Response Body

If the incoming request has an Accept:application/json header present, then StoreBuilder will return a JSON payload in the response. Otherwise StoreBuilder will return a rendered view as text/html.

If the incoming request is not requesting a json response, then StoreBuilder will additionally look for a X-Requested-With:XMLHttpRequest header to determine whether the response should be a partial view or a complete page. If the X-Requested-With:XMLHttpRequest header is present, then StoreBuilder will return the results of the handlebars template directly, otherwise Storebuilder will route the results to be "wrapped" with any (optional) surrounding view (such as wrapping the results with a Razor view to add all the surrounding page header/footer/etc).

GET/POST Response Data

The data that will either be supplied to Handlebars for rendering a template or serialized as JSON in the response body is defined by the CartViewModel and any mixins that your custom code or other plugins have added to the CartViewModel.

CartViewModel Data

The CartViewModel exposes the following data elements for use in your cart Handlebars templates.

Field Name	Data Type	Description
`Id`	Guid	The primary key for the Cart record.
`RowId`	int	A database generated int key for the cart record.
`CreatedBy`	string	The username of the user who first committed the cart record
`CreatedOn`	DateTime	The UTC DateTime the cart record was created
`CreatedOnTimestamp`	long	The UNIX timestamp the cart record was created
`ModifiedBy`	string	The username of the last user to modify the cart record
`ModifiedOn`	DateTime	The UTC DateTime the cart record was last modified
`ModifiedOnTimestamp`	long	The UNIX timestamp the cart record was last modified
`IsTrashed`	bool	Whether the cart record has been logically deleted
`ViewData`	ViewData
`StoreId`	Guid	The primary key for the Store this cart belongs to
`CurrencyId`	Guid	The primary key of the Currency this cart is using
`AccountId`	Guid?	The primary key of the Account this cart is owned by, if any
`Account`	AccountViewModel	The instance of the Account this cart is owned by, if any, if loaded from the db
`ContactId`	Guid?	The primary key of the Contact this cart is owned by, if any
`Contact`	Contact	The instance of the Contact this cart is owned by, if any, if loaded from the db
`BillingFirstName`	string	The First Name of the addressee. (Max Length: 64)
`BillingLastName`	string	The Last Name of the addressee. (Max Length: 64)
`BillingOrganization`	string	The Organization of the addressee. (Max Length: 128)
`BillingPhoneNumber`	string	The Phone Number of the addressee (Max Length: 32)
`BillingEmail`	string	The Email of the addressee (Max Length: 128)
`BillingLine1`	string	The first line for the address (Max Length: 128)
`BillingLine2`	string	The second line for this address (Max Length: 128)
`BillingCity`	string	The City for this address (Max Length: 128)
`BillingRegionId`	Guid?	The primary key for the region for this address
`BillingRegionCode`	string	A non-persisted field used for convenience. If you assign a new value here, it will try to set the RegionId when saved.
`BillingPostalCode`	string	The Postal Code or ZIP code for this address (Max Length: 16)
`BillingCountryId`	Guid?	The primary key for the country for this address
`BillingCountryCode`	string	A non-persisted field used for convenience. If you assign a new value here, it will try to set the CountryId when saved.
`BillingAddressTypeId`	Guid	The ID for the AddressType this Address is associated with (Guid.Empty = Unspecified, Commercial, Residential, PO Box).
`ShippingInfoSameAsBilling`	bool	True if the ship to party is the same as the bill to party
`ShippingFirstName`	string	The First Name of the addressee. (Max Length: 64)
`ShippingLastName`	string	The Last Name of the addressee. (Max Length: 64)
`ShippingOrganization`	string	The Organization of the addressee. (Max Length: 128)
`ShippingPhoneNumber`	string	The Phone Number of the addressee (Max Length: 32)
`ShippingEmail`	string	The Email of the addressee (Max Length: 128)
`ShippingLine1`	string	The first line for the address (Max Length: 128)
`ShippingLine2`	string	The second line for this address (Max Length: 128)
`ShippingCity`	string	The City for this address (Max Length: 128)
`ShippingRegionId`	Guid?	The primary key for the region for this address
`ShippingRegionCode`	string	A non-persisted field used for convenience. If you assign a new value here, it will try to set the RegionId when saved.
`ShippingPostalCode`	string	The Postal Code or ZIP code for this address (Max Length: 16)
`ShippingCountryId`	Guid?	The primary key for the country for this address
`ShippingCountryCode`	string	A non-persisted field used for convenience. If you assign a new value here, it will try to set the CountryId when saved.
`ShippingAddressTypeId`	Guid	The ID for the AddressType this Address is associated with (Guid.Empty = Unspecified, Commercial, Residential, PO Box).
`Items`	CartItemViewModel[]	The collection of Cart Items currently in this cart
`Items.Id`	Guid	The primary key for the Cart record.
`Items.RowId`	int	A database generated int key for the cart record.
`Items.CreatedBy`	string	The username of the user who first committed the cart record
`Items.CreatedOn`	DateTime	The UTC DateTime the cart record was created
`Items.CreatedOnTimestamp`	long	The UNIX timestamp the cart record was created
`Items.ModifiedBy`	string	The username of the last user to modify the cart record
`Items.ModifiedOn`	DateTime	The UTC DateTime the cart record was last modified
`Items.ModifiedOnTimestamp`	long	The UNIX timestamp the cart record was last modified
`Items.IsTrashed`	bool	Whether the cart record has been logically deleted
`Items.ViewData`	ViewData
`Items.CartId`	Guid	The primary key of the Cart this CartItem belongs to
`Items.CartItemGroupId`	Guid?	The primary key of the CartItemGroup this CartItem belongs to
`Items.ProductVariantId`	Guid?	The primary key of the ProductVariant this CartItem represents
`Items.Sku`	string	The "Stock keeping unit" part number of the item in the cart.
`Items.RetailSku`	string	The RETAIL "Stock keeping unit" is generally some type of part number used to track an item
`Items.OnlineSku`	string	The ONLINE "Stock keeping unit" is generally some type of part number used to track an item
`Items.Name`	string	The name of the item in the cart
`Items.Description`	string	The Description for this line item, generally copied from the ProductVariant
`Items.Quantity`	string	The quantity of this item the customer intends to purchase.
`Items.UnitPrice`	decimal	The price per unit of this item within the context of this cart (quantity and customer discounts already taken into account).
`Items.UnitPriceAmount`	string	The string value of the price per unit of this item within the context of this cart (quantity and customer discounts already taken into account).
`Items.SubTotal`	decimal	The sub total value of this cart item.
`Items.SubTotalAmount`	string	The string value of the sub total value of this cart item.
`Items.TotalDiscount`	decimal	The total value of all discounts applied to this cart item.
`Items.TotalDiscountAmount`	string	The string value of the total value of all discounts applied to this cart item.
`Items.TotalAmount`	string	The string value of the total value of this cart item.
`Items.Discounts`	CartItemDiscount[]	The collection of CartItemDiscounts currently applied to this CartItem
`Items.Url`	string	The URL for this cart item
`Items.ThumbnailUrl`	string	The URL for the main Thumbnail image for this cart item
`Items.ThumbnailAlt`	string	The Alt text for the main Thumbnail image for this cart item
`ItemGroups`	EntityCollection<CartItemGroup>	The collection of CartItemGroups currently in this cart
`Discounts`	CartDiscount[]	The collection of CartDiscounts currently in this cart
`TotalDiscount`	decimal	The sum of all discounts currently in this cart
`TotalDiscountAmount`	string	The string value of the sum of all discounts currently in this cart
`Taxes`	EntityCollection<CartTax>	The collection of CartTaxes currently in this cart
`RequiresShipping`	bool?	True if any of the items in the cart require shipping
`ShippingQuoteGroups`	CartShippingQuoteGroupViewModel[]	The collection of ShippingQuotes currently in this cart
`SelectedShippingQuoteId`	Guid?	The Id of the shipping option chosen to ship this order from all available shipping carrier quotes
`SelectedShippingQuote`	CartShippingQuoteViewModel	The shipping option chosen to ship this order from all available shipping carrier quotes.
`TotalItems`	decimal?	The number of items currently in this cart (Read Only)
`TotalValue`	decimal?	The sub total value of the cart items in this cart. (Read Only)
`TotalValueAmount`	string	The string value of the sub total value of the cart items in this cart
`TotalShipping`	decimal?	The total shipping value of this cart
`TotalShippingAmount`	string	The string value of the total shipping value of this cart
`TotalTax`	decimal?	The total tax value of this cart
`TotalTaxAmount`	string	The string value of the total tax value of this cart
`GrandTotal`	decimal?	The grand total of this cart, including taxes.
`GrandTotalAmount`	string	The string value of the grand total of this cart, including taxes.
`IsGuest`	bool	Does the cart belong to a guest
`LoginComplete`	bool	Is the user associated to this cart record logged in
`BillingAddressId`	Guid?	The primary key of the address used for billing
`BillingAddressComplete`	bool	Is the billing address provided to the cart a complete address
`ShippingAddressId`	Guid?	The primary key of the address used for shipping
`ShippingAddressComplete`	bool	Is the shipping address provided to the cart a complete address
`ReadyForShipping`	bool	True indicates we are ready to offer the customer to select a shipping quote. Shipping quotes will not be "ready" if we don't yet have proper address/delivery information.
`ReadyForPayment`	bool	True indicates we are ready for the customer to pay. We will be ready for payment after a valid shipping quote has been selected.
`ItemsLength`	int	The number of items currently in this cart (Read Only)
`ContactPaymentMethods`	ContactPaymentMethodViewModel[]	The collection of Saved Payment methods
`ContactPaymentMethodId`	Guid?	The primary key of the selected saved payment method
`PaymentValidationMessage`	string	Error message for any payment issues
`Newsletter`	bool	Register the logged in user to the stores newsletter
`AddBillingAddressToAddressBook`	bool	Add billing address to the logged in users Address book
`AddShippingAddressToAddressBook`	bool	Add shipping address to the logged in users Address book
`CouponError`	string	Error message for discount, if any
`CouponCode`	string	Discount Code currently applied to the cart